Image

Компонент Image в Next.js расширяет HTML-элемент <img> для автоматической оптимизации изображений.

import Image from 'next/image'

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

Справочник

Пропсы

Доступны следующие пропсы:

src

Источник изображения. Может быть одним из следующих:

Строка с внутренним путем.

<Image src="/profile.png" />

Абсолютный внешний URL (должен быть настроен с remotePatterns).

<Image src="https://example.com/profile.png" />

Статический импорт.

import profile from './profile.png'

export default function Page() {
  return <Image src={profile} />
}

alt

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

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

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

Узнайте больше о рекомендациях по доступности изображений.

width и height

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

<Image src="/profile.png" width={500} height={500} />

Вы должны указать оба свойства width и height, за исключением случаев:

• Изображение импортировано статически
• Изображение имеет свойство fill

Если высота и ширина неизвестны, рекомендуется использовать свойство fill.

fill

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

<Image src="/profile.png" fill={true} />

Позиционирование:

• Родительский элемент должен иметь position: "relative", "fixed", "absolute".
• По умолчанию элемент <img> использует position: "absolute".

Object Fit:

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

• "contain": Изображение будет масштабировано, чтобы поместиться в контейнер, сохраняя соотношение сторон.
• "cover": Изображение заполнит контейнер и будет обрезано.

Узнайте больше о position и object-fit.

loader

Пользовательская функция, используемая для генерации URL изображения. Функция получает следующие параметры и возвращает строку 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}
    />
  )
}

Полезно знать: Использование пропсов, таких как onLoad, которые принимают функцию, требует использования Клиентских компонентов для сериализации предоставленной функции.

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

sizes

Определяет размеры изображения на разных контрольных точках. Используется браузером для выбора наиболее подходящего размера из сгенерированного srcset.

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 следует использовать, когда:

• Изображение использует пропс fill
• CSS используется для создания адаптивного изображения

Если sizes отсутствует, браузер предполагает, что изображение будет такой же ширины, как область просмотра (100vw). Это может привести к загрузке излишне больших изображений.

Кроме того, sizes влияет на генерацию srcset:

• Без sizes: Next.js генерирует ограниченный srcset (например, 1x, 2x), подходящий для изображений фиксированного размера.
• С sizes: Next.js генерирует полный srcset (например, 640w, 750w и т.д.), оптимизированный для адаптивных макетов.

Узнайте больше о srcset и sizes на web.dev и mdn.

quality

Целое число от 1 до 100, которое устанавливает качество оптимизированного изображения. Более высокие значения увеличивают размер файла и визуальное качество. Более низкие значения уменьшают размер файла, но могут повлиять на резкость.

// Качество по умолчанию — 75
<Image quality={75} />

Если вы настроили qualities в next.config.js, значение должно соответствовать одному из разрешенных вариантов.

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

style

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

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

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

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

priority

Логическое значение, указывающее, должно ли изображение быть предзагружено.

// Приоритет по умолчанию — false
<Image priority={false} />

• true: Предзагружает изображение. Отключает ленивую загрузку.
• false: Лениво загружает изображение.

Когда использовать:

• Изображение находится выше сгиба.
• Изображение является элементом Largest Contentful Paint (LCP).
• Вы хотите улучшить начальную производительность загрузки страницы.

Когда не использовать:

• Когда используется пропс loading (это вызовет предупреждения).

loading

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

// По умолчанию — lazy
<Image loading="lazy" />

• lazy: Откладывает загрузку изображения до тех пор, пока оно не окажется на расчетном расстоянии от области просмотра.
• eager: Загружает изображение немедленно, независимо от его положения на странице.

Используйте eager только тогда, когда хотите гарантировать немедленную загрузку изображения.

Узнайте больше об атрибуте loading.

placeholder

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

// По умолчанию — empty
<Image placeholder="empty" />

• empty: Нет заполнителя во время загрузки изображения.
• blur: Использует размытую версию изображения в качестве заполнителя. Должен использоваться со свойством blurDataURL.
• data:image/...: Использует Data URL в качестве заполнителя.

Примеры:

• Заполнитель blur
• Эффект мерцания с пропсом placeholder в виде Data URL
• Цветовой эффект с пропсом blurDataURL

Узнайте больше об атрибуте placeholder.

blurDataURL

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

<Image placeholder="blur" blurDataURL="..." />

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

Автоматически

Если src является статическим импортом файлов jpg, png, webp или avif, blurDataURL добавляется автоматически — если изображение не анимировано.

Установка вручную

Если изображение динамическое или удаленное, вы должны предоставить blurDataURL самостоятельно. Для его генерации вы можете использовать:

