Компонент <Image>

Полезно знать: Если вы используете версию Next.js до 13, обратитесь к документации next/legacy/image, так как название компонента было изменено.

Это справочник API поможет вам разобраться с использованием пропсов и параметров конфигурации, доступных для компонента Image. Подробнее о возможностях и использовании см. на странице Компонент Image.

import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="/profile.png"
      width={500}
      height={500}
      alt="Picture of the author"
    />
  )
}

Пропсы

Вот сводка пропсов, доступных для компонента Image:

Обязательные пропсы

Компонент Image требует следующие свойства: src, width, height и alt.

import Image from 'next/image'

export default function Page() {
  return (
    <div>
      <Image
        src="/profile.png"
        width={500}
        height={500}
        alt="Picture of the author"
      />
    </div>
  )
}

src

Может быть одним из следующих:

• Статически импортированный файл изображения
• Строка пути. Это может быть абсолютный внешний URL или внутренний путь в зависимости от пропса loader.

При использовании внешнего URL его необходимо добавить в remotePatterns в next.config.js.

width

Свойство width представляет отображаемую ширину в пикселях, поэтому оно влияет на размер изображения.

Обязательно, за исключением статически импортированных изображений или изображений с пропсом fill.

height

Свойство height представляет отображаемую высоту в пикселях, поэтому оно влияет на размер изображения.

Обязательно, за исключением статически импортированных изображений или изображений с пропсом fill.

alt

Свойство alt используется для описания изображения для скринридеров и поисковых систем. Это также запасной текст, если изображения отключены или произошла ошибка при загрузке.

Оно должно содержать текст, который может заменить изображение без изменения смысла страницы. Оно не предназначено для дополнения изображения и не должно повторять информацию, уже предоставленную в подписях выше или ниже изображения.

Если изображение чисто декоративное или не предназначено для пользователя, свойство alt должно быть пустой строкой (alt="").

Подробнее

Опциональные пропсы

Компонент <Image /> принимает ряд дополнительных свойств помимо обязательных. В этом разделе описаны наиболее часто используемые свойства компонента Image. Подробности о более редких свойствах см. в разделе Расширенные пропсы.

loader

Пользовательская функция, используемая для разрешения URL изображений.

loader — это функция, возвращающая строку URL для изображения, принимающая следующие параметры:

• src
• width
• quality

Вот пример использования пользовательского загрузчика:

'use client'

import Image from 'next/image'

const imageLoader = ({ src, width, quality }) => {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}

