Image

例

Image Component

このAPIリファレンスは、Imageコンポーネントで利用可能なpropsと設定オプションの使用方法を理解するのに役立ちます。機能と使用法については、Image Componentページを参照してください。

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

Imageコンポーネントで利用可能なpropsの概要は以下のとおりです：

Prop	Example	Type	Status
`src`	`src="/profile.png"`	String	Required
`width`	`width={500}`	Integer (px)	Required
`height`	`height={500}`	Integer (px)	Required
`alt`	`alt="Picture of the author"`	String	Required
`loader`	`loader={imageLoader}`	Function	-
`fill`	`fill={true}`	Boolean	-
`sizes`	`sizes="(max-width: 768px) 100vw, 33vw"`	String	-
`quality`	`quality={80}`	Integer (1-100)	-
`priority`	`priority={true}`	Boolean	-
`placeholder`	`placeholder="blur"`	String	-
`style`	`style={{objectFit: "contain"}}`	Object	-
`onLoadingComplete`	`onLoadingComplete={img => done())}`	Function	Deprecated
`onLoad`	`onLoad={event => done())}`	Function	-
`onError`	`onError(event => fail()}`	Function	-
`loading`	`loading="lazy"`	String	-
`blurDataURL`	`blurDataURL="data:image/jpeg..."`	String	-
`overrideSrc`	`overrideSrc="/seo.png"`	String	-

Required Props

Imageコンポーネントには、src、alt、width、height（またはfill）のプロパティが必要です。

app/page.js
import Image from 'next/image'

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

`src`

以下のいずれかである必要があります：

静的にインポートされた画像ファイル
パス文字列。これは、loader propに応じて、絶対外部URLまたは内部パスのいずれかです。

デフォルトのloaderを使用する場合、ソース画像について以下も考慮してください：

srcが外部URLの場合、remotePatternsを設定する必要があります
srcがアニメーションされているか、既知の形式（JPEG、PNG、WebP、AVIF、GIF、TIFF）でない場合、画像はそのまま提供されます
srcがSVG形式の場合、unoptimizedまたはdangerouslyAllowSVGが有効でない限りブロックされます

`width`

widthプロパティは、ピクセル単位の本来の画像の幅を表します。このプロパティは、画像の正しいアスペクト比を推測し、読み込み中のレイアウトシフトを回避するために使用されます。HTMLの<img>タグのwidth属性と同様に、画像のレンダリングサイズを決定するものではなく、CSSによって制御されます。

静的にインポートされた画像またはfillプロパティを持つ画像を除いて必須です。

`height`

heightプロパティは、ピクセル単位の本来の画像の高さを表します。このプロパティは、画像の正しいアスペクト比を推測し、読み込み中のレイアウトシフトを回避するために使用されます。HTMLの<img>タグのheight属性と同様に、画像のレンダリングサイズを決定するものではなく、CSSによって制御されます。

静的にインポートされた画像またはfillプロパティを持つ画像を除いて必須です。

Good to know:

widthとheightプロパティを組み合わせることで、画像のアスペクト比を決定し、ブラウザが画像を読み込む前にスペースを確保します。

本来のサイズは、ブラウザでのレンダリングサイズを意味するものではなく、親コンテナによって決定されます。たとえば、親コンテナが本来のサイズより小さい場合、画像はコンテナに合わせて縮小されます。

幅と高さが不明な場合は、fillプロパティを使用できます。

`alt`

altプロパティは、スクリーンリーダーや検索エンジンのために画像を説明するために使用されます。また、画像が無効化されている場合や、画像の読み込み中にエラーが発生した場合のフォールバックテキストとしても機能します。

ページの意味を変えずに画像を置き換えることができるテキストを含めるべきです。画像を補完するためのものではなく、画像の上または下に既に提供されている情報を繰り返すべきではありません。

画像が純粋に装飾的であるか、ユーザー向けでない場合、altプロパティは空の文字列（alt=""）にするべきです。

