<Image> (Legacy)

Next.js13 から始まって、next/imagecomponent がパフォーマンスと開発者の経験を改善するために書き直されました。下位互換性のあるアップグレードソリューションを提供するために、古いnext/imageはnext/legacy/imageに名前が変更されました。

新しいnext/image API Referenceをご覧ください

Comparison

next/legacy/imageと比べて、新しいnext/imageの component には以下の変更点があります：

• <span>ラッパーを取り除き、代わりにネイティブ計算アスペクト比 を用いるために<img>を推奨
• style prop の正規サポートを追加します
  • layoutプロップを削除し、代わりにstyleまたはclassNameを優先します
  • objectFitのプロップを削除し、代わりにstyleまたはclassNameを使用します。
  • objectPositionプロップを削除し、代わりにstyleまたはclassNameを優先します
• IntersectionObserverの実装を削除し、ネイティブの lazy loading を優先
  • lazyBoundaryプロパティを削除します。ネイティブの同等物が存在しないため。
  • lazyRootプロップを削除します。これにはネイティブに相当するものがありません。
• loader prop を好むためにloader config を削除します
• altプロップをオプショナルから必須に変更しました
• onLoadingCompleteコールバックを変更して、<img>エレメントへの参照を受け取るようにしました。

Required Props

<Image />の component は次のプロパティが必要です。

src

Must be one of the following:

• 静的にインポートされた image ファイル
• path string 。これは、絶対的な外部の URL 、またはloader プロパティやloader 設定によっては内部の path になることがあります。

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

width

widthプロパティは、描画された width または元の width をピクセル単位で表すことができ、これはlayoutプロパティとsizesプロパティによります。

layout="intrinsic"またはlayout="fixed"を使用すると、widthプロパティはレンダリングされた width をピクセル単位で表現するため、 image がどれほど大きく表示されるかに影響を与えます。

layout="responsive"、layout="fill"を使用する際、widthプロパティは元の width をピクセル単位で表し、これはアスペクト比にのみ影響を与えます。

widthプロパティは必須です、ただし、静的にインポートされた画像や、layout="fill"を持つものは除きます。

height

heightプロパティは、layoutとsizesプロパティによって、表示された height または元の height をピクセル単位で表すことができます。

layout="intrinsic" または layout="fixed" を使用すると、heightプロパティはpixel 描画の height をピクセル単位で表し、したがって image の表示サイズに影響を与えます。

layout="responsive"、layout="fill"を使用するとき、heightプロパティは 元の height をピクセル単位で表しますので、アスペクト比にのみ影響を与えます。

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

Optional Props

The <Image /> component accepts a number of additional properties beyond those which are required. This section describes the most commonly-used properties of the Image component. Find details about more rarely-used properties in the Advanced Props section.

layout

viewport が size を変更すると、image の layout 行動。

• intrinsic layout (default)のデモ
  • intrinsicの場合、image は小さなビューポートのために寸法を縮小しますが、大きなビューポートでは元の寸法を保持します。
• fixed layout のデモ
  • fixedが設定されると、image のサイズは viewport の変更によって変わらない(反応しない)。これはネイティブの img 要素と同様です。
• responsive layout のデモ
  • responsiveの場合、image はより小さなビューポートのために次元を縮小し、より大きなビューポートのために次元を拡大します。
  • 親要素がスタイルシートでdisplay: blockを使用するように確認してください。
• fill layout のデモ
  • fillの場合、image は width と height の両方を親要素の次元に引き延ばしますが、これは親要素が相対である場合に限ります。
  • これは通常、objectFit プロパティとペアになっています。
  • 親要素がスタイルシート内で position: relative を持っていることを確認してください。
• デモ背景 image

loader

URL を解決するために使用されるカスタム関数。Image component のプロッパティに loader を設定すると、imagesセクションのnext.config.jsで定義された default loader が上書きされます。

A loader is a function returning a URL string for the image, given the following parameters:

• src
• width
• quality

Here is an example of using a custom 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

異なるブレークポイントで image の幅がどのようになるかについての情報を提供する string。sizes の value はlayout="responsive"やlayout="fill" を使用する画像のパフォーマンスに大きな影響を及ぼします。layout="intrinsic"やlayout="fixed"を使用する画像では無視されます。

The sizes property serves two important purposes related to image performance:

まず、value の sizes の値は、自動的に生成された next/legacy/image の source セットからどの size の image をダウンロードするかをブラウザが判断するために使用されます。ブラウザが選択する時点では、ページ上の image の size がまだわかっていないので、その size が viewport と同じかそれ以上の image を選択します。 sizes プロパティを使用すると、ブラウザに対して image がフルスクリーンよりも小さいことを通知することができます。もし sizes の value を設定しない場合、default の default value として 100vw(フルスクリーンの width)が使用されます。

次に、sizes value が解析され、自動的に作成された source セットの値をトリムするために使用されます。もしsizesプロパティが、50vwのような viewport width のパーセンテージを表す sizes を含んでいる場合、その source セットは、決して必要とされないほど小さな値を含まないようにトリムされます。