export default function Page() {
  return (
    <Image
      loader={imageLoader}
      src="me.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  )
}

Альтернативно, вы можете использовать конфигурацию loaderFile в next.config.js для настройки всех экземпляров next/image в вашем приложении без передачи пропса.

fill

fill={true} // {true} | {false}

Логическое значение, которое заставляет изображение заполнять родительский элемент, что полезно, когда width и height неизвестны.

Родительский элемент должен иметь стиль position: "relative", position: "fixed" или position: "absolute".

По умолчанию элементу img автоматически назначается стиль position: "absolute".

Если стили не применяются к изображению, изображение растянется, чтобы заполнить контейнер. Возможно, вы предпочтёте установить object-fit: "contain" для изображения, которое масштабируется с сохранением пропорций.

Альтернативно, object-fit: "cover" заставит изображение заполнить весь контейнер и обрезаться для сохранения пропорций. Чтобы это выглядело правильно, родительский элемент должен иметь стиль overflow: "hidden".

Для получения дополнительной информации см. также:

• position
• object-fit
• object-position

sizes

Строка, похожая на медиазапрос, которая предоставляет информацию о ширине изображения на разных точках останова. Значение sizes значительно влияет на производительность для изображений с fill или стилизованных под адаптивный размер.

Свойство sizes служит двум важным целям, связанным с производительностью изображений:

• Во-первых, значение sizes используется браузером для определения, какой размер изображения загрузить из автоматически сгенерированного srcset next/image. Когда браузер делает выбор, он ещё не знает размер изображения на странице, поэтому выбирает изображение того же размера или больше, чем область просмотра. Свойство sizes позволяет сообщить браузеру, что изображение на самом деле будет меньше, чем полный экран. Если вы не укажете значение sizes для изображения с пропсом fill, будет использоваться значение по умолчанию 100vw (ширина полного экрана).
• Во-вторых, свойство sizes изменяет поведение автоматически сгенерированного значения srcset. Если значение sizes отсутствует, генерируется небольшой srcset, подходящий для изображения фиксированного размера (1x/2x и т.д.). Если sizes определён, генерируется большой srcset, подходящий для адаптивного изображения (640w/750w и т.д.). Если свойство sizes включает размеры, такие как 50vw, которые представляют процент от ширины области просмотра, то srcset обрезается, чтобы исключить значения, которые слишком малы для использования.

Например, если вы знаете, что ваш стиль сделает изображение полноразмерным на мобильных устройствах, в двухколоночном макете на планшетах и трёхколоночном на десктопах, вы должны включить свойство sizes, например:

import Image from 'next/image'

export default function Page() {
  return (
    <div className="grid-element">
      <Image
        fill
        src="/example.png"
        sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
      />
    </div>
  )
}

Этот пример sizes может значительно повлиять на метрики производительности. Без 33vw выбранное с сервера изображение будет в 3 раза шире, чем необходимо. Поскольку размер файла пропорционален квадрату ширины, без sizes пользователь загрузит изображение, которое в 9 раз больше необходимого.

Подробнее о srcset и sizes:

• web.dev
• mdn

quality

quality={75} // {number 1-100}

Качество оптимизированного изображения, целое число от 1 до 100, где 100 — наилучшее качество и, следовательно, наибольший размер файла. По умолчанию 75.

priority

priority={false} // {false} | {true}

Когда true, изображение считается высокоприоритетным и предзагружается. Ленивая загрузка автоматически отключается для изображений с priority.

Свойство priority следует использовать для любого изображения, определённого как Largest Contentful Paint (LCP). Может быть уместно иметь несколько приоритетных изображений, так как разные изображения могут быть LCP-элементами для разных размеров области просмотра.

Следует использовать только для изображений, видимых выше сгиба. По умолчанию false.

placeholder

placeholder = 'empty' // "empty" | "blur" | "data:image/..."

Заполнитель, используемый во время загрузки изображения. Возможные значения: blur, empty или data:image/.... По умолчанию empty.

При blur в качестве заполнителя будет использоваться свойство blurDataURL. Если src — это объект из статического импорта и импортированное изображение имеет расширение .jpg, .png, .webp или .avif, то blurDataURL будет заполнен автоматически, за исключением случаев, когда изображение является анимированным.

Для динамических изображений вы должны предоставить свойство blurDataURL. Решения, такие как Plaiceholder, могут помочь с генерацией base64.

При data:image/... в качестве заполнителя во время загрузки изображения будет использоваться Data URL.

При empty во время загрузки изображения не будет заполнителя, только пустое пространство.

Попробуйте:

• Демо заполнителя blur
• Демо эффекта мерцания с пропсом placeholder в виде Data URL
• Демо цветового эффекта с пропсом blurDataURL

Расширенные пропсы

В некоторых случаях может потребоваться более продвинутое использование. Компонент <Image /> опционально принимает следующие расширенные свойства.

style

Позволяет передавать CSS-стили для базового элемента изображения.

const imageStyle = {
  borderRadius: '50%',
  border: '1px solid #fff',
}

export default function ProfileImage() {
  return <Image src="..." style={imageStyle} />
}

Помните, что обязательные пропсы width и height могут взаимодействовать с вашими стилями. Если вы используете стили для изменения ширины изображения, вы также должны установить его высоту в auto, чтобы сохранить исходное соотношение сторон, иначе изображение будет искажено.

onLoadingComplete

'use client'

<Image onLoadingComplete={(img) => console.log(img.naturalWidth)} />

Функция обратного вызова, которая вызывается после полной загрузки изображения и удаления заполнителя.

Функция обратного вызова будет вызвана с одним аргументом — ссылкой на базовый элемент <img>.

onLoad

<Image onLoad={(e) => console.log(e.target.naturalWidth)} />

Функция обратного вызова, которая вызывается при загрузке изображения.

Событие загрузки может произойти до удаления заполнителя изображения и полной декодировки изображения. Если вы хотите дождаться полной загрузки изображения, используйте onLoadingComplete.

onError

<Image onError={(e) => console.error(e.target.id)} />

Функция обратного вызова, которая вызывается, если изображение не загружается.

loading

Рекомендация: Это свойство предназначено только для продвинутых случаев использования. Переключение изображения на загрузку с eager обычно ухудшает производительность. Мы рекомендуем использовать свойство priority, которое предзагружает изображение.

loading = 'lazy' // {lazy} | {eager}

Поведение загрузки изображения. По умолчанию lazy.

При lazy откладывает загрузку изображения до достижения расчётного расстояния от области просмотра.

При eager загружает изображение немедленно.

Подробнее о атрибуте loading.

blurDataURL

Data URL, который будет использоваться в качестве изображения-заполнителя до успешной загрузки изображения из src. Эффект работает только в сочетании с placeholder="blur".

Должен быть изображением в кодировке base64. Оно будет увеличено и размыто, поэтому рекомендуется использовать очень маленькое изображение (10px или меньше). Использование больших изображений в качестве заполнителей может снизить производительность вашего приложения.

Попробуйте:

• Демо стандартного свойства blurDataURL
• Демо цветового эффекта с blurDataURL

Вы также можете сгенерировать Data URL однотонного цвета, чтобы он соответствовал изображению.

unoptimized

unoptimized = {false} // {false} | {true}

Если true, исходное изображение будет загружено как есть, без изменения качества, размера или формата. По умолчанию false.

import Image from 'next/image'

const UnoptimizedImage = (props) => {
  return <Image {...props} unoptimized />
}

Начиная с Next.js 12.3.0, это свойство можно применить ко всем изображениям, обновив next.config.js следующей конфигурацией:

module.exports = {
  images: {
    unoptimized: true,
  },
}

Другие свойства

Остальные свойства компонента <Image /> будут переданы базовому элементу img, за исключением следующих:

• srcSet. Вместо этого используйте Device Sizes.
• decoding. Всегда имеет значение "async".

Настройки конфигурации

В дополнение к свойствам, вы можете настроить компонент Image в next.config.js. Доступны следующие опции:

remotePatterns

Для защиты вашего приложения от злоумышленников требуется конфигурация для использования внешних изображений. Это гарантирует, что только внешние изображения из вашего аккаунта могут быть обработаны API оптимизации изображений Next.js. Эти внешние изображения можно настроить с помощью свойства remotePatterns в файле next.config.js, как показано ниже:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'example.com',
        port: '',
        pathname: '/account123/**',
      },
    ],
  },
}