詳細はこちら

Optional Props

<Image />コンポーネントは、必須のプロパティ以外にも多くの追加プロパティを受け入れます。このセクションでは、Imageコンポーネントの最も一般的に使用されるプロパティについて説明します。あまり使用されないプロパティの詳細については、Advanced Propsセクションを参照してください。

`loader`

画像URLを解決するために使用されるカスタム関数です。

loaderは、以下のパラメータを受け取り、画像のURL文字列を返す関数です：

src
width
quality

カスタムローダーを使用する例を以下に示します：

'use client'

import Image from 'next/image'

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

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

Good to know: loaderのように関数を受け入れるpropsを使用する場合、提供された関数をシリアライズするためにClient Componentsを使用する必要があります。

また、next.config.jsのloaderFile設定を使用して、アプリケーション内のnext/imageのすべてのインスタンスをpropを渡さずに設定することもできます。

`fill`

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

画像が親要素を埋めるようにするブール値で、widthとheightが不明な場合に便利です。

親要素はposition: "relative"、position: "fixed"、またはposition: "absolute"スタイルを割り当てる必要があります。

デフォルトでは、img要素には自動的にposition: "absolute"スタイルが割り当てられます。

画像にスタイルが適用されていない場合、画像はコンテナに合わせて伸縮します。画像をコンテナに合わせてレターボックス化し、アスペクト比を維持するためにobject-fit: "contain"を設定することをお勧めします。

また、object-fit: "cover"を設定すると、画像がコンテナ全体を埋め、アスペクト比を維持するためにトリミングされます。

詳細については、以下も参照してください：

`sizes`

メディアクエリに似た文字列で、異なるブレークポイントで画像がどれだけの幅になるかを提供します。sizesの値は、fillを使用する画像やレスポンシブサイズにスタイル設定された画像のパフォーマンスに大きく影響します。

sizesプロパティは、画像のパフォーマンスに関連する2つの重要な目的を果たします：

まず、sizesの値は、next/imageの自動生成されたsrcsetから、どのサイズの画像をダウンロードするかをブラウザが決定するために使用されます。ブラウザが選択する際には、ページ上の画像のサイズをまだ知らないため、ビューポートと同じサイズまたはそれ以上の画像を選択します。sizesプロパティを使用すると、ブラウザに画像が実際にはフルスクリーンよりも小さくなることを伝えることができます。fillプロパティを持つ画像でsizes値を指定しない場合、デフォルト値として100vw（フルスクリーン幅）が使用されます。
次に、sizesプロパティは、自動生成されたsrcset値の動作を変更します。sizes値が存在しない場合、固定サイズの画像に適した小さなsrcsetが生成されます（1x/2xなど）。sizesが定義されている場合、レスポンシブ画像に適した大きなsrcsetが生成されます（640w/750wなど）。sizesプロパティに50vwのようなビューポート幅の割合を表すサイズが含まれている場合、srcsetは必要以上に小さい値を含まないようにトリミングされます。

たとえば、スタイリングがモバイルデバイスで画像をフル幅にし、タブレットで2カラムレイアウト、デスクトップディスプレイで3カラムレイアウトになることがわかっている場合、次のようなsizesプロパティを含めるべきです：

import Image from 'next/image'

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

この例のsizesは、パフォーマンスメトリクスに劇的な影響を与える可能性があります。33vwのサイズがない場合、サーバーから選択される画像は必要な幅の3倍になります。ファイルサイズは幅の2乗に比例するため、sizesがない場合、ユーザーは必要以上に9倍大きな画像をダウンロードすることになります。

srcsetとsizesについて詳しく学ぶ：

web.dev
mdn

`quality`

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

最適化された画像の品質を示す整数で、1から100の間で指定します。100は最高品質であり、したがって最大のファイルサイズです。デフォルトは75です。

next.config.jsでqualities設定が定義されている場合、qualityプロパティは設定で定義された値のいずれかに一致する必要があります。

