<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 要素になる可能性があるため、複数の優先画像を持つことが適切な場合があります。

画像が折り返し線より上で表示される場合にのみ使用してください。デフォルトは 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/**',
      },
    ],
  },
}

知っておくと良い: 上記の例では、next/legacy/imageのsrcプロパティがhttps://example.com/account123/で始まる必要があります。他のプロトコル、ホスト名、ポート、または一致しないパスは400 Bad Requestで応答されます。

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

next.config.js

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

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

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

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

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

ドメイン

警告: 悪意のあるユーザーからアプリケーションを保護するため、domainsではなく厳格な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を設定できます。
複数のフォーマットを無効にして単一の画像フォーマットを優先するために、フォーマットを設定できます。

最小キャッシュ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)ヘッダーがないと脆弱性につながる可能性があります。

デフォルトの画像最適化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