Image コンポーネント

Next.js Image コンポーネントは HTML の <img> 要素を拡張して、自動的な画像最適化を提供します。

app/page.js

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

リファレンス

Props

以下の Props が利用できます。

Prop	例	型	ステータス
`src`	`src="/profile.png"`	String	必須
`alt`	`alt="Picture of the author"`	String	必須
`width`	`width={500}`	Integer (px)	-
`height`	`height={500}`	Integer (px)	-
`fill`	`fill={true}`	Boolean	-
`loader`	`loader={imageLoader}`	Function	-
`sizes`	`sizes="(max-width: 768px) 100vw, 33vw"`	String	-
`quality`	`quality={80}`	Integer (1-100)	-
`preload`	`preload={true}`	Boolean	-
`placeholder`	`placeholder="blur"`	String	-
`style`	`style={{objectFit: "contain"}}`	Object	-
`onLoadingComplete`	`onLoadingComplete={img => done())}`	Function	非推奨
`onLoad`	`onLoad={event => done())}`	Function	-
`onError`	`onError(event => fail()}`	Function	-
`loading`	`loading="lazy"`	String	-
`blurDataURL`	`blurDataURL="data:image/jpeg..."`	String	-
`unoptimized`	`unoptimized={true}`	Boolean	-
`overrideSrc`	`overrideSrc="/seo.png"`	String	-
`decoding`	`decoding="async"`	String	-

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

補足：セキュリティ上の理由から、デフォルト loader を使用した 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`

画像を親要素のサイズに合わせて拡大する boolean です。

<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 のような関数を受け取る Props を使用するには、提供された関数をシリアル化するために Client Components を使用する必要があります。

または、next.config.js の loaderFile 設定を使用して、Props を渡さずにアプリケーション内のすべての 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 props を使用している。
CSS を使用して画像がレスポンシブになっている。

sizes が不足している場合、ブラウザは画像がビューポートと同じ幅（100vw）になると仮定します。これにより、不必要に大きな画像がダウンロードされる可能性があります。

さらに、sizes は srcset の生成方法に影響します。

sizes がない場合：Next.js は限定的な srcset（例：1x、2x）を生成し、固定サイズの画像に適しています。
sizes がある場合：Next.js は完全な srcset（例：640w、750w など）を生成し、レスポンシブレイアウトに最適化されています。

web.dev と mdn の srcset と sizes の詳細を確認してください。

`quality`

最適化された画像の品質を設定する 1 ～ 100 の整数です。値が高いほどファイルサイズと視覚的忠実度が増加します。値が低いほどファイルサイズが削減されますが、シャープネスに影響する可能性があります。

// デフォルト品質は 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 props を使用してカスタム幅を設定する場合は、画像のアスペクト比を保持するために height: 'auto' も設定してください。

`preload`

画像をプリロードする必要があるかどうかを示す boolean です。

// デフォルトの preload は 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`

画像のロードをいつ開始するかを制御します。

// デフォルトは lazy
<Image loading="lazy" />

lazy：ビューポートから計算された距離に達するまで、画像のロードを遅延させます。
eager：ページ内の位置に関係なく、画像を直ちにロードします。

画像が直ちにロードされることを確認したい場合のみ、eager を使用してください。

loading 属性の詳細を確認してください。

`placeholder`

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

// デフォルトは 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> 要素を参照する target を持つイベントの 1 つの引数で呼び出されます。

補足：onLoad のような関数を受け取る Props を使用するには、提供された関数をシリアル化するために Client Components を使用する必須があります。

`onError`

画像のロードに失敗すると実行されるコールバック関数です。

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

補足：onError のような関数を受け取る Props を使用するには、提供された関数をシリアル化するために Client Components を使用する必須があります。

`unoptimized`

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

import Image from 'next/image'
 
const UnoptimizedImage = (props) => {
  // デフォルトは false
  return <Image {...props} unoptimized />
}

true：ソース画像は品質、サイズ、または形式を変更せずに src から提供されます。
false：ソース画像は最適化されます。

Next.js 12.3.0 以降、この props は next.config.js を以下の設定で更新することで、すべての画像に割り当てることができます。

next.config.js

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

`overrideSrc`

<Image> コンポーネントに src props を提供する場合、srcset と src 属性は結果の <img> に自動的に生成されます。

input.js

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

output.html

<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 props を使用してそれをオーバーライドしたい場合があります。

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

input.js

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

output.html

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

他のコンテンツ更新を提示する前に画像をデコードするのを待つ必要があるかどうかを示すブラウザへのヒントです。

// デフォルトは async
<Image decoding="async" />

async：非同期的に画像をデコードし、他のコンテンツをレンダリングしてから完了することを許可します。
sync：他のコンテンツと原子的な提示のために、画像を同期的にデコードします。
auto：優先事項なし。ブラウザが最適なアプローチを選択します。

