Menu

<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を使用する場合、ソース画像について次の点も考慮してください：

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

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動作srcSetsizesラッパーとサイザーの有無
intrinsic（デフォルト）コンテナの幅に合わせて_縮小_、画像サイズまで1x、2x（imageSizesに基づく）該当なしあり
fixedwidthとheightに正確にサイズ設定1x、2x（imageSizesに基づく）該当なしあり
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文字列を返す関数です：

カスタム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 の sizes がない場合、サーバーから選択される画像は必要以上に3倍の幅になります。ファイルサイズは幅の2乗に比例するため、sizes がない場合、ユーザーは必要以上に9倍大きな画像をダウンロードすることになります。

詳細については、srcset と sizes について以下を参照してください：

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

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

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

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

詳細情報

blurDataURL

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

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

試してみましょう：

ソリッドカラーのデータURLを生成して、画像に合わせることもできます。

lazyBoundary

マージンプロパティと同様の文法を持つ文字列で、ビューポートと画像の交差を検出し、遅延読み込みをトリガーする境界ボックスとして機能します。デフォルトは "200px"。

画像がルート文書以外のスクロール可能な親要素にネストされている場合、lazyRoot プロップも割り当てる必要があります。

詳細情報

lazyRoot

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

Refは、DOM要素またはRefを基底のDOM要素に転送する 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 要素に渡されます：

設定オプション

リモートパターン

悪意のあるユーザーからアプリケーションを保護するため、外部画像を使用するには設定が必要です。これにより、Next.js Image Optimization 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で応答します。

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

  • * は1つのパスセグメントまたはサブドメインと一致します
  • ** は末尾の任意の数のパスセグメントまたは先頭の任意の数のサブドメインと一致します

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

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

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

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 の組み込み Image Optimization API の代わりにクラウドプロバイダを使用して画像を最適化する場合、next.config.js ファイルで loader と path プレフィックスを設定できます。これにより、Image の src に相対 URL を使用し、プロバイダ用の正確な絶対 URL を自動的に生成できます。

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

組み込みローダー

以下の Image Optimization クラウドプロバイダが含まれています：

  • デフォルト: 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.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],
  },
}

許容される形式

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

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

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

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

AVIFのサポートを有効にし、以下の設定でWebPにフォールバックすることができます。

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

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

キャッシングの動作

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

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

画像のキャッシュステータスは、x-nextjs-cache（Vercelにデプロイされている場合はx-vercel-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を設定して、生成される画像の総数を削減できます。
  • フォーマットを設定して、単一の画像フォーマットに有利に複数のフォーマットを無効にできます。

最小キャッシュTTL

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

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

最適化された画像の有効期限（または最大有効期間）は、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と同様の多くの機能を持っており、適切なコンテンツセキュリティポリシー（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を設定することを強くお勧めします。

contentDispositionType

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

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

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

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

アニメーション画像

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

アニメーションファイルの自動検出は最善の努力であり、GIF、APNG、WebPをサポートします。特定のアニメーション画像に対して画像最適化を明示的にバイパスする場合は、unoptimizedプロパティを使用します。

バージョン履歴

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