• Онлайн-инструменты, такие как png-pixel.com
• Библиотеки, такие как Plaiceholder

Большой blurDataURL может ухудшить производительность. Держите его маленьким и простым.

Примеры:

• Пропс blurDataURL по умолчанию
• Цветовой эффект с пропсом blurDataURL

onLoad

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

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

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

Полезно знать: Использование пропсов, таких как onLoad, которые принимают функцию, требует использования Клиентских компонентов для сериализации предоставленной функции.

onError

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

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

Полезно знать: Использование пропсов, таких как onError, которые принимают функцию, требует использования Клиентских компонентов для сериализации предоставленной функции.

unoptimized

Логическое значение, указывающее, должно ли изображение быть оптимизировано. Это полезно для изображений, которые не выигрывают от оптимизации, таких как маленькие изображения (менее 1 КБ), векторные изображения (SVG) или анимированные изображения (GIF).

import Image from 'next/image'

const UnoptimizedImage = (props) => {
  // По умолчанию — false
  return <Image {...props} unoptimized />
}

• true: Исходное изображение будет обслуживаться как есть из src без изменения качества, размера или формата.
• false: Исходное изображение будет оптимизировано.

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

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

overrideSrc

При передаче пропса src компоненту <Image>, атрибуты srcset и src генерируются автоматически для результирующего <img>.

<Image src="/profile.jpg" />

<img
  srcset="
    /_next/image?url=%2Fme.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fme.jpg&w=828&q=75 2x
  "
  src="/_next/image?url=%2Fme.jpg&w=828&q=75"
/>

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

Например, при обновлении существующего веб-сайта с <img> на <Image>, вы можете захотеть сохранить тот же атрибут src для целей SEO, таких как ранжирование изображений или избежание повторного сканирования.

<Image src="/profile.jpg" overrideSrc="/override.jpg" />

<img
  srcset="
    /_next/image?url=%2Fme.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fme.jpg&w=828&q=75 2x
  "
  src="/override.jpg"
/>

decoding

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

// По умолчанию — async
<Image decoding="async" />

• async: Асинхронно декодировать изображение и разрешить отображение другого контента до завершения.
• sync: Синхронно декодировать изображение для атомарного отображения с другим контентом.
• auto: Нет предпочтений. Браузер выбирает лучший подход.

Узнайте больше об атрибуте decoding.

Другие пропсы

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

• srcSet: Вместо этого используйте Device Sizes.

Устаревшие пропсы

onLoadingComplete

Предупреждение: Устарело в Next.js 14, используйте вместо этого onLoad.

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

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

'use client'

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

Полезно знать: Использование пропсов, таких как onLoadingComplete, которые принимают функцию, требует использования Клиентских Компонентов (Client Components) для сериализации предоставленной функции.

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

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

localPatterns

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

module.exports = {
  images: {
    localPatterns: [
      {
        pathname: '/assets/images/**',
        search: '',
      },
    ],
  },
}

Приведенный выше пример гарантирует, что свойство src в next/image должно начинаться с /assets/images/ и не должно содержать строки запроса. Попытка оптимизировать любой другой путь вернет ошибку 400 Bad Request.

remotePatterns

Используйте remotePatterns в файле next.config.js, чтобы разрешить изображения из определенных внешних путей и заблокировать все остальные. Это гарантирует, что будут обслуживаться только внешние изображения с вашего аккаунта.

module.exports = {
  images: {
    remotePatterns: [new URL('https://example.com/account123/**')],
  },
}

Если используется версия ниже 15.3.0, можно настроить remotePatterns с помощью объекта:

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

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

Шаблоны с подстановочными знаками:

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

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

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

Это разрешает поддомены, такие как image.example.com. Строки запроса и пользовательские порты по-прежнему блокируются.

Полезно знать: Если опустить protocol, port, pathname или search, то подразумевается подстановочный знак **. Это не рекомендуется, так как может позволить злоумышленникам оптимизировать URL-адреса, которые вы не планировали.

Строки запроса:

Вы также можете ограничить строки запроса с помощью свойства search:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'assets.example.com',
        search: '?v=1727111025337',
      },
    ],
  },
}

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

loaderFile

loaderFiles позволяет использовать пользовательский сервис оптимизации изображений вместо Next.js.

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

Путь должен быть относительным к корню проекта. Файл должен экспортировать функцию по умолчанию, которая возвращает строку URL:

'use client'

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

Пример:

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

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

deviceSizes

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

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

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

imageSizes

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

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

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

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

qualities

qualities позволяет указать список значений качества изображения.

module.exports = {
  images: {
    qualities: [25, 50, 75],
  },
}

