Image

Next.jsのImageコンポーネントは、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"を使用します。

オブジェクトフィット:

画像にスタイルが適用されていない場合、画像はコンテナに合わせて伸縮します。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のように関数を受け取るプロパティを使用するには、提供された関数をシリアライズするためにクライアントコンポーネントを使用する必要があります。

あるいは、next.config.jsでloaderFile設定を使用して、プロパティを渡さずにアプリケーション内のすべての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} />

next.config.jsでqualitiesを設定している場合、値は許可されたエントリの1つと一致する必要があります。

知っておくと便利: 元の画像がすでに低品質の場合、高い品質値を設定しても見た目が改善されずにファイルサイズが増加します。

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

画像をプリロードするかどうかを示すブール値。

// デフォルトの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プレースホルダー
• Data URL placeholderプロパティを使用したシャイマー効果
• 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)} />

コールバック関数は、基礎となる<img>要素を参照するtargetを持つイベントを1つの引数として呼び出されます。

知っておくと便利: onLoadのように関数を受け取るプロパティを使用するには、提供された関数をシリアライズするためにクライアントコンポーネントを使用する必要があります。

onError

画像の読み込みに失敗した場合に呼び出されるコールバック関数。

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

知っておくと便利: onErrorのように関数を受け取るプロパティを使用するには、提供された関数をシリアライズするためにクライアントコンポーネントを使用する必要があります。

unoptimized

画像を最適化するかどうかを示すブール値。これは、最適化の恩恵を受けない小さな画像（1KB未満）、ベクター画像（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

<Image>コンポーネントにsrcプロパティを提供すると、結果の<img>に対してsrcsetとsrc属性の両方が自動的に生成されます。

<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>にアップグレードする場合、画像ランキングや再クロールを避けるなどのSEO目的で同じsrc属性を維持したい場合があります。

<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: 代わりにデバイスサイズを使用してください。

非推奨のプロパティ

onLoadingComplete

警告: Next.js 14 で非推奨となりました。代わりに onLoad を使用してください。

画像が完全に読み込まれ、プレースホルダーが削除された後に呼び出されるコールバック関数です。

コールバック関数は、基盤となる <img> 要素への参照を引数として受け取ります。

'use client'

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

豆知識: onLoadingComplete のように関数を受け取るプロパティを使用する場合、提供された関数をシリアライズするために クライアントコンポーネント を使用する必要があります。

設定オプション

Image コンポーネントは next.config.js で設定できます。以下のオプションが利用可能です:

localPatterns

next.config.js ファイルで localPatterns を使用して、特定のローカルパスからの画像の最適化を許可し、他のすべてをブロックします。

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

上記の例では、next/image の src プロパティが /assets/images/ で始まり、クエリ文字列を持たないことを保証します。他のパスを最適化しようとすると 400 Bad Request エラーが返されます。

remotePatterns

next.config.js ファイルで remotePatterns を使用して、特定の外部パスからの画像を許可し、他のすべてをブロックします。これにより、アカウントからの外部画像のみが提供されるようになります。

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: '',
      },
    ],
  },
}

上記の例では、next/image の src プロパティが 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',
      },
    ],
  },
}

上記の例では、next/image の src プロパティが 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の3つの品質のみが許可されます。quality プロパティがこの配列の値と一致しない場合、画像は 400 Bad Request で失敗します。

formats

formats を使用すると、使用する画像フォーマットのリストを指定できます。

module.exports = {
  images: {
    // デフォルト
    formats: ['image/webp'],
  },
}

Next.js は、リクエストの Accept ヘッダーを介してブラウザでサポートされている画像フォーマットを自動的に検出し、最適な出力フォーマットを決定します。

Accept ヘッダーが設定されたフォーマットの複数と一致する場合、配列内の最初の一致が使用されます。したがって、配列の順序が重要です。一致がない場合（またはソース画像がアニメーションの場合）、元の画像のフォーマットが使用されます。

AVIF サポートを有効にすることができます。これは、ブラウザが AVIF をサポートしていない 場合に src 画像の元のフォーマットにフォールバックします:

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

豆知識:

• ほとんどのユースケースでは WebP の使用を推奨します。
• AVIF は一般的にエンコードに50%長くかかりますが、WebP と比較して20%小さく圧縮されます。つまり、画像が最初にリクエストされたときは通常遅くなりますが、キャッシュされた後続のリクエストは高速になります。
• Next.js の前に Proxy/CDN を自己ホストしている場合、Accept ヘッダーを転送するように Proxy を設定する必要があります。

minimumCacheTTL

minimumCacheTTL を使用すると、キャッシュされた最適化画像の Time to Live (TTL) を秒単位で設定できます。多くの場合、ファイル内容を自動的にハッシュし、Cache-Control ヘッダーを immutable として画像を永久にキャッシュする 静的画像インポート を使用する方が良いです。

設定が提供されていない場合、以下のデフォルトが使用されます。

module.exports = {
  images: {
    minimumCacheTTL: 60, // 1分
  },
}

TTL を増やして再検証の回数を減らし、コストを下げることができます:

module.exports = {
  images: {
    minimumCacheTTL: 2678400, // 31日
  },
}