Полезно знать: В примере выше свойство src компонента next/image должно начинаться с https://example.com/account123/. Любой другой протокол, хост, порт или несоответствующий путь вернут ответ 400 Bad Request.

Ниже приведен еще один пример свойства remotePatterns в файле next.config.js:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.example.com',
      },
    ],
  },
}

Полезно знать: В примере выше свойство src компонента next/image должно начинаться с https://img1.example.com, https://me.avatar.example.com или любого количества поддоменов. Любой другой протокол или несоответствующий хост вернут ответ 400 Bad Request.

Шаблоны с подстановочными знаками могут использоваться как для pathname, так и для hostname и имеют следующий синтаксис:

• * соответствует одному сегменту пути или поддомену
• ** соответствует любому количеству сегментов пути в конце или поддоменов в начале

Синтаксис ** не работает в середине шаблона.

domains

Предупреждение: Рекомендуется настраивать строгие remotePatterns вместо domains, чтобы защитить приложение от злоумышленников. Используйте domains только если вы владеете всем контентом, обслуживаемым с домена.

Аналогично remotePatterns, конфигурация domains может использоваться для предоставления списка разрешенных хостов для внешних изображений.

Однако конфигурация domains не поддерживает подстановочные знаки и не может ограничивать протокол, порт или путь.

