<Image>（レガシー）

例

レガシー Image コンポーネント

Next.js 13 以降、next/image コンポーネントはパフォーマンスと開発者体験を向上させるために書き直されました。後方互換性のあるアップグレードソリューションを提供するため、旧 next/image は next/legacy/image に名称変更されました。

新しい next/image API リファレンスを参照してください。

比較

next/legacy/image と比較して、新しい next/image コンポーネントには以下の変更点があります:

<img> 周囲の <span> ラッパーを削除し、ネイティブの計算されたアスペクト比を採用
標準的な style プロパティのサポートを追加
- layout プロパティを削除し、style または className で代替
- objectFit プロパティを削除し、style または className で代替
- objectPosition プロパティを削除し、style または className で代替
IntersectionObserver の実装を削除し、ネイティブの遅延読み込みを採用
- ネイティブ相当がないため lazyBoundary プロパティを削除
- ネイティブ相当がないため lazyRoot プロパティを削除
loader 設定を削除し、loader プロパティで代替
alt プロパティをオプションから必須に変更
onLoadingComplete コールバックが <img> 要素への参照を受け取るように変更

必須プロパティ

<Image /> コンポーネントには以下のプロパティが必須です。

src

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

静的インポートされた画像ファイル
パス文字列。loader プロパティまたは loader 設定に応じて、外部の絶対URLまたは内部パス

外部URLを使用する場合、next.config.js の remotePatterns に追加する必要があります。

width

width プロパティは、layout と sizes プロパティに応じて、ピクセル単位の レンダリング 幅または元の幅を表します。

layout="intrinsic" または layout="fixed" を使用する場合、width プロパティはピクセル単位の レンダリング 幅を表すため、画像の表示サイズに影響します。

layout="responsive"、layout="fill" を使用する場合、width プロパティはピクセル単位の元の幅を表すため、アスペクト比にのみ影響します。

width プロパティは、静的インポートされた画像または layout="fill" の場合を除き必須です。

height

height プロパティは、layout と sizes プロパティに応じて、ピクセル単位の レンダリング 高さまたは元の高さを表します。

layout="intrinsic" または layout="fixed" を使用する場合、height プロパティはピクセル単位の レンダリング 高さを表すため、画像の表示サイズに影響します。

layout="responsive"、layout="fill" を使用する場合、height プロパティはピクセル単位の元の高さを表すため、アスペクト比にのみ影響します。

height プロパティは、静的インポートされた画像または layout="fill" の場合を除き必須です。

オプションプロパティ

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

layout

ビューポートのサイズ変更に伴う画像のレイアウト動作。

