<Image>

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

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

プロパティ

Imageコンポーネントで使用可能なプロパティの概要を以下に示します。

必須プロパティ

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

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`プロパティに応じて、絶対外部URLまたは内部パスのいずれかになります。

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

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

width

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

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

height

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

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

補足情報

• width と height プロパティは組み合わせて使用され、画像のアスペクト比を決定します。ブラウザは、このアスペクト比を使用して、画像が読み込まれる前に画像のための領域を確保します。
• 固有サイズは、ブラウザでのレンダリングサイズを必ずしも意味するものではありません。レンダリングサイズは親コンテナによって決定されます。たとえば、親コンテナが固有サイズよりも小さい場合、画像はコンテナに合わせて縮小されます。
• 幅と高さが不明な場合は、fill プロパティを使用できます。

alt

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

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

画像が純粋に装飾的なものであるか、ユーザー向けではない場合は、alt プロパティは空文字列 (alt="") である必要があります。

詳細はこちら

オプションのプロパティ

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

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

補足情報: 関数を引数に取る loader のようなプロパティを使用するには、提供された関数をシリアライズするためにクライアントコンポーネントを使用する必要があります。

あるいは、next.config.js 内の loaderFile 設定を使用して、プロパティを渡さずにアプリケーション内のすべての next/image のインスタンスを構成できます。

fill

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

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

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

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

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

あるいは、object-fit: "cover" を使用すると、画像はコンテナ全体を満たし、アスペクト比を維持するためにトリミングされます。

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

• position
• object-fit
• object-position

sizes

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

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

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

priority

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

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

Largest Contentful Paint (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/...の場合、画像の読み込み中にData URLがプレースホルダーとして使用されます。

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

お試しください

• blurプレースホルダーのデモ
• Data URL placeholderプロパティを使用したシマー効果のデモ
• blurDataURLプロパティを使用したカラー効果のデモ

高度なプロパティ

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

style

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

const imageStyle = {
  borderRadius: '50%',
  border: '1px solid #fff',
}
 
export default function ProfileImage() {
  return <Image src="..." style={imageStyle} />
}

必要な幅と高さのプロパティは、スタイリングと相互作用することに注意してください。スタイリングを使用して画像の幅を変更する場合は、本来のアスペクト比を維持するために高さをautoに設定する必要があります。そうでない場合、画像は歪んでしまいます。

onLoadingComplete

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

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

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

コールバック関数は、基礎となる<img>要素への参照を1つの引数として呼び出されます。

参考情報: 関数を引数として受け取るonLoadingCompleteなどのプロパティを使用するには、提供された関数をシリアル化するためにクライアントコンポーネントを使用する必要があります。

onLoad

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

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

コールバック関数は、基礎となる<img>要素を参照するtargetを持つEventを1つの引数として呼び出されます。

参考情報: 関数を引数として受け取るonLoadなどのプロパティを使用するには、提供された関数をシリアル化するためにクライアントコンポーネントを使用する必要があります。

onError

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

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

参考情報: 関数を引数として受け取るonErrorなどのプロパティを使用するには、提供された関数をシリアル化するためにクライアントコンポーネントを使用する必要があります。

loading

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

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

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

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

loading属性の詳細をご覧ください。

blurDataURL

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

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

お試しください

• デフォルトのblurDataURLプロップのデモ
• blurDataURLプロパティを使用したカラー効果のデモ

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

unoptimized

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

trueの場合、ソース画像は画質、サイズ、形式を変更せずにそのまま配信されます。デフォルトはfalseです。

import Image from 'next/image'
 
const UnoptimizedImage = (props) => {
  return <Image {...props} unoptimized />
}

Next.js 12.3.0以降、次の設定でnext.config.jsを更新することにより、このプロパティをすべての画像に割り当てることができます。

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

overrideSrc

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

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

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

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

<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属性の詳細については、こちらをご覧ください。

その他のプロップ

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

• srcSet。代わりにデバイスサイズを使用してください。

設定オプション

プロップに加えて、next.config.jsでImageコンポーネントを設定できます。使用可能なオプションは以下のとおりです。

localPatterns

特定のパスを最適化し、他のすべてのパスをブロックするために、必要に応じてnext.config.jsファイルでlocalPatternsを設定できます。

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

重要: 上記の例では、next/imageのsrcプロパティは/assets/images/で始まる必要があり、クエリ文字列を含めることはできません。他のパスを最適化しようとすると、400 Bad Requestが返されます。

remotePatterns

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

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

重要: 上記の例では、next/imageのsrcプロパティはhttps://example.com/account123/で始まる必要があり、クエリ文字列を含めることはできません。他のプロトコル、ホスト名、ポート、または一致しないパスは、400 Bad Requestが返されます。

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

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

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

ワイルドカードパターンはpathnameとhostnameの両方で使用でき、構文は以下のとおりです。

• * パスセグメントまたはサブドメインを1つにマッチします。
• ** 末尾のパスセグメントまたは先頭のサブドメインをいくつでもマッチします。

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

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

次に、searchを使用したnext.config.jsファイルのremotePatternsプロパティの例を示します。

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が返されます。

domains

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

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

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

次に、next.config.jsファイルのdomainsプロパティの例を示します。

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

loaderFile

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

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

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

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

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

例

• カスタムイメージローダーの設定

重要: 関数を受け取るイメージローダーファイルをカスタマイズするには、提供された関数をシリアライズするためにクライアントコンポーネントを使用する必要があります。

高度な設定

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

deviceSizes

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

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

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

imageSizes

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

2つの別々のリストがある理由は、imageSizesは、sizesプロパティを提供する画像（画面の全幅より狭い画像を示す）に対してのみ使用されるためです。したがって、imageSizesのサイズは、deviceSizesの最小サイズより小さい必要があります。

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

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

formats

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

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

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

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

次の設定で、AVIFサポートを有効にしてWebPにフォールバックできます。

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

補足情報:

• AVIFは一般的にエンコードに50％長く時間がかかりますが、WebPと比較して20％小さく圧縮されます。これは、画像が最初に要求されたときは通常遅くなりますが、キャッシュされた後続のリクエストは高速になることを意味します。
• Next.jsの前にプロキシ/CDNでセルフホストする場合は、プロキシでAcceptヘッダーを転送するように設定する必要があります。

キャッシュ動作

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

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

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

• MISS - パスはキャッシュにありません（初回アクセス時のみ発生します）。
• 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）を秒単位で設定できます。多くの場合、ファイルの内容を自動的にハッシュし、Cache-Controlヘッダーにimmutableを設定して画像を永久にキャッシュする静的画像インポートを使用する方が優れています。

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

最適化された画像の有効期限（または最大有効期間）は、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内で静的画像インポートを無効にできます。

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

dangerouslyAllowSVG

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

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

ただし、デフォルトの画像最適化APIを使用してSVG画像を提供する必要がある場合は、next.config.js内でdangerouslyAllowSVGを設定できます。

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を設定して、直接アクセスしたときにブラウザが画像をダウンロードせずにレンダリングできるようにすることができます。

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

アニメーション画像

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

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

レスポンシブ画像

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

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

静的インポートを使用したレスポンシブ画像

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

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

お試しください

• ビューポートにレスポンシブな画像のデモ

アスペクト比を指定したレスポンシブ画像

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

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プロパティを設定し、親要素にposition: relativeを設定する必要があります。必要に応じて、目的のストレッチとクロップの動作に応じてobject-fitスタイルを設定することもできます。

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プロパティのデモ

テーマ検出CSS

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

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

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

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

お試しください

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

getImageProps

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

これにより、ReactのuseState()の呼び出しを回避できるため、パフォーマンスが向上しますが、プレースホルダーは削除されないため、placeholderプロパティと共に使用することはできません。

テーマ検出画像

ライトモードとダークモードで異なる画像を表示したい場合は、ユーザーの優先カラーテーマに基づいて異なる画像を表示するために、<picture>要素を使用できます。

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

アートディレクション

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

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

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

既知のブラウザのバグ

この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 を使用してください。

バージョン履歴