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

知っておくと良いこと: Next.jsのバージョン13より前のバージョンを使用している場合、コンポーネントの名前が変更されたため、next/legacy/imageのドキュメントを使用してください。

リファレンス

Props

以下のプロパティが利用可能です

プロパティ	例	タイプ	ステータス
`src`	`src="/profile.png"`	文字列	必須
`alt`	`alt="Picture of the author"`	文字列	必須
`width`	`width={500}`	整数 (px)	-
`height`	`height={500}`	整数 (px)	-
`埋め込み`	`fill={true}`	ブーリアン	-
`ローダー`	`loader={imageLoader}`	関数	-
`サイズ`	`sizes="(max-width: 768px) 100vw, 33vw"`	文字列	-
`品質`	`quality={80}`	整数 (1-100)	-
`プリロード`	`preload={true}`	ブーリアン	-
`プレースホルダー`	`placeholder="blur"`	文字列	-
`style`	`style={{objectFit: "contain"}}`	オブジェクト	-
`onLoadingComplete`	`onLoadingComplete={img => done())}`	関数	非推奨
`onLoad`	`onLoad={event => done())}`	関数	-
`onError`	`onError(event => fail()}`	関数	-
`loading`	`loading="lazy"`	文字列	-
`blurDataURL`	`blurDataURL="data:image/jpeg..."`	文字列	-
`最適化なし`	`unoptimized={true}`	ブーリアン	-
`overrideSrc`	`overrideSrc="/seo.png"`	文字列	-
`デコード`	`decoding="async"`	文字列	-

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

知っておくと良いこと: セキュリティ上の理由から、デフォルトのローダーを使用するImage Optimization APIは、src画像をフェッチする際にヘッダーを転送しません。src画像が認証を必要とする場合は、Image Optimizationを無効にするunoptimizedプロパティの使用を検討してください。

`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
品質

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

あるいは、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までの整数。値が高いほどファイルサイズと視覚的な忠実度が増加します。値が低いほどファイルサイズは小さくなりますが、シャープネスに影響する可能性があります。

// Default quality is 75
<Image quality={75} />

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

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

`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'も設定するようにしてください。

`preload`

画像がプリロードされるかどうかを示すブーリアン値。

// Default preload is false
<Image preload={false} />

true: <head>に<link>を挿入して画像をプリロードします。
false: 画像をプリロードしません。

いつ使用するか

画像はLargest Contentful Paint (LCP)要素です。
画像はビューポートの上部（通常はヒーロー画像）にあります。
<body>で後で検出される前に、<head>で画像読み込みを開始したい。

いつ使用しないか

ビューポートに応じて、Largest Contentful Paint (LCP)要素と見なされる可能性のある画像が複数ある場合。
loadingプロパティが使用されている場合。
fetchPriorityプロパティが使用されている場合。

ほとんどの場合、preloadの代わりにloading="eager"またはfetchPriority="high"を使用する必要があります。

`priority`

Next.js 16以降、priorityプロパティは、動作を明確にするためにpreloadプロパティに置き換えられました。

`loading`

画像がいつ読み込みを開始するかを制御します。

// Defaults to lazy
<Image loading="lazy" />

lazy: 画像がビューポートから計算された距離に達するまで読み込みを遅延させます。
eager: 画像がページ上の位置に関係なく、すぐに読み込みます。

画像がすぐに読み込まれることを保証したい場合にのみeagerを使用してください。

loading属性について詳細はこちら。

`placeholder`

画像読み込み中に使用するプレースホルダーを指定し、認識される読み込みパフォーマンスを向上させます。

// defaults to empty
<Image placeholder="empty" />

empty: 画像読み込み中にプレースホルダーはありません。
blur: 画像のぼかしバージョンをプレースホルダーとして使用します。blurDataURLプロパティと組み合わせて使用する必要があります。
data:image/...: プレースホルダーとしてData URLを使用します。

例

placeholder属性について詳細はこちら。

`blurDataURL`

画像が正常に読み込まれる前にプレースホルダーとして使用されるData URL。自動的に設定されるか、placeholder="blur"プロパティと組み合わせて使用できます。

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

画像は自動的に拡大縮小されぼかされるため、非常に小さな画像（10px以下）が推奨されます。