Good to know: 元のソース画像がすでに低品質である場合、qualityプロパティを高く設定しすぎると、最適化された画像が元のソース画像よりも大きくなる可能性があります。

`priority`

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

trueの場合、Next.jsは画像をプリロードします。priorityを使用する画像では、遅延読み込みが自動的に無効になります。loadingプロパティが使用され、lazyに設定されている場合、priorityプロパティは使用できません。loadingプロパティは高度なユースケースのためのものです。priorityが必要な場合はloadingを削除してください。

最大コンテンツ描画（LCP）要素として検出された画像には、priorityプロパティを使用する必要があります。異なるビューポートサイズで異なる画像がLCP要素になる可能性があるため、複数の優先画像を持つことが適切な場合があります。

折りたたみ領域の上に画像が表示される場合にのみ使用する必要があります。デフォルトはfalseです。

`placeholder`

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

画像の読み込み中に使用するプレースホルダーです。可能な値はblur、empty、またはdata:image/...です。デフォルトはemptyです。

blurの場合、blurDataURLプロパティがプレースホルダーとして使用されます。srcが静的インポートからのオブジェクトであり、インポートされた画像が.jpg、.png、.webp、または.avifの場合、blurDataURLは自動的に設定されます。ただし、画像がアニメーションとして検出された場合を除きます。

動的画像の場合、blurDataURLプロパティを提供する必要があります。Plaiceholderなどのソリューションは、base64生成に役立ちます。

data:image/...の場合、データURLが画像の読み込み中にプレースホルダーとして使用されます。

emptyの場合、画像の読み込み中にプレースホルダーはなく、空白のスペースのみが表示されます。

試してみてください：