Ниже приведен пример свойства domains в файле next.config.js:

module.exports = {
  images: {
    domains: ['assets.acme.com'],
  },
}

loaderFile

Если вы хотите использовать облачного провайдера для оптимизации изображений вместо встроенного API оптимизации изображений Next.js, вы можете настроить loaderFile в вашем next.config.js следующим образом:

module.exports = {
  images: {
    loader: 'custom',
    loaderFile: './my/image/loader.js',
  },
}

Это должно указывать на файл относительно корня вашего приложения Next.js. Файл должен экспортировать функцию по умолчанию, которая возвращает строку, например:

'use client'

export default function myImageLoader({ src, width, quality }) {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}

Альтернативно, вы можете использовать свойство loader для настройки каждого экземпляра next/image.

Примеры:

• Конфигурация пользовательского загрузчика изображений

Продвинутые настройки

Следующая конфигурация предназначена для сложных случаев использования и обычно не требуется. Если вы решите настроить свойства ниже, вы переопределите любые изменения стандартных значений Next.js в будущих обновлениях.

deviceSizes

Если вы знаете ожидаемые ширины устройств ваших пользователей, вы можете указать список точек останова ширины устройств с помощью свойства deviceSizes в next.config.js. Эти ширины используются, когда компонент next/image использует свойство sizes, чтобы гарантировать загрузку правильного изображения для устройства пользователя.

Если конфигурация не предоставлена, используется значение по умолчанию ниже.

module.exports = {
  images: {
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
  },
}

imageSizes

Вы можете указать список ширин изображений с помощью свойства images.imageSizes в вашем файле next.config.js. Эти ширины объединяются с массивом device sizes, чтобы сформировать полный массив размеров, используемых для генерации srcset изображений.

Причина разделения на два списка в том, что imageSizes используется только для изображений, которые предоставляют свойство sizes, указывающее, что изображение меньше полной ширины экрана. Поэтому размеры в imageSizes должны быть меньше, чем наименьший размер в deviceSizes.

Если конфигурация не предоставлена, используется значение по умолчанию ниже.

module.exports = {
  images: {
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
  },
}

formats

Стандартный API оптимизации изображений автоматически определяет поддерживаемые браузером форматы изображений через заголовок Accept запроса.

Если заголовок Accept соответствует более чем одному из настроенных форматов, используется первое совпадение в массиве. Поэтому порядок массива имеет значение. Если совпадений нет (или исходное изображение анимировано), API оптимизации изображений вернется к исходному формату изображения.

Если конфигурация не предоставлена, используется значение по умолчанию ниже.

module.exports = {
  images: {
    formats: ['image/webp'],
  },
}

Вы можете включить поддержку AVIF следующей конфигурацией.

module.exports = {
  images: {
    formats: ['image/avif', 'image/webp'],
  },
}

Полезно знать:

• AVIF обычно занимает на 20% больше времени для кодирования, но сжимается на 20% лучше по сравнению с WebP. Это означает, что при первом запросе изображения оно обычно будет загружаться медленнее, а последующие запросы из кэша будут быстрее.
• Если вы используете собственный хостинг с Proxy/CDN перед Next.js, вы должны настроить Proxy для пересылки заголовка Accept.

Поведение кэширования

Ниже описаны алгоритмы кэширования для стандартного загрузчика. Для всех других загрузчиков обратитесь к документации вашего облачного провайдера.

Изображения оптимизируются динамически при запросе и сохраняются в директории <distDir>/cache/images. Оптимизированное изображение будет обслуживаться для последующих запросов до истечения срока действия. Когда поступает запрос, соответствующий устаревшему, но сохраненному в кэше файлу, устаревшее изображение сразу же возвращается. Затем изображение повторно оптимизируется в фоновом режиме (так называемая ревалидация) и сохраняется в кэше с новой датой истечения срока.