自動

srcがjpg、png、webp、またはavifファイルの静的インポートである場合、画像がアニメーションでない限り、blurDataURLは自動的に追加されます。

手動設定

画像が動的またはリモートである場合、blurDataURLを自分で提供する必要があります。生成するには、以下を使用できます。

大きなblurDataURLはパフォーマンスに悪影響を与える可能性があります。小さくシンプルに保ってください。

例

`onLoad`

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

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

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

`onError`

画像が読み込めなかった場合に呼び出されるコールバック関数。

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

`unoptimized`

画像が最適化されるかどうかを示すブーリアン値。これは、最適化の恩恵を受けない画像（1KB未満の小さな画像、ベクター画像（SVG）、またはアニメーション画像（GIF））に便利です。

import Image from 'next/image'
 
const UnoptimizedImage = (props) => {
  // Default is 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=%2Fprofile.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fprofile.jpg&w=828&q=75 2x
  "
  src="/_next/image?url=%2Fprofile.jpg&w=828&q=75"
/>

場合によっては、src属性が生成されることを望まないことがあり、overrideSrcプロパティを使用して上書きしたい場合があります。

たとえば、既存のWebサイトを<img>から<Image>にアップグレードする場合、SEO目的（画像のランキングや再クロールの回避など）で同じsrc属性を維持したい場合があります。

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

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

`decoding`

ブラウザに、他のコンテンツ更新の前に画像のデコードを待つべきかどうか、またはそうしないべきかを示すヒント。

// Default is async
<Image decoding="async" />

async: 画像を非同期にデコードし、完了前に他のコンテンツのレンダリングを許可します。
sync: 他のコンテンツとのアトミックなプレゼンテーションのために画像を同期的にデコードします。
auto: 好みなし。ブラウザが最適なアプローチを選択します。

decoding属性について詳細はこちら。

その他のプロパティ

<Image />コンポーネントのその他のプロパティは、以下を除くすべてのプロパティが基盤となるimg要素に渡されます。

srcSet: Device Sizesを使用してください。

非推奨のプロパティ

`onLoadingComplete`

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

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

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

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

設定オプション

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

`localPatterns`

next.config.jsファイルでlocalPatternsを使用して、特定のローカルパスからの画像を最適化できるようにし、それ以外はすべてブロックします。

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

上記の例では、next/imageのsrcプロパティは/assets/images/で始まり、クエリ文字列を含まない必要があります。それ以外のパスを最適化しようとすると、400 Bad Requestエラーが応答されます。

知っておくと良いこと: searchプロパティを省略すると、すべての検索パラメータが許可される可能性があり、悪意のあるアクターが意図しないURLを最適化できるようになる可能性があります。search: '?v=2'のような具体的な値を使用して、正確な一致を確実にしてください。

`remotePatterns`

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

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

オブジェクトを使用して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文字列を返すデフォルト関数をエクスポートする必要があります。

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

例

カスタム画像ローダー設定

あるいは、loaderプロパティを使用して、next/imageの各インスタンスを設定することもできます。

`path`

Image Optimization APIのデフォルトパスを変更またはプレフィックスしたい場合は、pathプロパティを使用できます。pathのデフォルト値は/_next/imageです。

module.exports = {
  images: {
    path: '/my-prefix/_next/image',
  },
}

`deviceSizes`

deviceSizesを使用すると、デバイス幅のブレークポイントのリストを指定できます。これらの幅は、next/imageコンポーネントがsizesプロパティを使用し、ユーザーのデバイスに適切な画像が提供されるようにするために使用されます。

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

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

`imageSizes`

imageSizesを使用すると、画像幅のリストを指定できます。これらの幅は、device sizesの配列と連結されて、画像srcsetを生成するために使用される完全なサイズ配列を形成します。

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

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

imageSizesは、sizesプロパティを提供し、画像が画面の全幅より小さいことを示す画像にのみ使用されます。したがって、imageSizesのサイズはすべて、deviceSizesの最小サイズよりも小さくなっている必要があります。

`qualities`

qualitiesを使用すると、画像品質値のリストを指定できます。

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

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

知っておくと良いこと: Next.js 16以降、このフィールドは必須です。制限のないアクセスは、悪意のあるアクターが意図した以上の品質を最適化できるようになる可能性があるためです。

許可リストに画像品質を追加できます。たとえば、次のようになります。

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

上記の例では、4つの品質（25、50、75、100）のみが許可されています。

qualityプロパティがこの配列の値と一致しない場合、最も近い許可された値が使用されます。

REST APIに値が一致しない品質で直接アクセスした場合、サーバーは400 Bad Request応答を返します。

`formats`

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

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

Next.jsは、リクエストのAcceptヘッダーを通じてブラウザがサポートする画像フォーマットを自動的に検出し、最適な出力フォーマットを判断します。

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

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

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

知っておくと良いこと:

ほとんどの場合、WebPを使用することをお勧めします。

AVIFは一般的にエンコードに50%長くかかりますが、WebPと比較して20%小さく圧縮されます。つまり、画像が最初にリクエストされたときは通常遅くなりますが、キャッシュされた後続のリクエストは速くなります。

プロキシ/CDNでNext.jsの前にセルフホストしている場合、プロキシがAcceptヘッダーを転送するように設定する必要があります。

`minimumCacheTTL`

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

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

module.exports = {
  images: {
    minimumCacheTTL: 14400, // 4 hours
  },
}

再検証の回数を減らし、コストを削減するためにTTLを増やすことができます。

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

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

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

現時点ではキャッシュを無効にするメカニズムはありません。そのため、minimumCacheTTLは低く保つのが最善です。そうしないと、srcプロパティを手動で変更するか、キャッシュファイル<distDir>/cache/imagesを削除する必要がある場合があります。

`disableStaticImages`

disableStaticImagesを使用すると、静的画像インポートを無効にできます。

デフォルトの動作では、import icon from './icon.png'のような静的ファイルをインポートし、それをsrcプロパティに渡すことができます。場合によっては、インポートが他のプラグインと競合して、インポートが異なるように動作することを期待する場合、この機能を無効にしたい場合があります。

next.config.js内で静的画像インポートを無効にできます。

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

`maximumRedirects`

デフォルトの画像最適化ローダーは、リモート画像を取得する際に最大3回HTTPリダイレクトを追跡します。

module.exports = {
  images: {
    maximumRedirects: 3,
  },
}

リモート画像を取得する際に追跡するリダイレクトの数を設定できます。値を0に設定すると、リダイレクトの追跡が無効になります。

module.exports = {
  images: {
    maximumRedirects: 0,
  },
}

`dangerouslyAllowLocalIP`

まれに、プライベートネットワークでNext.jsをセルフホストする場合、ローカルIPアドレスからの画像最適化を許可したい場合があります。これは、悪意のあるユーザーが内部ネットワーク上のコンテンツにアクセスできるようになる可能性があるため、ほとんどのユーザーには推奨されません。

デフォルトでは、値はfalseです。

module.exports = {
  images: {
    dangerouslyAllowLocalIP: false,
  },
}

ローカルネットワーク内の他の場所でホストされているリモート画像を最適化する必要がある場合は、値をtrueに設定できます。

module.exports = {
  images: {
    dangerouslyAllowLocalIP: 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',
  },
}

`contentSecurityPolicy`

contentSecurityPolicyを使用すると、画像用のContent-Security-Policyヘッダーを設定できます。これは、特にdangerouslyAllowSVGを使用する場合に、画像に埋め込まれたスクリプトの実行を防ぐために重要です。

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

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

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

オプションでinlineを設定して、直接アクセスしたときにブラウザが画像をダウンロードせずにレンダリングできるようにすることができます。

非推奨の設定オプション

`domains`

警告: Next.js 14で、悪意のあるユーザーからアプリケーションを保護するために、厳密なremotePatternsに置き換えられました。

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

ほとんどのリモート画像サーバーは複数のテナント間で共有されているため、意図した画像のみが最適化されるようにremotePatternsを使用するのが安全です。

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: '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コンポーネントは、ブラウザネイティブの遅延読み込みを使用しています。これは、古いブラウザ（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) } }を使用する。
- 画像がビューポートの上部にある場合はloading="eager"を使用する。
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マークを付けない限り）。

静的エクスポートでのレスポンシブ画像

静的画像（static image）をインポートすると、Next.jsは自動的にファイルに基づいて幅と高さを設定します。スタイルを設定することで、画像をレスポンシブにすることができます。

Responsive image filling the width and height of its parent container

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"
        // Importing an image will
        // automatically set the width and height
        src={mountains}
        sizes="100vw"
        // Make the image display full width
        // and preserve its aspect ratio
        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="Picture of the author"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
      width={500}
      height={300}
    />
  )
}