最適化された画像の有効期限（またはむしろ Max Age）は、minimumCacheTTL またはアップストリーム画像の Cache-Control ヘッダーのいずれか大きい方によって定義されます。

画像ごとにキャッシュ動作を変更する必要がある場合、アップストリーム画像（例: /_next/image 自体ではなく /some-asset.jpg）に Cache-Control ヘッダーを設定するために headers を設定できます。

現時点ではキャッシュを無効化するメカニズムがないため、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) ヘッダー がないと脆弱性につながる可能性があります。

src プロパティが SVG であることがわかっている場合は、unoptimized プロパティを使用することを推奨します。これは 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',
  },
}

デフォルトでは、ローダー は API が任意のリモート画像を提供できるため、追加の保護として Content-Disposition ヘッダーを attachment に設定します。

デフォルト値は attachment で、直接訪問したときにブラウザに画像をダウンロードさせます。これは dangerouslyAllowSVG が true の場合に特に重要です。

inline を設定すると、直接訪問したときにブラウザが画像をダウンロードせずにレンダリングできるようになります。

非推奨の設定オプション

domains

警告: 悪意のあるユーザーからアプリケーションを保護するために、Next.js 14 以降では厳密な remotePatterns が推奨されます。ドメインから提供されるすべてのコンテンツを所有している場合にのみ domains を使用してください。

remotePatterns と同様に、domains 設定を使用して、外部画像の許可されたホスト名のリストを提供できます。ただし、domains 設定はワイルドカードパターンマッチングをサポートしておらず、プロトコル、ポート、またはパス名を制限できません。

以下は next.config.js ファイル内の domains プロパティの例です:

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

関数

getImageProps

getImageProps 関数を使用すると、基盤となる <img> 要素に渡されるプロパティを取得し、それらを別のコンポーネント、スタイル、キャンバスなどに渡すことができます。

import { getImageProps } from 'next/image'

const props = getImageProps({
  src: 'https://example.com/image.jpg',
  alt: '山の景色',
  width: 1200,
  height: 800,
})

function ImageWithCaption() {
  return (
    <figure>
      <img {...props} />
      <figcaption>山の景色</figcaption>
    </figure>
  )
}

これにより React の useState() も呼び出さないため、パフォーマンスが向上する可能性がありますが、placeholder プロパティとは使用できません。プレースホルダーは削除されないためです。

既知のブラウザバグ

この next/image コンポーネントはブラウザネイティブの 遅延読み込み を使用しており、Safari 15.4 より前の古いブラウザでは積極的読み込みにフォールバックする可能性があります。ぼかしプレースホルダーを使用する場合、Safari 12 より前の古いブラウザでは空のプレースホルダーにフォールバックします。width/height を auto にしたスタイルを使用する場合、アスペクト比を保持しない 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> 要素のスタイリングと似ていますが、いくつかのガイドラインに注意する必要があります:

styled-jsx ではなく className または style を使用してください。ほとんどの場合、className プロパティを使用することを推奨します。これはインポートされた CSS モジュール、グローバルスタイルシート などにすることができます。

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="Mountains"
        // 画像をインポートすると
        // 自動的に幅と高さが設定される
        src={mountains}
        sizes="100vw"
        // 画像をフル幅で表示し
        // アスペクト比を維持する
        style={{
          width: '100%',
          height: 'auto',
        }}
      />
    </div>
  )
}

リモートURLでのレスポンシブ画像

ソース画像が動的またはリモートURLの場合、Next.jsがアスペクト比を計算できるようにwidthとheightプロップを指定する必要があります:

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}
    />
  )
}

試してみる:

• ビューポートに応答する画像のデモ

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="Mountains"
          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="Mountains"
      src={mountains}
      placeholder="blur"
      quality={100}
      fill
      sizes="100vw"
      style={{
        objectFit: 'cover',
      }}
    />
  )
}

様々なスタイルで使用されたImageコンポーネントの例については、Image Component Demoを参照してください。

リモート画像

リモート画像を使用するには、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は、画像ファイルのレンダリングサイズを決定するものでは_ありません_。

画像の最適化を安全に許可するには、next.config.jsでサポートされるURLパターンのリストを定義します。悪意のある使用を防ぐため、できるだけ具体的にしてください。例えば、次の設定では特定のAWS S3バケットからの画像のみを許可します:

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

テーマ検出

ライトモードとダークモードで異なる画像を表示したい場合は、2つの<Image>コンポーネントをラップし、CSSメディアクエリに基づいて正しい方を表示する新しいコンポーネントを作成できます。

.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} />
    </>
  )
}

知っておくと良い: loading="lazy"のデフォルト動作により、正しい画像のみが読み込まれます。priorityやloading="eager"は使用できません。これらは両方の画像を読み込む原因になります。代わりにfetchPriority="high"を使用できます。

試してみる:

• ライト/ダークモードテーマ検出のデモ

アートディレクション

モバイルとデスクトップで異なる画像を表示したい場合（アートディレクションと呼ばれることもあります）、getImageProps()に異なるsrc、width、height、qualityプロップを提供できます。

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文字列をimage-set() CSS関数に変換して、背景画像を最適化することもできます。

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>
  )
}

バージョン履歴