В приведенном выше примере разрешены только три уровня качества: 25, 50 и 75. Если проп quality не соответствует значению в этом массиве, изображение не загрузится с ошибкой 400 Bad Request.

formats

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

module.exports = {
  images: {
    // По умолчанию
    formats: ['image/webp'],
  },
}

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

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

Вы можете включить поддержку AVIF, который вернется к исходному формату изображения, если браузер не поддерживает AVIF:

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

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

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

minimumCacheTTL

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

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

module.exports = {
  images: {
    minimumCacheTTL: 60, // 1 минута
  },
}

Вы можете увеличить TTL, чтобы уменьшить количество повторных проверок и потенциально снизить затраты:

module.exports = {
  images: {
    minimumCacheTTL: 2678400, // 31 день
  },
}

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

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

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

disableStaticImages

disableStaticImages позволяет отключить статический импорт изображений.

Поведение по умолчанию позволяет импортировать статические файлы, такие как import icon from './icon.png', а затем передавать их в свойство src. В некоторых случаях может потребоваться отключить эту функцию, если она конфликтует с другими плагинами, которые ожидают другого поведения импорта.

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

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

dangerouslyAllowSVG

dangerouslyAllowSVG позволяет обслуживать SVG-изображения.

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

По умолчанию Next.js не оптимизирует SVG-изображения по нескольким причинам:

• SVG — это векторный формат, что означает, что его можно масштабировать без потерь.
• SVG имеет много общих функций с HTML/CSS, что может привести к уязвимостям без правильных заголовков Content Security Policy (CSP).

Мы рекомендуем использовать проп unoptimized, когда известно, что проп src содержит SVG. Это происходит автоматически, если src заканчивается на ".svg".

<Image src="/my-image.svg" unoptimized />

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

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

contentDispositionType

contentDispositionType позволяет настроить заголовок Content-Disposition.

module.exports = {
  images: {
    contentDispositionType: 'inline',
  },
}

По умолчанию загрузчик устанавливает заголовок Content-Disposition в значение attachment для дополнительной защиты, так как API может обслуживать произвольные удаленные изображения.

Значение по умолчанию — attachment, что заставляет браузер загружать изображение при прямом посещении. Это особенно важно, когда dangerouslyAllowSVG имеет значение true.

Вы можете настроить inline, чтобы разрешить браузеру отображать изображение при прямом посещении без загрузки.

Устаревшие настройки конфигурации

domains

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

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

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

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

Функции

getImageProps

Функция getImageProps может использоваться для получения пропсов, которые будут переданы базовому элементу <img>, и их передачи другому компоненту, стилю, canvas и т. д.

import { getImageProps } from 'next/image'

const props = getImageProps({
  src: 'https://example.com/image.jpg',
  alt: 'A scenic mountain view',
  width: 1200,
  height: 800,
})

function ImageWithCaption() {
  return (
    <figure>
      <img {...props} />
      <figcaption>A scenic mountain view</figcaption>
    </figure>
  )
}

Это также позволяет избежать вызова React useState(), что может улучшить производительность, но не может использоваться с пропом placeholder, так как заполнитель никогда не будет удален.

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

Компонент next/image использует нативную для браузеров ленивую загрузку (lazy loading), которая может переключаться на жадную загрузку для старых браузеров до Safari 15.4. При использовании заполнителя с размытием (blur-up) старые браузеры до 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, если изображение находится выше сгиба

• Firefox 67+ отображает белый фон во время загрузки. Возможные решения:

  • Включите AVIF formats
  • Используйте placeholder

Примеры

Стилизация изображений

Стилизация компонента Image похожа на стилизацию обычного элемента <img>, но есть несколько рекомендаций:

Используйте className или style, а не styled-jsx. В большинстве случаев мы рекомендуем использовать проп className. Это может быть импортированный CSS Module, глобальная таблица стилей и т. д.

import styles from './styles.module.css'

export default function MyImage() {
  return <Image className={styles.image} src="/my-image.png" alt="My Image" />
}

Вы также можете использовать проп style для назначения встроенных стилей.

export default function MyImage() {
  return (
    <Image style={{ borderRadius: '8px' }} src="/my-image.png" alt="My Image" />
  )
}

При использовании fill родительский элемент должен иметь position: relative или display: block. Это необходимо для правильного отображения элемента изображения в этом режиме макета.

<div style={{ position: 'relative' }}>
  <Image fill src="/my-image.png" alt="My Image" />
</div>

Вы не можете использовать styled-jsx, так как он ограничен текущим компонентом (если только вы не пометите стиль как global).

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

При импорте статического изображения Next.js автоматически устанавливает его ширину и высоту на основе файла. Вы можете сделать изображение адаптивным, задав стиль:

import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Responsive() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column' }}>
      <Image
        alt="Горы"
        // Импорт изображения автоматически
        // установит ширину и высоту
        src={mountains}
        sizes="100vw"
        // Сделать изображение на всю ширину
        // с сохранением пропорций
        style={{
          width: '100%',
          height: 'auto',
        }}
      />
    </div>
  )
}

Адаптивные изображения с удалённым URL

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

import Image from 'next/image'

export default function Page({ photoUrl }) {
  return (
    <Image
      src={photoUrl}
      alt="Фото автора"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
      width={500}
      height={300}
    />
  )
}

Попробуйте:

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

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

Если вы не знаете соотношение сторон изображения, вы можете добавить проп fill с пропсом objectFit, установленным в cover. Это заставит изображение заполнить всю ширину родительского контейнера.

import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Fill() {
  return (
    <div
      style={{
        display: 'grid',
        gridGap: '8px',
        gridTemplateColumns: 'repeat(auto-fit, minmax(400px, auto))',
      }}
    >
      <div style={{ position: 'relative', width: '400px' }}>
        <Image
          alt="Горы"
          src={mountains}
          fill
          sizes="(min-width: 808px) 50vw, 100vw"
          style={{
            objectFit: 'cover', // cover, contain, none
          }}
        />
      </div>
      {/* И другие изображения в сетке... */}
    </div>
  )
}

Фоновое изображение

Используйте проп fill, чтобы изображение покрыло всю область экрана:

import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Background() {
  return (
    <Image
      alt="Горы"
      src={mountains}
      placeholder="blur"
      quality={100}
      fill
      sizes="100vw"
      style={{
        objectFit: 'cover',
      }}
    />
  )
}

Примеры использования компонента Image с различными стилями можно посмотреть в демо компонента Image.

Удалённые изображения

Для использования удалённого изображения свойство src должно быть строкой URL.

import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="https://s3.amazonaws.com/my-bucket/profile.png"
      alt="Фото автора"
      width={500}
      height={500}
    />
  )
}

Поскольку Next.js не имеет доступа к удалённым файлам во время сборки, вам нужно вручную указать пропсы width, height и опционально blurDataURL.

Атрибуты width и height используются для определения правильного соотношения сторон изображения и предотвращения сдвига макета при загрузке изображения. width и height не определяют размер отображаемого файла изображения.

Для безопасной оптимизации изображений определите список поддерживаемых шаблонов URL в next.config.js. Будьте как можно более конкретными, чтобы предотвратить злоупотребления. Например, следующая конфигурация разрешит только изображения из определённого бакета AWS S3:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 's3.amazonaws.com',
        port: '',
        pathname: '/my-bucket/**',
        search: '',
      },
    ],
  },
}

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

Если вы хотите отображать разные изображения для светлой и тёмной темы, вы можете создать новый компонент, который оборачивает два компонента <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".

Попробуйте:

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

Арт-дирекшн

Если вы хотите отображать разные изображения для мобильных и десктопных устройств (иногда это называется арт-дирекшн), вы можете передать разные src, width, height и quality в getImageProps().

import { getImageProps } from 'next/image'

export default function Home() {
  const common = { alt: 'Пример арт-дирекшна', sizes: '100vw' }
  const {
    props: { srcSet: desktop },
  } = getImageProps({
    ...common,
    width: 1440,
    height: 875,
    quality: 80,
    src: '/desktop.jpg',
  })
  const {
    props: { srcSet: mobile, ...rest },
  } = getImageProps({
    ...common,
    width: 750,
    height: 1334,
    quality: 70,
    src: '/mobile.jpg',
  })

  return (
    <picture>
      <source media="(min-width: 1000px)" srcSet={desktop} />
      <source media="(min-width: 500px)" srcSet={mobile} />
      <img {...rest} style={{ width: '100%', height: 'auto' }} />
    </picture>
  )
}

Фоновый CSS

Вы даже можете преобразовать строку srcSet в CSS-функцию image-set() для оптимизации фонового изображения.

import { getImageProps } from 'next/image'

function getBackgroundImage(srcSet = '') {
  const imageSet = srcSet
    .split(', ')
    .map((str) => {
      const [url, dpi] = str.split(' ')
      return `url("${url}") ${dpi}`
    })
    .join(', ')
  return `image-set(${imageSet})`
}

export default function Home() {
  const {
    props: { srcSet },
  } = getImageProps({ alt: '', width: 128, height: 128, src: '/img.png' })
  const backgroundImage = getBackgroundImage(srcSet)
  const style = { height: '100vh', width: '100vw', backgroundImage }

  return (
    <main style={style}>
      <h1>Hello World</h1>
    </main>
  )
}

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