blurプレースホルダーのデモ
データURLplaceholderプロップを使用したシマー効果のデモ](https://image-component.nextjs.gallery/shimmer)
blurDataURLプロップを使用したカラー効果のデモ

Advanced Props

場合によっては、より高度な使用が必要になることがあります。<Image />コンポーネントは、以下の高度なプロパティをオプションで受け入れます。

`style`

基礎となる画像要素にCSSスタイルを渡すことができます。

components/ProfileImage.js
const imageStyle = {
  borderRadius: '50%',
  border: '1px solid #fff',
}

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

必要な幅と高さのpropsがスタイリングに影響を与える可能性があることを忘れないでください。スタイリングを使用して画像の幅を変更する場合は、アスペクト比を維持するために高さをautoにスタイル設定する必要があります。そうしないと、画像が歪む可能性があります。

`onLoadingComplete`

'use client'

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

Warning: Next.js 14以降、onLoadに置き換えられたため、非推奨です。

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

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

Good to know: onLoadingCompleteのように関数を受け入れるpropsを使用する場合、提供された関数をシリアライズするためにClient Componentsを使用する必要があります。

`onLoad`

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

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

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

Good to know: onLoadのように関数を受け入れるpropsを使用する場合、提供された関数をシリアライズするためにClient Componentsを使用する必要があります。

`onError`

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

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

Good to know: onErrorのように関数を受け入れるpropsを使用する場合、提供された関数をシリアライズするためにClient Componentsを使用する必要があります。

`loading`

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

画像の読み込み動作を指定します。デフォルトはlazyです。

lazyの場合、画像がビューポートから計算された距離に達するまで読み込みを遅延させます。

eagerの場合、画像を即座に読み込みます。

loading属性について詳しく学ぶ。

`blurDataURL`

データURLをプレースホルダー画像として使用し、src画像が正常に読み込まれるまで表示します。placeholder="blur"と組み合わせた場合にのみ効果を発揮します。

base64エンコードされた画像である必要があります。拡大されてぼかされるため、非常に小さな画像（10px以下）が推奨されます。プレースホルダーとして大きな画像を含めると、アプリケーションのパフォーマンスに悪影響を与える可能性があります。

試してみてください：

デフォルトのblurDataURLプロップのデモ](https://image-component.nextjs.gallery/placeholder)
blurDataURLプロップを使用したカラー効果のデモ

画像に一致する単色データURLを生成することもできます。

`unoptimized`

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

trueの場合、ソース画像はsrcからそのまま提供され、品質、サイズ、形式は変更されません。デフォルトはfalseです。

1KB未満の小さな画像、ベクター画像（SVG）、アニメーション画像（GIF）など、最適化の恩恵を受けない画像に適しています。

import Image from 'next/image'

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

Next.js 12.3.0以降、このプロップは次の設定を使用してnext.config.jsを更新することで、すべての画像に割り当てることができます：

next.config.js
module.exports = {
  images: {
    unoptimized: true,
  },
}

`overrideSrc`

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

input.js
<Image src="/me.jpg" />

output.html
<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属性を維持したい場合があります。

input.js
<Image src="/me.jpg" overrideSrc="/override.jpg" />

output.html
<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です。

可能な値は以下のとおりです：

async - 画像を非同期にデコードし、他のコンテンツが完了する前にレンダリングを許可します。
sync - 他のコンテンツと一緒にアトミックに表示するために画像を同期的にデコードします。
auto - デコードモードに対する優先順位はなく、ブラウザが最適なものを決定します。

decoding属性について詳しく学ぶ。

Other Props

<Image />コンポーネントの他のプロパティは、基礎となるimg要素に渡されますが、以下のものは除きます：

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

Configuration Options

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

`localPatterns`

next.config.jsファイルでlocalPatternsをオプションで設定することで、特定のパスを最適化し、他のすべてのパスをブロックできます。

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

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

`remotePatterns`

悪意のあるユーザーからアプリケーションを保護するために、外部画像を使用するには設定が必要です。これにより、アカウントからの外部画像のみがNext.js Image Optimization APIから提供されることが保証されます。これらの外部画像は、以下のようにnext.config.jsファイルのremotePatternsプロパティで設定できます：

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

Next.js 15.3.0より前のバージョンでは、オブジェクトを使用してremotePatternsを設定できます：

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

Good to know: 上記の例では、next/imageのsrcプロパティがhttps://example.com/account123/で始まり、クエリ文字列を持たないことを保証します。他のプロトコル、ホスト名、ポート、または一致しないパスは400 Bad Requestが返されます。

以下は、hostnameにワイルドカードパターンを使用したnext.config.jsファイルのremotePatternsプロパティの例です：

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

Good to know: 上記の例では、next/imageのsrcプロパティがhttps://img1.example.comまたはhttps://me.avatar.example.comまたは任意の数のサブドメインで始まることを保証します。ポートやクエリ文字列を持つことはできません。他のプロトコルや一致しないホスト名は400 Bad Requestが返されます。

ワイルドカードパターンは、pathnameとhostnameの両方に使用でき、以下の構文を持ちます：

*は単一のパスセグメントまたはサブドメインに一致します
**は、末尾の任意の数のパスセグメントまたは先頭のサブドメインに一致します

**構文は、パターンの途中では機能しません。

Good to know: protocol、port、pathname、またはsearchを省略すると、ワイルドカード**が暗黙的に適用されます。これは、意図しないURLを悪意のあるアクターが最適化する可能性があるため、推奨されません。

以下は、searchを使用したnext.config.jsファイルのremotePatternsプロパティの例です：

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

Good to know: 上記の例では、next/imageのsrcプロパティがhttps://assets.example.comで始まり、正確なクエリ文字列?v=1727111025337を持つことを保証します。他のプロトコルやクエリ文字列は400 Bad Requestが返されます。

`domains`

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

remotePatternsと同様に、domains設定を使用して、外部画像の許可されたホスト名のリストを提供できます。

ただし、domains設定はワイルドカードパターンマッチングをサポートしておらず、プロトコル、ポート、またはパス名を制限することはできません。

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

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

`loaderFile`

Next.jsの組み込みImage Optimization APIを使用する代わりに、クラウドプロバイダーを使用して画像を最適化したい場合は、next.config.jsでloaderFileを次のように設定できます：

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

これは、Next.jsアプリケーションのルートからの相対パスを指す必要があります。ファイルは、文字列を返すデフォルト関数をエクスポートする必要があります。たとえば：

my/image/loader.js
'use client'

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

また、loaderプロップを使用して、next/imageの各インスタンスを設定することもできます。

例：

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

Good to know: 関数を受け入れる画像ローダーファイルをカスタマイズするには、提供された関数をシリアライズするためにClient Componentsを使用する必要があります。

Advanced

以下の設定は高度なユースケース向けであり、通常は必要ありません。以下のプロパティを設定する場合、将来のアップデートでNext.jsのデフォルトに対する変更を上書きします。

`deviceSizes`

ユーザーの予想されるデバイス幅を知っている場合、next.config.jsでdeviceSizesプロパティを使用してデバイス幅のブレークポイントのリストを指定できます。これらの幅は、next/imageコンポーネントがsizesプロップを使用する際に、ユーザーのデバイスに適した画像が提供されるようにするために使用されます。

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

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

`imageSizes`

next.config.jsファイルでimages.imageSizesプロパティを使用して画像幅のリストを指定できます。これらの幅は、デバイスサイズの配列と連結され、画像srcsetを生成するために使用されるサイズの完全な配列を形成します。

2つのリストが分かれている理由は、imageSizesは、画像が画面の全幅よりも小さいことを示すsizesプロップを提供する画像にのみ使用されるためです。したがって、imageSizesのサイズは、deviceSizesの最小サイズよりもすべて小さくする必要があります。

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

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

`qualities`

デフォルトのImage Optimization APIは、1から100までのすべての品質を自動的に許可します。許可される品質を制限したい場合は、next.config.jsに設定を追加できます。

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

上記の例では、25、50、75の3つの品質のみが許可されます。qualityプロップがこの配列の値と一致しない場合、画像は400 Bad Requestで失敗します。

`formats`

デフォルトのImage Optimization APIは、リクエストのAcceptヘッダーを介してブラウザがサポートする画像形式を自動的に検出し、最適な出力形式を決定します。

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

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

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

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

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

Good to know:

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

AVIFはエンコードに通常50％長くかかりますが、WebPと比較して20％小さく圧縮されます。これは、画像が最初にリクエストされたときに通常は遅くなり、その後のキャッシュされたリクエストが高速になることを意味します。

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

Caching Behavior

以下は、デフォルトのloaderのキャッシングアルゴリズムについて説明します。他のすべてのローダーについては、クラウドプロバイダーのドキュメントを参照してください。

画像はリクエスト時に動的に最適化され、<distDir>/cache/imagesディレクトリに保存されます。最適化された画像ファイルは、期限が切れるまで後続のリクエストに対して提供されます。キャッシュされたが期限切れのファイルに一致するリクエストが行われた場合、期限切れの画像はすぐに古い状態で提供されます。その後、画像はバックグラウンドで再最適化（再検証とも呼ばれます）され、新しい有効期限でキャッシュに保存されます。

画像のキャッシュステータスは、x-nextjs-cacheレスポンスヘッダーの値を読み取ることで判断できます。可能な値は以下のとおりです：

MISS - パスがキャッシュにありません（最初の訪問時に最大1回発生）
STALE - パスがキャッシュにありますが、再検証時間を超過したため、バックグラウンドで更新されます
HIT - パスがキャッシュにあり、再検証時間を超過していません

有効期限（または最大年齢）は、minimumCacheTTL設定または上流画像のCache-Controlヘッダーのいずれか大きい方によって定義されます。具体的には、Cache-Controlヘッダーのmax-age値が使用されます。s-maxageとmax-ageの両方が見つかった場合、s-maxageが優先されます。max-ageは、CDNやブラウザを含む下流のクライアントにも渡されます。

上流画像にCache-Controlヘッダーが含まれていない場合や値が非常に低い場合にキャッシュ期間を延ばすために、minimumCacheTTLを設定できます。
生成される可能性のある画像の総数を減らすために、deviceSizesとimageSizesを設定できます。
単一の画像形式を優先するために、formatsを設定して複数の形式を無効にすることができます。

`minimumCacheTTL`

キャッシュされた最適化画像の生存時間（TTL）を秒単位で設定できます。多くの場合、静的画像インポートを使用する方が良いです。これにより、ファイルの内容が自動的にハッシュされ、immutableのCache-Controlヘッダーで画像が永遠にキャッシュされます。

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

next.config.js
module.exports = {
  images: {
    minimumCacheTTL: 60, // 1 minute
  },
}

TTLを延ばして再検証の回数を減らし、コストを削減することができます：

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

最適化された画像の有効期限（または最大年齢）は、minimumCacheTTLまたは上流画像のCache-Controlヘッダーのいずれか大きい方によって定義されます。

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

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

`disableStaticImages`

デフォルトの動作では、import icon from './icon.png'のように静的ファイルをインポートし、それをsrcプロパティに渡すことができます。

場合によっては、インポートが異なる動作を期待する他のプラグインと競合する場合、この機能を無効にしたいことがあります。

next.config.js内で静的画像インポートを無効にすることができます：

next.config.js
module.exports = {
  images: {
    disableStaticImages: true,
  },
}

`dangerouslyAllowSVG`

デフォルトのloaderは、いくつかの理由でSVG画像を最適化しません。まず、SVGはベクター形式であり、損失なくリサイズできます。第二に、SVGはHTML/CSSと同じ機能を多く持っており、適切なコンテンツセキュリティポリシー（CSP）ヘッダーがないと脆弱性を引き起こす可能性があります。

したがって、srcプロップがSVGであることがわかっている場合は、unoptimizedプロップを使用することをお勧めします。これは、srcが".svg"で終わる場合に自動的に発生します。

ただし、デフォルトのImage Optimization APIでSVG画像を提供する必要がある場合は、next.config.js内でdangerouslyAllowSVGを設定できます：

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

さらに、画像に埋め込まれたスクリプトが実行されないようにするために、contentDispositionTypeを設定してブラウザに画像をダウンロードさせること、およびcontentSecurityPolicyを設定することを強くお勧めします。

`contentDispositionType`

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

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

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

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

Animated Images

デフォルトのloaderは、アニメーション画像の最適化を自動的にバイパスし、画像をそのまま提供します。

アニメーションファイルの自動検出はベストエフォートであり、GIF、APNG、WebPをサポートします。特定のアニメーション画像の最適化を明示的にバイパスしたい場合は、unoptimizedプロップを使用してください。

Responsive Images

デフォルトで生成されるsrcsetには、異なるデバイスピクセル比をサポートするために1xと2xの画像が含まれています。ただし、ビューポートに合わせて伸縮するレスポンシブ画像をレンダリングしたい場合があります。その場合、sizesとstyle（またはclassName）を設定する必要があります。

以下の方法のいずれかを使用してレスポンシブ画像をレンダリングできます。

Responsive image using a static import

ソース画像が動的でない場合、静的インポートを使用してレスポンシブ画像を作成できます：

components/author.js
import Image from 'next/image'
import me from '../photos/me.jpg'

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

試してみてください：

ビューポートに応じた画像のデモ

Responsive image with aspect ratio

ソース画像が動的またはリモートURLの場合、レスポンシブ画像の正しいアスペクト比を設定するためにwidthとheightを提供する必要があります：

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

試してみてください：

ビューポートに応じた画像のデモ

Responsive image with `fill`

アスペクト比が不明な場合、fillプロップを設定し、親にposition: relativeを設定する必要があります。オプションで、目的のストレッチ対クロップ動作に応じてobject-fitスタイルを設定できます：

app/page.js
import Image from 'next/image'

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

試してみてください：

fillプロップのデモ

Theme Detection CSS

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

components/theme-image.module.css
.imgDark {
  display: none;
}

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

TypeScript
JavaScript

components/theme-image.tsx
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} />
    </>
  )
}