`layout`	動作	`srcSet`	`sizes`	ラッパーとサイザーあり
`intrinsic` (デフォルト)	コンテナの幅に合わせて縮小、画像サイズまで拡大	`1x`, `2x` (imageSizes に基づく	N/A	はい
`fixed`	`width` と `height` で指定されたサイズに固定	`1x`, `2x` (imageSizes に基づく	N/A	はい
`responsive`	コンテナの幅に合わせて拡縮	`640w`, `750w`, ... `2048w`, `3840w` (imageSizes と deviceSizes に基づく	`100vw`	はい
`fill`	X軸とY軸の両方でコンテナを埋めるように拡大	`640w`, `750w`, ... `2048w`, `3840w` (imageSizes と deviceSizes に基づく	`100vw`	はい

intrinsic レイアウトのデモ（デフォルト）
- intrinsic の場合、画像は小さなビューポートでは縮小されますが、大きなビューポートでは元の寸法を維持します。
fixed レイアウトのデモ
- fixed の場合、画像の寸法はビューポートの変更に伴って変化しません（レスポンシブでない）、ネイティブの img 要素と同様です。
responsive レイアウトのデモ
- responsive の場合、画像は小さなビューポートでは縮小され、大きなビューポートでは拡大されます。
- 親要素のスタイルシートで display: block を使用していることを確認してください。
fill レイアウトのデモ
- fill の場合、画像は親要素の寸法に合わせて幅と高さを伸縮します（親要素が相対位置である場合）。
- これは通常 objectFit プロパティと組み合わせて使用されます。
- 親要素のスタイルシートに position: relative があることを確認してください。
背景画像のデモ

loader

URLを解決するためのカスタム関数。Image コンポーネントのプロパティとして loader を設定すると、next.config.js の images セクションで定義されたデフォルトの loader が上書きされます。

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

src
width
quality

カスタム loader の使用例:

import Image from 'next/legacy/image'

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

const MyImage = (props) => {
  return (
    <Image
      loader={myLoader}
      src="me.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  )
}

sizes

異なるブレークポイントでの画像の幅に関する情報を提供する文字列。sizes の値は、layout="responsive" または layout="fill" を使用する画像のパフォーマンスに大きく影響します。layout="intrinsic" または layout="fixed" を使用する画像では無視されます。

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

第一に、sizes の値は、ブラウザが next/legacy/image の自動生成されたソースセットからどのサイズの画像をダウンロードするかを決定するために使用されます。ブラウザが選択する時点では、ページ上の画像のサイズがわからないため、ビューポートと同じサイズまたはそれ以上の画像を選択します。sizes プロパティを使用すると、画像が実際にはフルスクリーンより小さいことをブラウザに伝えることができます。sizes 値を指定しない場合、デフォルト値の 100vw（フルスクリーン幅）が使用されます。

第二に、sizes 値は解析され、自動生成されたソースセットの値をトリミングするために使用されます。sizes プロパティに 50vw などのビューポート幅の割合を表すサイズが含まれている場合、ソースセットは不要な小さな値を含まないようにトリミングされます。

例えば、モバイルデバイスではフル幅、タブレットでは2列レイアウト、デスクトップでは3列レイアウトになることがわかっている場合、次のような sizes プロパティを含めるべきです:

import Image from 'next/legacy/image'
const Example = () => (
  <div className="grid-element">
    <Image
      src="/example.png"
      layout="fill"
      sizes="(max-width: 768px) 100vw,
              (max-width: 1200px) 50vw,
              33vw"
    />
  </div>
)

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

srcset と sizes についてさらに学ぶ:

web.dev
mdn

quality

最適化された画像の品質で、1 から 100 の整数（100 が最高品質）。デフォルトは 75。

priority

true の場合、画像は高優先度と見なされ、プリロードされます。priority を使用する画像では、遅延読み込みが自動的に無効になります。

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

画像が画面内（above the fold）に表示される場合にのみ使用してください。デフォルトは false。

placeholder

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

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

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

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

デモを試す:

高度なプロパティ

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

style

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

すべての layout モードは画像要素に独自のスタイルを適用し、これらの自動スタイルは style プロパティよりも優先されることに注意してください。

また、必須の width と height プロパティがスタイルと相互作用する可能性があることにも注意してください。スタイルを使用して画像の width を変更する場合、height="auto" スタイルも設定する必要があります。そうしないと画像が歪む可能性があります。

objectFit

layout="fill" を使用する場合、画像が親コンテナにどのようにフィットするかを定義します。

この値は src 画像の object-fit CSSプロパティに渡されます。

objectPosition

layout="fill" を使用する場合、画像が親要素内でどのように配置されるかを定義します。

この値は画像に適用される object-position CSSプロパティに渡されます。

onLoadingComplete

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

onLoadingComplete 関数は、以下のプロパティを持つオブジェクトを1つのパラメータとして受け取ります:

loading

注意: このプロパティは高度な使用のみを目的としています。画像を eager で読み込むように切り替えると、通常 パフォーマンスが低下 します。

代わりに priority プロパティを使用することをお勧めします。これはほぼすべてのユースケースで適切に画像を積極的に読み込みます。

画像の読み込み動作。デフォルトは lazy。

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

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

詳細を学ぶ

blurDataURL

src 画像が正常に読み込まれる前にプレースホルダー画像として使用される Data URL。placeholder="blur" と組み合わせた場合にのみ効果があります。

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

デモを試す:

画像に合わせた単色のData URLを生成することもできます。

lazyBoundary

ビューポートと画像の交差を検出し、遅延読み込みをトリガーするために使用される境界ボックスとして機能する文字列（marginプロパティと同様の構文）。デフォルトは "200px"。

画像がルートドキュメント以外のスクロール可能な親要素内にある場合、lazyRoot プロパティも割り当てる必要があります。

詳細を学ぶ

lazyRoot

スクロール可能な親要素を指すReactのRef。デフォルトは null（ドキュメントビューポート）。

RefはDOM要素または基礎となるDOM要素にRefを転送するReactコンポーネントを指している必要があります。

DOM要素を指す例

import Image from 'next/legacy/image'
import React from 'react'

const Example = () => {
  const lazyRoot = React.useRef(null)

  return (
    <div ref={lazyRoot} style={{ overflowX: 'scroll', width: '500px' }}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </div>
  )
}

Reactコンポーネントを指す例

import Image from 'next/legacy/image'
import React from 'react'

const Container = React.forwardRef((props, ref) => {
  return (
    <div ref={ref} style={{ overflowX: 'scroll', width: '500px' }}>
      {props.children}
    </div>
  )
})

const Example = () => {
  const lazyRoot = React.useRef(null)

  return (
    <Container ref={lazyRoot}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </Container>
  )
}

詳細を学ぶ

unoptimized

trueに設定すると、ソース画像は品質、サイズ、フォーマットを変更せずにそのまま配信されます。デフォルトはfalseです。

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

その他のプロパティ

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

srcSet。代わりにデバイスサイズを使用してください。
ref。代わりにonLoadingCompleteを使用してください。
decoding。常に"async"です。

設定オプション

リモートパターン

悪意のあるユーザーからアプリケーションを保護するため、外部画像を使用するには設定が必要です。これにより、Next.jsの画像最適化APIを通じて配信される外部画像をあなたのアカウントのものに限定できます。これらの外部画像は、以下のようにnext.config.jsファイルのremotePatternsプロパティで設定できます:

next.config.js

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

知っておくと良い: 上記の例では、next/legacy/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: '',
      },
    ],
  },
}

知っておくと良い: 上記の例では、next/legacy/imageのsrcプロパティはhttps://img1.example.comまたはhttps://me.avatar.example.com、または任意の数のサブドメインで始まる必要があります。ポートやクエリ文字列を持つことはできません。他のプロトコルや一致しないホスト名は400 Bad Requestで応答されます。

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

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

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

知っておくと良い: 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',
      },
    ],
  },
}

