<Image>
この API リファレンスは、Image コンポーネントで利用可能な props や設定オプションの使い方を理解するのに役立ちます。機能や使い方については、 Image コンポーネントのページを参照してください。
import Image from 'next/image'
export default function Page() {
return (
<Image
src="/profile.png"
width={500}
height={500}
alt="Picture of the author"
/>
)
}
Props
Image コンポーネントで使用可能な主な Props は以下のとおりです:
Prop | Example | Type | Required |
---|---|---|---|
src | src="/profile.png" | String | Yes |
width | width={500} | Integer (px) | Yes |
height | height={500} | Integer (px) | Yes |
alt | alt="Picture of the author" | String | Yes |
loader | loader={imageLoader} | Function | - |
fill | fill={true} | Boolean | - |
sizes | sizes="(max-width: 768px) 100vw" | String | - |
quality | quality={80} | Integer (1-100) | - |
priority | priority={true} | Boolean | - |
placeholder | placeholder="blur" | String | - |
style | style={{objectFit: "contain"}} | Object | - |
onLoadingComplete | onLoadingComplete={img => done()} | Function | 非推奨 |
onLoad | onLoad={event => done()} | Function | - |
onError | onError(event => fail()} | Function | - |
loading | loading="lazy" | String | - |
blurDataURL | blurDataURL="data:image/jpeg..." | String | - |
必須の Props
Image コンポーネントには、src
、width
、height
、alt
の各属性が必須です。
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
以下のどちらかを指定する必要があります:
外部 URL を使用する場合は、next.config.js
のremotePatternsに追加する必要があります。
width
width
プロパティはレンダリングされる幅をピクセル単位で表し、画像が表示される大きさに影響します。
静的にインポートされた画像やfill
プロパティを持つ画像を除き、必須です。
height
height
プロパティはレンダリングの高さをピクセル単位で表し、画像が表示される大きさに影響します。
静的にインポートされた画像やfill
プロパティを持つ画像を除き、必須です。
alt
alt
プロパティは、スクリーンリーダーや検索エンジンのために画像を説明するために使用されます。また画像が無効になっていたり、画像の読み込み中にエラーが発生した場合の代替テキストでもあります。
alt
プロパティには、ページの意味を変えることなく画像を置き換えることができるテキストを記述する必要があります。画像を補足するためのものではなく、画像の上や下のキャプションですでに提供されている情報を繰り返してはいけません。
画像が純粋に装飾的であったり、ユーザー向けでない場合は、alt
プロパティは空の文字列(alt=""
)にする必要があります。
任意の Props
<Image />
コンポーネントは、必須属性以外にも多くの負荷的な属性を受け付けます。このセクションでは、Image コンポーネントのもっとも一般的に使用されるプロパティについて説明します。めったに使われない属性については、高度な属性のセクションで詳細をご覧ください。
loader
画像 URL の解決に使用されるカスタム関数です。
loader
は、以下のパラメータを受け取り、画像の URL 文字列を返す関数です:
カスタムのloader
の例は以下のようなものです:
'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}
/>
)
}
Good to know:
loader
のような関数を受け付ける prop を使用する場合、提供された関数をシリアライズするためにClient Componentsを使用する必要があります。
あるいはnext.config.js
のloaderFile
設定を使用して、アプリケーション内のnext/image
のすべてのインスタンスを、prop を渡さずに設定もできます。
fill
fill={true} // {true} | {false}
画像が親要素を満たすようにするブール値で、幅と高さが不明な場合に便利です。
親要素はposition: "relative"
、position:"fixed"
、またはposition:"absolute"
を指定する必要があります。
デフォルトでは、img 要素には自動的にposition: "absolute"
が割り当てられます。
画像にスタイルが適用されていない場合、画像はコンテナに合わせて引き伸ばされます。コンテナに合わせてアスペクト比を維持するためにレターボックス化する画像には、object-fit: "contain"
を設定するほうがよいでしょう。
あるいは、object-fit: "cover"
にすると、画像はコンテナ全体を満たし、アスペクト比を保つように切り取られます。これを正しく見せるには、overflow:"hidden"
スタイルが親要素に割り当てられていなければなりません。
詳細は以下を参照してください
sizes
メディアクエリに似た文字列で、異なるブレイクポイントにおける画像の幅に関する情報を提供します。sizes
の値は、fill
を使用している画像や、レスポンシブサイズを持つようにスタイルされている画像のパフォーマンスに大きく影響します。
sizes
は、画像描画性能に関連する 2 つの重要な目的を果たします:
- まず、ブラウザは、
next/image
が自動的に生成したsrcset
から、ダウンロードする画像のサイズを決定するためにsizes
の値を使用します。ブラウザが画像を選択するとき、ページ上の画像のサイズをまだ知らないので、ビューポートと同じサイズかそれより大きい画像を選択します。sizes
属性を使用すると、画像が実際にはフルスクリーンよりも小さくなることをブラウザに伝えることができます。fill
属性で画像のsizes
値を指定しない場合、デフォルト値の100vw
(フルスクリーン幅)が使用されます。 - 次に、
sizes
属性は自動生成されsrcset
値の動作を変更します。sizes
値がない場合、固定サイズの画像(1x/2x/など)に適した小さなsrcset
が生成されます。sizes
が定義されている場合 、レスポンシブ画像に適した大きなsrcset
が生成されます(640w/750w など)。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 乗に比例するため、サイズがなければユーザーは必要なサイズの 9 倍の画像をダウンロードすることになります。
srcset
、sizes
の詳細は以下を参照してください:
quality
quality={75} // {number 1-100}
最適化された画像の画質を表し、1
から100
の整数で、100
を指定すると最高画質、したがってファイルサイズは最大になります。デフォルトは75
です。
priority
priority={false} // {false} | {true}
true
の場合、画像は優先度が高いとみなされ、プリロードされます。priority
を使用している画像では、遅延読み込みは自動的に無効になります。
priority
属性はLargest Contentful Paint(LCP)要素として検出された画像に使用するべきです。異なるビューポートサイズでは異なる画像が 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
の場合、画像の読み込み中にプレースホルダは無く、空白のスペースだけが表示されます。
以下のリンクから動作を試すことができます:
高度な属性
場合によっては、より高度な使い方が必要になるかもしれません。<Image />
コンポーネントは、オプションで以下の高度な属性を受け付けます。
style
基礎となる画像要素に CSS スタイル を渡します。
const imageStyle = {
borderRadius: '50%',
border: '1px solid #fff',
}
export default function ProfileImage() {
return <Image src="..." style={imageStyle} />
}
必須のwidth
、height
props はスタイリングと相互作用することがあることを覚えておいてください。スタイリングを使って画像の幅を変更する場合、その画像の本来の縦横比を維持するために高さもauto
にスタイリングする必要があります。
onLoadingComplete
'use client'
<Image onLoadingComplete={(img) => console.log(img.naturalWidth)} />
画像が完全に読み込まれ、プレースホルダが削除されると呼び出されるコールバック関数です。
コールバック関数は基礎となる<img>
要素への参照を引数にとり呼び出されます。
Good to know:
onLoadingComplete
のような関数を受け付ける props を使用する場合、引数に渡される関数をシリアライズするためにClient Componentsを使用する必要があります。
onLoad
<Image onLoad={(e) => console.log(e.target.naturalWidth)} />
画像がロードされたときに呼び出されるコールバック関数です。
load
イベントは、画像のプレースホルダが削除され、画像が完全にデコードされる前に発生する場合があります。画像が完全に読み込まれるまで待ちたい場合は、代わりにonLoadingComplete
を使用します。
Good to know:
onLoad
のような関数を受け付ける props を使用する場合、引数に渡される関数をシリアライズするためにClient Componentsを使用する必要があります。
onError
<Image onError={(e) => console.error(e.target.id)} />
画像の読み込みが失敗した場合に呼び出されるコールバック関数です。
Good to know:
onError
のような関数を受け付ける props を使用する場合、引数に渡される関数をシリアライズするためにClient Componentsを使用する必要があります。
loading
推奨:このプロパティは高度なユースケースを想定しています。
eager
でロードする画像を切り替えると、通常はパフォーマンスが低下します。代わりにpriority
属性を使用することをお勧めします。
loading = 'lazy' // {lazy} | {eager}
画像の読み込み動作を指定します。デフォルトはlazy
です。
lazy
の場合、ビューポートから計算された距離に達するまで画像の読み込みを延期します。
eager
の場合、画像を直ちに読み込みます。
loading
属性の詳細については、こちらを参照してださい。
blurDataURL
src
画像が正常に読み込まれる前にプレースホルダ画像として使用されるData URLです。placeholder="blur"
と組み合わせた場合のみ有効です。
base64 エンコードされた画像でなければなりません。拡大されてぼかされるので、非常に小さい画像(10px 以下)を推奨します。プレースホルダとして大きな画像を含めると、アプリケーションのパフォーマンスが低下する可能性があります。
以下のリンクから動作を試すことができます:
また画像にマッチした単色の 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
を以下の設定で更新することで、すべての画像にこの prop を割り当てることができます:
module.exports = {
images: {
unoptimized: true,
},
}
その他の Props
<Image />
コンポーネントの他の属性は、以下を除いて、その下にあるimg
要素へ渡されます:
srcSet
-deviceSizes
を使用してくださいdecoding
- 常に"async"
になります
設定オプション
props に加えて、next.config.js
で Image コンポーネントを設定できます。以下のオプションがあります:
remotePatterns
悪意のあるユーザーからアプリケーションを保護するため、外部画像を使用するには設定が必要です。これにより、Next.js の Image Optimization API から提供される外部画像は、自分のアカウントの画像だけになります。これらの外部画像はnext.config.js
ファイルのremotePatterns
プロパティで設定できます:
module.exports = {
images: {
remotePatterns: [
{
protocol: 'https',
hostname: 'example.com',
port: '',
pathname: '/account123/**',
},
],
},
}
Good to know: 上記の例では、
next/image
のsrc
属性はhttps://example.com/account123/
から始まることを強制します。その他のプロトコル、ホスト名、ポート、または一致しないパスは、400 Bad Request で応答します。
以下は、next.config.js
ファイルのremotePatterns
プロパティの別の例です:
module.exports = {
images: {
remotePatterns: [
{
protocol: 'https',
hostname: '**.example.com',
},
],
},
}
Good to know: 上記の例では、
next/image
のsrc
属性はhttps://img1.example.com
やhttps://me.avatar.example.com
、または任意の数のサブドメインから始まることを強制します。その他のプロトコルやホスト名に一致しないパスは、400 Bad Request で応答します。
ワイルドカード・パターンはパス名とホスト名の両方に使用でき、以下の構文を持ちます:
*
は単一のパス Segment またはサブドメインにマッチします**
は末尾の任意の数のパス Segment または先頭のサブドメインにマッチします
パターンの途中では、**
構文は機能しません。
domains
注意: 悪意のあるユーザからアプリケーションを保護するために、
domain
ではなく厳密なremotePatterns
を設定することをお勧めします。ドメインから提供されるすべてのコンテンツを所有する場合にのみ、domain
を使用してください。
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
propを使ってnext/image
の各インスタンスを設定できます。
例:
Good to know:関数を受け付けるイメージローダーのファイルをカスタマイズするには、Client Componentを使用して提供された関数をシリアライズする必要があります。
高度な設定
以下の設定は高度なユースケース向けであり、通常は必要ありません。以 下の属性を設定すると、今後のアップデートで Next.js のデフォルトが変更されても、それを上書きすることになります。
deviceSizes
ユーザーのデバイス幅がわかっている場合、next.config.js
のdeviceSizes
プロパティを使用してデバイス幅のブレークポイントのリストを指定できます。これらの幅は、next/image
コンポーネントがsizes
prop を使用するときに使用され、ユーザーのデバイスに対して正しい画像が提供されるようにします。
設定が提供されない場合、以下のデフォルトが使用されます。
module.exports = {
images: {
deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
},
}
imageSizes
next.config.js
ファイルのimages.imageSizes
プロパティを使用して、画像の幅のリストを指定できます。これらの幅は、deviceSizesの配列と連結され、画像のsrcsetを生成するために使用されるサイズの完全な配列を形成します。
2 つの別々のリストがある理由は、imageSizes は、画像が画面の全幅よりも小さいことを示すsizes
prop を提供する画像にのみ使用されるからです。したがって、imageSizes のサイズはすべて deviceSizes の最小サイズより小さくなければなりません。
設定が提供されていない場合、以下のデフォルトが使用されます。
module.exports = {
images: {
imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
},
}
formats
デフォルトのImage Optimization APIは、リクエストのAccept
ヘッダによってブラウザがサポート している画像フォーマットを自動的に検出します。
Accept
ヘッダが複数の設定済みのフォーマットにマッチした場合は、配列の最初にマッチしたものが使用されます。したがって、配列の順番は重要です。マッチするものがない(あるいは元画像がアニメーションである)場合は、Image Optimization API は元画像のフォーマットにフォールバックします。
設定を省略した場合は、以下のデフォルトが使われます。
module.exports = {
images: {
formats: ['image/webp'],
},
}
AVIF のサポートは以下の設定で有効にできます。
module.exports = {
images: {
formats: ['image/avif', 'image/webp'],
},
}
Good to know:
- AVIF は一般的にエンコードに 20%長い時間がかかりますが、WebP に比べて 20%小さく圧縮されます。つまり、最初に画像がリクエストされたときは一般的に遅くなり、その後キャッシュされたリクエストは速くなります
- Next.js の前にプロキシ/CDN を使用してセルフホストする場合は、
Accept
ヘッダーを転送するようにプロキシを設定する必要があります
キャッシュの制御
以下に、デフォルトのローダーのキャッシュ・アルゴリズムについて説明します。その他のローダーについては、クラウドプロバイダーのドキュメントを参照してください。
画像はリクエスト時に動的に最適化され、<distDir>/cache/images
ディレクトリに保存されます。最適化された画像ファイルは、有効期限が切れるまで、それ以降のリクエストで提供されます。キャッシュされているが有効期限切れのファイルにマッチするリクエストがなされると、有効期限切れの画像は直ちに古くなったものが提供されます。その後、画像はバックグラウンドで再度最適化され(再検証とも呼ばれます)、 新しい有効期限とともにキャッシュに保存されます。
画像のキャッシュの状態は 、x-nextjs-cache
レスポンス・ヘッダの値を読み取ることで決定されます。取り得る値は以下のとおりです:
MISS
- パスがキャッシュにない(最初の訪問時に最大一度だけ発生する)STALE
- パスはキャッシュにあるが、再検証時間を超えているため、バックグラウンドで更新されるHIT
- パスがキャッシュ内にあり、再検証時間を超えていない
有効期限(というより Max Age)は、minimumCacheTTL
設定またはアップストリームイメージのCache-Control
ヘッダーのいずれか大きい方で定義されます。具体的には、Cache-Control
ヘッダーのmax-age
値が使用されます。s-maxage
とmax-age
の両方が見つかった場合、s-maxage
が優先されます。max-age
は、CDN やブラウザを含む下流のクライアントにも渡されます。
- minimumCacheTTLを設定すると、アップストリーム画像に
Cache-Control
ヘッダが含まれていない場合、またはその値が非常に小さい場合に、キャッシュ期間を長くできます - deviceSizesとimageSizesを設定して、生成可能なイメージの総数を減らすことができます
- formatsを設定して、複数のフォーマットを無効にし、単一の画像フォーマットを優先させることができます
minimumCacheTTL
最適化された画 像をキャッシュする TTL(Time to Live)を秒単位で設定できます。多くの場合、ファイルの内容を自動的にハッシュ化し、Cache-Control
ヘッダをimmutable
にして画像を永久にキャッシュする静的な画像インポートを使うのがよいでしょう。
module.exports = {
images: {
minimumCacheTTL: 60,
},
}
最適化された画像の有効期限(というより Max Age)は、minimumCacheTTL
またはアップストリーム画像のCache-Control
ヘッダーのいずれか大きいほうで定義されます。
画像ごとにキャッシュ動作を変更する場合は、アップストリームの画像(例えば/_next/image
自体ではなく/some-asset.jpg
)のCache-Control
ヘッダを設定できます。
現時点ではキャッシュを無効にする仕組みはないので、minimumCacheTTL
を低く保つのが最善です。あるいは、手動でsrc
prop を変更するか、<distDir>/cache/images
を削除する必要があるかもしれません。
disableStaticImages
デフォルトの動作では、import icon from './icon.png'
のように静的ファイルをインポートし、それをsrc
プロパティに渡すことが可能です。
場合によっては、インポートが異なる動作をすることを期待する他のプラグインと競合するため、この機能を無効にしたいかもしれません。
静的画像のインポートを無効にするには、next.config.js
で設定します:
module.exports = {
images: {
disableStaticImages: true,
},
}
dangerouslyAllowSVG
デフォルトのローダーは、いくつかの理由から SVG 画像を最適化しません。第一に、SVG はベクターフォーマットであり、ロスレスでリサイズできることを意味します。第二に、SVG には HTML/CSS と同じ機能がたくさんあり、適切なコンテンツ・セキュリティ・ポリシーがないと脆弱性につながる可能性があります。
デフォルトの Image Optimization 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 prop を使ってください。
レスポンシブ画像
デフォルトで生成されるsrcset
は、異なるデバイスのピクセル比をサポートするために、1x
と2x
の画像を含んでいます。しかし、ビューポートに合わせて伸縮するレスポンシブな画像をレンダリングしたい場合もあるでしょう。その場合は、style
(またはclassName
)と同様にsizes
を設定する必要があります。
以下のいずれかの方法で、レスポンシブ画像をレンダリングできます。