decoding 属性の詳細を確認してください。

その他の Props

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

srcSet：代わりに Device Sizes を使用してください。

非推奨の Props

`onLoadingComplete`

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

画像が完全にロードされ、プレースホルダーが削除されると実行されるコールバック関数です。

コールバック関数は基になる <img> 要素への参照である 1 つの引数で呼び出されます。

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

補足：onLoadingComplete のような関数を受け取る Props を使用するには、提供された関数をシリアル化するために Client Components を使用する必須があります。

設定オプション

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

`localPatterns`

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

next.config.js

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 を使用して、特定の外部パスからの画像を許可し、他のすべての画像をブロックします。これにより、アカウントからのみ外部画像が提供されることが保証されます。

next.config.js

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

オブジェクトを使用して remotePatterns を設定することもできます。

next.config.js

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 の両方に使用でき、以下の構文があります。

* 単一のパスセグメントまたはサブドメインを一致させます。
** パスセグメント末尾のサブドメインの開始時の任意の数を一致させます。この構文はパターンの中央では機能しません。

next.config.js

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

これにより、image.example.com のようなサブドメインが許可されます。クエリ文字列とカスタムポートはブロックされたままです。

補足：protocol、port、pathname、または search を省略すると、ワイルドカード ** が暗黙に使用されます。これは推奨されません。悪意のあるユーザーが意図していない URL を最適化する可能性があります。

クエリ文字列：

search プロパティを使用してクエリ文字列を制限することもできます。

next.config.js

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 の代わりにカスタム画像最適化サービスを使用できます。

next.config.js

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

パスはプロジェクトルートに対する相対パスである必須があります。ファイルは URL 文字列を返すデフォルト関数をエクスポートする必須があります。

my/image/loader.js

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

例：

カスタム Image Loader 設定

または、loader props を使用して next/image の各インスタンスを設定できます。

`path`

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

next.config.js

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

`deviceSizes`

deviceSizes を使用すると、デバイス幅ブレークポイントのリストを指定できます。これらの幅は、next/image コンポーネントが sizes props を使用して、ユーザーのデバイスに正しい画像が提供されるようにする場合に使用されます。

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

next.config.js

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

`imageSizes`

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

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

next.config.js

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

imageSizes は sizes props を提供する画像に対してのみ使用されます。これは、画像が画面の全幅より小さいことを示します。したがって、imageSizes 内のサイズはすべて deviceSizes 内の最小サイズより小さくする必須があります。

`qualities`

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

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

next.config.js

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

補足：Next.js 16 以降、このフィールドは必須です。制限のないアクセスにより、悪意のあるユーザーが意図していない品質をより多く最適化できる可能性があります。

以下のように、より多くの画像品質をアローリストに追加できます。

next.config.js

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

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

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

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

`formats`

formats を使用すると、使用する画像形式のリストを指定できます。

next.config.js

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

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

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

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

next.config.js

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

補足：

ほとんどのユースケースでは、WebP を使用し続けることをお勧めします。

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

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

`minimumCacheTTL`

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

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

next.config.js

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

TTL を増加させて、再検証の数を減らし、潜在的にコストを低下させることができます。

next.config.js

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

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

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

現在、キャッシュを無効化するメカニズムはないため、minimumCacheTTL を低く保つことが最良です。それ以外の場合は、src props を手動で変更するか、キャッシュされたファイル <distDir>/cache/images を削除する必須があります。

`disableStaticImages`

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

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

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

next.config.js

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

`maximumRedirects`

デフォルトの画像最適化ローダーは、リモート画像を取得するときに HTTP リダイレクトに従い、最大 3 回まで実行されます。

next.config.js

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

リモート画像を取得するときに従うリダイレクト数を設定できます。値を 0 に設定すると、リダイレクトの従動を無効にします。

next.config.js

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

`dangerouslyAllowLocalIP`

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

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

next.config.js

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

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

next.config.js

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

`dangerouslyAllowSVG`

dangerouslyAllowSVG を使用すると、SVG 画像を提供できます。

next.config.js

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

デフォルトでは、Next.js はいくつかの理由で SVG 画像を最適化しません。

SVG はベクター形式です。つまり、ロスレスでサイズ変更できます。
SVG には HTML/CSS と同じ機能が多数あり、適切な Content Security Policy（CSP）ヘッダーがないと脆弱性につながる可能性があります。

src props が SVG であることが既知の場合、unoptimized props を使用することをお勧めします。これは、src が ".svg" で終わる場合に自動的に実行されます。

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

さらに、contentDispositionType を設定してブラウザに画像をダウンロードするよう強制し、contentSecurityPolicy を設定して画像に組み込まれたスクリプトが実行されるのを防ぐことをお勧めします。

next.config.js

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

`contentDispositionType`