知っておくと良い: 上記の例では、next/legacy/imageのsrcプロパティはhttps://assets.example.comで始まり、正確なクエリ文字列?v=1727111025337を持つ必要があります。他のプロトコルやクエリ文字列は400 Bad Requestで応答されます。

ドメイン

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

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

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

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

next.config.js

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

ローダー設定

Next.jsの組み込み画像最適化APIの代わりにクラウドプロバイダーを使用して画像を最適化したい場合、next.config.jsファイルでloaderとpathプレフィックスを設定できます。これにより、Imageのsrcに相対URLを使用し、プロバイダー向けの正しい絶対URLを自動生成できます。

next.config.js

module.exports = {
  images: {
    loader: 'imgix',
    path: 'https://example.com/myaccount/',
  },
}

組み込みローダー

以下の画像最適化クラウドプロバイダーが含まれています:

デフォルト: next dev、next start、またはカスタムサーバーで自動的に動作
Vercel: Vercelにデプロイ時に自動的に動作、設定不要。詳細
Imgix: loader: 'imgix'
Cloudinary: loader: 'cloudinary'
Akamai: loader: 'akamai'
カスタム: loader: 'custom' next/legacy/imageコンポーネントのloaderプロパティを実装してカスタムクラウドプロバイダーを使用

他のプロバイダーが必要な場合は、next/legacy/imageでloaderプロパティを使用できます。

output: 'export'を使用すると、ビルド時ではなくオンデマンドでのみ画像を最適化できます。output: 'export'でnext/legacy/imageを使用するには、デフォルト以外のローダーを使用する必要があります。ディスカッションで詳細を読む

next/legacy/imageコンポーネントのデフォルトローダーは、開発環境に適しておりインストールが速いsquooshを使用します。本番環境でnext startを使用する場合、プロジェクトディレクトリでnpm i sharpを実行してsharpをインストールすることを強く推奨します。Vercelデプロイでは自動的にsharpがインストールされるため不要です。

高度な設定

以下の設定は高度な使用例向けで、通常は不要です。以下のプロパティを設定すると、将来のNext.jsのデフォルト更新を上書きします。

デバイスサイズ

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

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

next.config.js

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

画像サイズ

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

許容フォーマット

デフォルトの画像最適化APIは、リクエストのAcceptヘッダーを通じてブラウザがサポートする画像フォーマットを自動的に検出します。

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

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

next.config.js

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

以下の設定でAVIFサポートを有効にできます。

next.config.js

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

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

キャッシュ動作

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

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

画像のキャッシュ状態は、x-nextjs-cache（Vercelにデプロイ時はx-vercel-cache）レスポンスヘッダーの値を読み取ることで確認できます。可能な値は以下の通りです:

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

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

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

最小キャッシュTTL

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

next.config.js

module.exports = {
  images: {
    minimumCacheTTL: 60,
  },
}

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

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

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

静的インポートの無効化

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

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

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

next.config.js

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

SVGの危険な許可

デフォルトのローダーはいくつかの理由でSVG画像を最適化しません。第一に、SVGはベクター形式であり、ロスレスでサイズ変更できます。第二に、SVGにはHTML/CSSと同様の機能が多く、適切なContent Security Policy (CSP) ヘッダーがないと脆弱性につながる可能性があります。

したがって、srcプロパティがSVGであることがわかっている場合、unoptimizedプロパティを使用することを推奨します。これはsrcが".svg"で終わる場合に自動的に行われます。

ただし、デフォルトの画像最適化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を設定することを強く推奨します。

アニメーション画像

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

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

バージョン履歴

バージョン	変更点
`v13.0.0`	`next/image`が`next/legacy/image`に改名

On this page