Статус кэша изображения можно определить, прочитав значение заголовка ответа x-nextjs-cache. Возможные значения:

• MISS - путь отсутствует в кэше (происходит максимум один раз при первом посещении)
• STALE - путь есть в кэше, но превышено время ревалидации, поэтому он будет обновлен в фоновом режиме
• HIT - путь есть в кэше и не превышено время ревалидации

Срок действия (или, точнее, Max Age) определяется либо конфигурацией minimumCacheTTL, либо заголовком Cache-Control исходного изображения, в зависимости от того, что больше. Конкретно используется значение max-age заголовка Cache-Control. Если найдены и s-maxage, и max-age, предпочтение отдается s-maxage. Значение max-age также передается всем нижестоящим клиентам, включая CDN и браузеры.

• Вы можете настроить minimumCacheTTL, чтобы увеличить срок кэширования, когда исходное изображение не включает заголовок Cache-Control или значение слишком мало.
• Вы можете настроить deviceSizes и imageSizes, чтобы уменьшить общее количество возможных сгенерированных изображений.
• Вы можете настроить formats, чтобы отключить несколько форматов в пользу одного.

minimumCacheTTL

Вы можете настроить Time to Live (TTL) в секундах для кэшированных оптимизированных изображений. Во многих случаях лучше использовать Статический импорт изображений, который автоматически хеширует содержимое файла и кэширует изображение навсегда с заголовком Cache-Control со значением immutable.

module.exports = {
  images: {
    minimumCacheTTL: 60,
  },
}

Срок действия (Max Age) оптимизированного изображения определяется либо minimumCacheTTL, либо заголовком Cache-Control исходного изображения, в зависимости от того, что больше.

Если вам нужно изменить поведение кэширования для конкретного изображения, вы можете настроить headers, чтобы установить заголовок Cache-Control для исходного изображения (например, /some-asset.jpg, а не /_next/image).

На данный момент нет механизма для инвалидации кэша, поэтому лучше держать minimumCacheTTL небольшим. В противном случае вам может потребоваться вручную изменить свойство src или удалить <distDir>/cache/images.

disableStaticImages

Стандартное поведение позволяет импортировать статические файлы, такие как import icon from './icon.png', а затем передавать их в свойство src.

В некоторых случаях вам может потребоваться отключить эту функцию, если она конфликтует с другими плагинами, которые ожидают другого поведения импорта.

Вы можете отключить статический импорт изображений в вашем next.config.js:

module.exports = {
  images: {
    disableStaticImages: true,
  },
}

dangerouslyAllowSVG

Стандартный загрузчик не оптимизирует SVG изображения по нескольким причинам. Во-первых, SVG - это векторный формат, который можно масштабировать без потерь. Во-вторых, SVG имеет много общих функций с HTML/CSS, что может привести к уязвимостям без правильной Политики безопасности контента.

Если вам нужно обслуживать SVG изображения с помощью стандартного API оптимизации изображений, вы можете установить dangerouslyAllowSVG в вашем next.config.js:

module.exports = {
  images: {
    dangerouslyAllowSVG: true,
    contentDispositionType: 'attachment',
    contentSecurityPolicy: "default-src 'self'; script-src 'none'; sandbox;",
  },
}

Кроме того, настоятельно рекомендуется также установить contentDispositionType, чтобы заставить браузер загружать изображение, и contentSecurityPolicy, чтобы предотвратить выполнение скриптов, встроенных в изображение.

Анимированные изображения

Стандартный загрузчик автоматически пропускает оптимизацию для анимированных изображений и обслуживает их как есть.

Автоопределение анимированных файлов работает по принципу best-effort и поддерживает GIF, APNG и WebP. Если вы хотите явно отключить оптимизацию для конкретного анимированного изображения, используйте свойство unoptimized.

Адаптивные изображения

Стандартно генерируемый srcset содержит изображения 1x и 2x для поддержки различных плотностей пикселей устройств. Однако вам может потребоваться отобразить адаптивное изображение, которое растягивается вместе с областью просмотра. В этом случае вам нужно установить sizes, а также style (или className).