components/theme-image.js
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} />
    </>
  )
}

Good to know: デフォルトのloading="lazy"の動作により、正しい画像のみが読み込まれます。priorityやloading="eager"を使用することはできません。これにより、両方の画像が読み込まれるためです。代わりに、fetchPriority="high"を使用できます。

試してみてください：

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

getImageProps

より高度なユースケースのために、getImageProps()を呼び出して、基礎となる<img>要素に渡されるpropsを取得し、それを他のコンポーネント、スタイル、キャンバスなどに渡すことができます。

これにより、ReactのuseState()を呼び出すことを避けることができ、パフォーマンスが向上する可能性がありますが、placeholderプロップと一緒に使用することはできません。プレースホルダーが削除されることはありません。

Theme Detection Picture

ライトモードとダークモードで異なる画像を表示したい場合、<picture>要素を使用して、ユーザーの好みのカラースキームに基づいて異なる画像を表示できます。

app/page.js
import { getImageProps } from 'next/image'

export default function Page() {
  const common = { alt: 'Theme Example', width: 800, height: 400 }
  const {
    props: { srcSet: dark },
  } = getImageProps({ ...common, src: '/dark.png' })
  const {
    props: { srcSet: light, ...rest },
  } = getImageProps({ ...common, src: '/light.png' })

  return (
    <picture>
      <source media="(prefers-color-scheme: dark)" srcSet={dark} />
      <source media="(prefers-color-scheme: light)" srcSet={light} />
      <img {...rest} />
    </picture>
  )
}