For example, if you know your styling will cause an image to be full-width on mobile devices, in a 2-column layout on tablets, and a 3-column layout on desktop displays, you should include a sizes property such as the following:

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

This example sizes could have a dramatic effect on performance metrics. Without the 33vw sizes, the image selected from the server would be 3 times as wide as it needs to be. Because file size is proportional to the square of the width, without sizes the user would download an image that's 9 times larger than necessary.

Learn more about srcset and sizes:

• web.dev
• mdn

quality

最適化された image の quality ，1と100の間の整数で、100が最高の quality を示します。 default は75です。

priority

When true, the image will be considered high priority and preload . Lazy loading is automatically disabled for images using priority.

You should use the priority property on any image detected as the Largest Contentful Paint (LCP) element. It may be appropriate to have multiple priority images, as different images may be the LCP element for different viewport sizes.

Should only be used when the image is visible above the fold. Defaults to false.

placeholder

image がロード中の間に使用する''placeholder''。可能な values は blur または empty です。default は empty です。

blurの際には、blurDataURL プロパティが placeholder として使用されます。もしsrcがstatic importからの object であり、インポートされた image のフォーマットが.jpg、.png、.webp、または.avifである場合、blurDataURLは自動的に補充されます。

For dynamic images, you must provide the blurDataURL property. Solutions such as Plaiceholder can help with base64 generation.

When empty, there will be no placeholder while the image is loading, only empty space.

Try it out:

• blur placeholder のデモ
• blurDataURLプロパティを使ってシマー効果をデモする
• blurDataURLプロップでカラーエフェクトをデモ

Advanced Props

In some cases, you may need more advanced usage. The <Image /> component optionally accepts the following advanced properties.

style

基本的な image 要素にCSS styles を渡すことを許可します。

すべての layout モードは、自身の styles を image 要素に適用し、これらの自動的な styles は style prop よりも優先されることに注意してください。

また、必要なwidthとheightの props があなたのスタイリングと相互に作用することを覚えておいてください。画像のwidthをスタイリングで変更する場合、height="auto"の style も設定しなければならず、そうしないとあなたの image は歪むことになります。

objectFit

"layout="fill"を使用しているとき、image が親の container にどのようにフィットするかを定義します。

この value は、src image のためのobject-fit CSS property に渡されます。

objectPosition

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

この value は、image に適用されたobject-position CSS property に渡されます。

onLoadingComplete

A callback function that is invoked once the image is completely loaded and the placeholder has been removed.

onLoadingComplete関数は 1 つのパラメータを受け入れます。それは以下のプロパティを持つ object です：

• naturalWidth
• naturalHeight

loading

注意: このプロパティは高度な使用を意図したものです。切り替えると eagerでロードする image は通常、パフォーマンスを損ないます。

代わりに、priority プロパティを使用することをおすすめしますが、 image をほぼすべての使用ケースで熱心に適切にロードします。

The loading behavior of the image. Defaults to lazy.

When lazy, defer loading the image until it reaches a calculated distance from the viewport.

When eager, load the image immediately.

blurDataURL

A Data URL to be used as a placeholder image before the src image successfully loads. Only takes effect when combined with placeholder="blur".

Must be a base64-encoded image. It will be enlarged and blurred, so a very small image (10px or less) is recommended. Including larger images as placeholders may harm your application performance.

Try it out:

• blurDataURLプロパティの default をデモする
• blurDataURLプロパティを使ってシマー効果をデモする
• blurDataURLプロップでカラーエフェクトをデモする

You can also generate a solid color Data URL to match the image.

lazyBoundary

string(マージンプロパティと同様の syntax)を使用して、viewport と image の交差を検出し、lazy loadingをトリガするためのバウンディングボックスとして働きます。default は"200px"です。

もし image が root document 以外の Scroll 可能な親要素にネストされている場合、lazyRootプロパティも割り当てる必要があります。

lazyRoot

Scroll 可能な親要素を指す ReactRef 。default はnull(document viewport)。

Ref は、DOM 要素または基礎となる DOM 要素に Ref を転送する React component を指す必要があります。

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 component を指し示す例

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

When true, the source image will be served as-is instead of changing quality, size, or format. Defaults to false.

import Image from "next/image";

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

Since Next.js 12.3.0, this prop can be assigned to all images by updating next.config.js with the following configuration:

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

Other Props

Other properties on the <Image /> component will be passed to the underlying img element with the exception of the following:

• srcSet. 代わりにDevice Sizesを使用してください。
• refを使用します。代わりにonLoadingCompleteを使用してください。
• decoding. It is always "async".

Configuration Options

リモートパターン

To protect your application from malicious users, configuration is required in order to use external images. This ensures that only external images from your account can be served from the Next.js Image Optimization API. These external images can be configured with the remotePatterns property in your next.config.js file, as shown below:

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

Good to know: 上記の例では、next/legacy/imageのsrcプロパティは https://example.com/account123/で start しなければなりません。他のプロトコル、 hostname 、 port 、または一致しない path は 400 Bad Request を返します。

Below is another example of the remotePatterns property in the next.config.js file:

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