Вы можете отобразить адаптивное изображение одним из следующих способов.

Адаптивное изображение со статическим импортом

Если исходное изображение не динамическое, вы можете использовать статический импорт для создания адаптивного изображения:

import Image from 'next/image'
import me from '../photos/me.jpg'

export default function Author() {
  return (
    <Image
      src={me}
      alt="Picture of the author"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
    />
  )
}

Попробуйте:

• Демо адаптивного изображения к области просмотра

Адаптивное изображение с соотношением сторон

Если исходное изображение динамическое или является удаленным URL, вам также нужно указать width и height, чтобы установить правильное соотношение сторон адаптивного изображения:

import Image from 'next/image'

export default function Page({ photoUrl }) {
  return (
    <Image
      src={photoUrl}
      alt="Picture of the author"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
      width={500}
      height={300}
    />
  )
}

Попробуйте:

• Демо адаптивного изображения к области просмотра

Адаптивное изображение с fill

Если вы не знаете соотношение сторон, вам нужно установить свойство fill и position: relative для родительского элемента. Опционально вы можете установить object-fit в зависимости от желаемого поведения растяжения или обрезки:

import Image from 'next/image'

export default function Page({ photoUrl }) {
  return (
    <div style={{ position: 'relative', width: '500px', height: '300px' }}>
      <Image
        src={photoUrl}
        alt="Picture of the author"
        sizes="500px"
        fill
        style={{
          objectFit: 'contain',
        }}
      />
    </div>
  )
}

Попробуйте:

• Демо свойства fill

Определение темы

Если вы хотите отображать разные изображения для светлой и тёмной темы, можно создать новый компонент, который оборачивает два компонента <Image> и показывает нужный на основе CSS media query.

.imgDark {
  display: none;
}

@media (prefers-color-scheme: dark) {
  .imgLight {
    display: none;
  }
  .imgDark {
    display: unset;
  }
}

import styles from './theme-image.module.css'
import Image, { ImageProps } from 'next/image'

type Props = Omit<ImageProps, 'src' | 'priority' | 'loading'> & {
  srcLight: string
  srcDark: string
}

const ThemeImage = (props: Props) => {
  const { srcLight, srcDark, ...rest } = props

  return (
    <>
      <Image {...rest} src={srcLight} className={styles.imgLight} />
      <Image {...rest} src={srcDark} className={styles.imgDark} />
    </>
  )
}

import styles from './theme-image.module.css'
import Image from 'next/image'

const ThemeImage = (props) => {
  const { srcLight, srcDark, ...rest } = props

  return (
    <>
      <Image {...rest} src={srcLight} className={styles.imgLight} />
      <Image {...rest} src={srcDark} className={styles.imgDark} />
    </>
  )
}

Полезно знать: Поведение по умолчанию loading="lazy" гарантирует, что загружается только правильное изображение. Нельзя использовать priority или loading="eager", так как это приведёт к загрузке обоих изображений. Вместо этого можно использовать fetchPriority="high".

Попробуйте:

• Демо определения темы (светлая/тёмная)

Известные ошибки браузеров

Компонент next/image использует нативную ленивую загрузку (lazy loading) браузера, которая может переключаться на eager loading в старых браузерах до Safari 15.4. При использовании размытого плейсхолдера (blur-up placeholder) в браузерах до Safari 12 будет показываться пустой плейсхолдер. При использовании стилей с width/height в auto возможен Layout Shift в старых браузерах до Safari 15, которые не сохраняют соотношение сторон. Подробнее см. это видео на MDN.

• Safari 15 - 16.3 отображают серую рамку во время загрузки. В Safari 16.4 эта проблема исправлена. Возможные решения:
  • Использовать CSS @supports (font: -apple-system-body) and (-webkit-appearance: none) { img[loading="lazy"] { clip-path: inset(0.6px) } }
  • Использовать priority, если изображение находится выше сгиба (above the fold)
• Firefox 67+ отображает белый фон во время загрузки. Возможные решения:
  • Включить AVIF formats
  • Использовать placeholder

История версий