contentDispositionType を使用して、Content-Disposition ヘッダーを設定できます。

next.config.js

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

`contentSecurityPolicy`

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

next.config.js

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

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

デフォルト値は attachment で、直接アクセス時にブラウザが画像をダウンロードするように強制します。これは、dangerouslyAllowSVG が true の場合に特に重要です。

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

非推奨の設定オプション

`domains`

警告：悪意のあるユーザーからアプリケーションを保護するために、Next.js 14 以降は厳密な remotePatterns の支持で非推奨になりました。

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

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

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

next.config.js

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 props では使用できません。プレースホルダーは削除されることがありません。

next/image コンポーネントはブラウザネイティブ lazy loading を使用します。これにより、Safari 15.4 より前の古いブラウザで eager loading にフォールバックする可能性があります。ぼかしアッププレースホルダーを使用するときは、Safari 12 より前の古いブラウザは空のプレースホルダーにフォールバックします。width/height のスタイルを auto で使用するときは、アスペクト比を保持しないSafari 15 より前の古いブラウザで Layout Shift が発生する可能性があります。詳細については、この 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> 要素のスタイル設定に似ていますが、注意すべき点がいくつかあります。

styled-jsx ではなく、className または style を使用してください。ほとんどの場合、className props を使用することをお勧めします。これは、インポートされた CSS Module、global stylesheet などです。

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

style props を使用して、インラインスタイルを割り当てることもできます。

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 はファイルに基づいて幅と高さを自動的に設定します。スタイルを設定して、画像をレスポンシブにできます。

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

リモート URL を使用した応答性の高い画像

ソース画像が動的またはリモート URL の場合、Next.js がアスペクト比を計算できるよう、幅と高さの props を提供する必須があります。

components/page.js

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 props を追加して、objectFit props を cover に設定できます。これにより、画像は親コンテナの全幅を満たします。

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>
      {/* グリッド内の他の画像... */}
    </div>
  )
}

背景画像

fill props を使用して、画像が画面全体をカバーするようにします。

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 文字列である必須があります。

app/page.js

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 props を手動で提供する必須があります。

width と height 属性は、画像の正しいアスペクト比を推測し、ロード中の画像からのレイアウトシフトを回避するために使用されます。width と height は、画像ファイルのレンダリングサイズを決定しません。

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

next.config.js

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

テーマ検出

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

components/theme-image.module.css

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

components/theme-image.tsx

TypeScript

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 props を提供できます。

app/page.js

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

app/page.js

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` props を追加、`priority` props を非推奨、`dangerouslyAllowLocalIP` 設定を追加、`maximumRedirects` 設定を追加。
`v15.3.0`	`remotePatterns` は `URL` オブジェクトの配列をサポート。
`v15.0.0`	`contentDispositionType` 設定のデフォルトを `attachment` に変更。
`v14.2.23`	`qualities` 設定を追加。
`v14.2.15`	`decoding` props と `localPatterns` 設定を追加。
`v14.2.14`	`remotePatterns.search` props を追加。
`v14.2.0`	`overrideSrc` props を追加。
`v14.1.0`	`getImageProps()` は安定版。
`v14.0.0`	`onLoadingComplete` props と `domains` 設定を非推奨。
`v13.4.14`	`placeholder` props で `data:/image...` をサポート。
`v13.2.0`	`contentDispositionType` 設定を追加。
`v13.0.6`	`ref` props を追加。
`v13.0.0`	`next/image` インポートは `next/legacy/image` に名前変更。`next/future/image` インポートは `next/image` に名前変更。codemod を使用してインポートを安全かつ自動的に名前変更できます。`<span>` ラッパーを削除。`layout`、`objectFit`、`objectPosition`、`lazyBoundary`、`lazyRoot` props を削除。`alt` は必須。`onLoadingComplete` は `img` 要素への参照を受け取ります。組み込みの loader 設定を削除。
`v12.3.0`	`remotePatterns` と `unoptimized` 設定は安定版。
`v12.2.0`	実験的な `remotePatterns` と実験的な `unoptimized` 設定を追加。`layout="raw"` を削除。
`v12.1.1`	`style` props を追加。`layout="raw"` の実験的サポートを追加。
`v12.1.0`	`dangerouslyAllowSVG` と `contentSecurityPolicy` 設定を追加。
`v12.0.9`	`lazyRoot` props を追加。
`v12.0.0`	`formats` 設定を追加。 AVIF サポートを追加。ラッパー `<div>` を `<span>` に変更。
`v11.1.0`	`onLoadingComplete` と `lazyBoundary` props を追加。
`v11.0.0`	静的インポート用の `src` props サポート。 `placeholder` props を追加。 `blurDataURL` props を追加。
`v10.0.5`	`loader` props を追加。
`v10.0.1`	`layout` props を追加。
`v10.0.0`	`next/image` を導入。