Good to know: 上記の例により、next/legacy/imageのsrcプロパティは、https://img1.example.com または https://me.avatar.example.com または任意の数のサブドメインで 始まる 必要があります。それ以外のプロトコル、ポート、または一致しないホスト名は、400 Bad Request と返答します。

pathnameとhostnameの両方でワイルドカードパターンを使用することができ、次の構文があります：

• * は単一のパスセグメントまたはサブドメインに一致します
• ** はパターンの終わりにある任意の数のパスセグメントまたは始まりにあるサブドメインに一致します

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

Good to know: protocol、port、またはpathnameを省略すると、ワイルドカード**が暗黙的に適用されます。これは推奨されません。なぜなら、意図しない URL を最適化する機会を悪意のある行為者に提供する可能性があるからです。

Domains

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

remotePatternsと同様に、domains設定を使用して、外部イメージの許可されたホスト名のリストを提供することができます。

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

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

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

Loader 設定

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

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

ビルトインローダー

次の Image Optimization クラウドプロバイダーが含まれています:

• Default：next dev、next start、またはカスタムの server と自動的に動作します。
• Vercel ：Vercel に deploy すると自動的に機能します、設定の必要はありません。詳しくはこちら
• Imgix : loader: 'imgix'
• Cloudinary : loader: 'cloudinary'
• Akamai : loader: 'akamai'
• Custom：loader: 'custom'により、next/legacy/image component のloaderプロップを実装することで、カスタムクラウドプロバイダーを使用します。

異なるプロバイダーが必要な場合、next/legacy/imageと共にloaderプロップを使用できます。

画像はoutput: 'export'を使用する build 時に最適化することはできず、オンデマンドのみ可能です。next/legacy/imageをoutput: 'export'と共に使用するには、default とは異なる別の loader を使用する必要があります。 詳細は議論をご覧ください。

next/legacy/imageComponent の default loader はsquoosh を使用しています。それはインストールが速く、development 環境に適しているからです。next startを production 環境で使用する場合、プロジェクトディレクトリでnpm i sharpを実行してsharp をインストールすることを強く推奨します。ただし、Vercel のデプロイメントでは必要ありません。なぜなら、sharpは自動的にインストールされるからです。

Advanced

以下の設定は高度な使用例のためのもので、通常は必要ありません。以下のプロパティを設定する場合、将来のアップデートでの Next.js のデフォルトの変更が上書きされます。

デバイス Sizes

"あなたがユーザーの予想デバイス幅を知っている場合は、 next.config.jsのdeviceSizesプロパティを使用して、「width ブレークポイント」のリストを指定することができます。これらの幅は、next/legacy/imageの component が layout="responsive"または layout="fill" を使用してユーザーのデバイスに適した image が提供されることを確認するために使用されます。

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

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

Image Sizes

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

2 つのリストが別々にある理由は、imageSizes がsizesプロパティを提供する画像にのみ使用され、その画像が画面の全幅よりも小さいことを示しているためです。したがって、imageSizes 内のサイズはすべて、deviceSizes 内の最小サイズよりも小さくなければなりません。

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

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

受け入れ可能な Formats

default のImage Optimization APIは、request のAcceptヘッダを介してブラウザがサポートする image 形式を自動的に検出します。

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

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

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

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

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

Good to know: AVIF は一般的にエンコードに 20%長い時間がかかりますが、WebP と比較して 20%小さく圧縮します。これは、 image が最初に要求されたときは通常遅く、その後のキャッシュされた要求はより速くなることを意味します。

Caching Behavior

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

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

image の cache 状態は、x-nextjs-cache(Vercel にデプロイされた場合はx-vercel-cache)の value を読み取ることで決定できます。 response header の可能な値は次のとおりです：

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

minimumCacheTTL設定または上流の image Cache-Control header が定義する有効期限(むしろ最大期間)は、どちらか大きい方によって決まります。具体的には、Cache-Control header のmax-age value が使用されます。s-maxageとmax-ageの両方が見つかった場合は、s-maxageが優先されます。max-ageは、CDN やブラウザを含む任意の下流 clients にも通過します。

• あなたは、上流の image にCache-Controlheader が含まれていないか、value が非常に低い場合に、cache の期間を延ばすために、minimumCacheTTLを設定することができます。
• あなたは、deviceSizesとimageSizesを設定することで、生成される可能性のある画像の総 number を減らすことができます。
• formatsを設定して、複数の formats を無効にし、単一の image フォーマットを優先することができます。

最小の Cache TTL

キャッシュされた最適化画像の Live(TTL)を秒単位で設定することができます。多くの場合、ファイル内容を自動的にハッシュし、cache と image をCache-Controlheader のimmutableで永久に保持する静的 Image Importを使用する方が良いです。

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

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

image ごとのキャッシュ動作を変更する必要がある場合、headersを設定して、上流の image(例：/some-asset.jpg、/_next/image自体ではありません)にCache-Controlheader を設定できます。

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

スタティックインポートを無効にする

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

場合によっては、インポートの動作が他のプラグインと競合する場合、この機能を無効にすることが望ましいかもしれません。

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を設定できます：

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

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

アニメーション画像

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

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

Version History