試してみる

ビューポートにレスポンシブな画像を表示する

`fill`を使用したレスポンシブ画像

画像の縦横比が不明な場合は、objectFitプロップをcoverに設定したfillプロップを追加できます。これにより、画像は親コンテナの全幅を埋めるようになります。

Grid of images filling parent container width

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>
      {/* And more images in the grid... */}
    </div>
  )
}

背景画像

fillプロップを使用して、画像を画面全体に表示させます。

Background image taking full width and height of page

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="Picture of the author"
      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' | 'preload' | '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"のデフォルトの動作により、正しい画像のみが読み込まれます。両方の画像が読み込まれてしまうため、preloadまたはloading="eager"は使用できません。代わりに、fetchPriority="high"を使用できます。

試してみる

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

アートディレクション

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

import { getImageProps } from 'next/image'
 
export default function Home() {
  const common = { alt: 'Art Direction Example', 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>
  )
}

バージョン履歴

バージョン	変更履歴
`v16.0.0`	`qualities`のデフォルト構成が`[75]`に変更され、`preload`プロップが追加され、`priority`プロップが非推奨となり、`dangerouslyAllowLocalIP`構成と`maximumRedirects`構成が追加されました。
`v15.3.0`	`remotePatterns`に`URL`オブジェクトの配列のサポートが追加されました。
`v15.0.0`	`contentDispositionType`構成のデフォルトが`attachment`に変更されました。
`v14.2.23`	`qualities`構成が追加されました。
`v14.2.15`	`decoding`プロップと`localPatterns`構成が追加されました。
`v14.2.14`	`remotePatterns.search`プロップが追加されました。
`v14.2.0`	`overrideSrc`プロップが追加されました。
`v14.1.0`	`getImageProps()`が安定しました。
`v14.0.0`	`onLoadingComplete`プロップと`domains`構成が非推奨になりました。
`v13.4.14`	`placeholder`プロップで`data:/image...`のサポートが追加されました。
`v13.2.0`	`contentDispositionType`構成が追加されました。
`v13.0.6`	`ref`プロップが追加されました。
`v13.0.0`	`next/image`のインポートが`next/legacy/image`にリネームされました。`next/future/image`のインポートが`next/image`にリネームされました。インポートを安全かつ自動的にリネームするためのcodemodが利用可能です。`<span>`ラッパーが削除されました。`layout`、`objectFit`、`objectPosition`、`lazyBoundary`、`lazyRoot`プロップが削除されました。`alt`は必須です。`onLoadingComplete`は`img`要素への参照を受け取ります。組み込みローダー構成が削除されました。
`v12.3.0`	`remotePatterns`および`unoptimized`構成が安定しました。
`v12.2.0`	実験的な`remotePatterns`および実験的な`unoptimized`構成が追加されました。`layout="raw"`が削除されました。
`v12.1.1`	`style`プロップと、`layout="raw"`の実験的なサポートが追加されました。
`v12.1.0`	`dangerouslyAllowSVG`および`contentSecurityPolicy`構成が追加されました。
`v12.0.9`	`lazyRoot`プロップが追加されました。
`v12.0.0`	`formats`構成が追加されました。 AVIFサポートが追加されました。ラッパー`<div>`が`<span>`に変更されました。
`v11.1.0`	`onLoadingComplete`および`lazyBoundary`プロップが追加されました。
`v11.0.0`	静的インポートでの`src`プロップのサポートが追加されました。 `placeholder`プロップが追加されました。 `blurDataURL`プロップが追加されました。
`v10.0.5`	`loader`プロップが追加されました。
`v10.0.1`	`layout`プロップが追加されました。
`v10.0.0`	`next/image`が導入されました。