Art Direction

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

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

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

Known Browser Bugs

この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を使用する

バージョン履歴

Version	Changes
`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`に名前が変更されました。コードモッドが利用可能ですで、安全かつ自動的にインポートをリネームできます。`<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`が導入されました。

Props​

Required Props​

src​

width​

height​

alt​

Optional Props​

loader​

fill​

sizes​

quality​

priority​

placeholder​

Advanced Props​

style​

onLoadingComplete​

onLoad​

onError​

loading​

blurDataURL​

unoptimized​

overrideSrc​

decoding​

Other Props​

Configuration Options​

localPatterns​

remotePatterns​

domains​

loaderFile​

Advanced​

deviceSizes​

imageSizes​

qualities​

formats​

Caching Behavior​

minimumCacheTTL​

disableStaticImages​

dangerouslyAllowSVG​

contentDispositionType​

Animated Images​

Responsive Images​

Responsive image using a static import​

Responsive image with aspect ratio​

Responsive image with fill​

Theme Detection CSS​

getImageProps​

Theme Detection Picture​

Art Direction​

Background CSS​

Known Browser Bugs​

バージョン履歴​

Props

Required Props

`src`

`width`

`height`

`alt`

Optional Props

`loader`

`fill`

`sizes`

`quality`

`priority`

`placeholder`

Advanced Props

`style`

`onLoadingComplete`

`onLoad`

`onError`

`loading`

`blurDataURL`

`unoptimized`

`overrideSrc`

decoding

Other Props

Configuration Options

`localPatterns`

`remotePatterns`

`domains`

`loaderFile`

Advanced

`deviceSizes`

`imageSizes`

`qualities`

`formats`

Caching Behavior

`minimumCacheTTL`

`disableStaticImages`

`dangerouslyAllowSVG`

`contentDispositionType`

Animated Images

Responsive Images

Responsive image using a static import

Responsive image with aspect ratio

Responsive image with `fill`

Theme Detection CSS

getImageProps

Theme Detection Picture

Art Direction

Background CSS

Known Browser Bugs

バージョン履歴