<Image>

Gut zu wissen: Wenn Sie eine Version von Next.js vor 13 verwenden, sollten Sie die Dokumentation für next/legacy/image verwenden, da die Komponente umbenannt wurde.

Diese API-Referenz hilft Ihnen zu verstehen, wie Sie die verfügbaren Props und Konfigurationsoptionen für die Image-Komponente verwenden. Für Funktionen und Nutzung siehe die Seite Image-Komponente.

import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="/profile.png"
      width={500}
      height={500}
      alt="Bild des Autors"
    />
  )
}

Props

Hier ist eine Übersicht der verfügbaren Props für die Image-Komponente:

Erforderliche Props

Die Image-Komponente erfordert die folgenden Eigenschaften: src, width, height und alt.

import Image from 'next/image'

export default function Page() {
  return (
    <div>
      <Image
        src="/profile.png"
        width={500}
        height={500}
        alt="Bild des Autors"
      />
    </div>
  )
}

src

Muss eines der folgenden sein:

• Eine statisch importierte Bilddatei
• Ein Pfad-String. Dies kann entweder eine absolute externe URL oder ein interner Pfad sein, abhängig von der loader-Prop.

Bei Verwendung einer externen URL müssen Sie diese zu remotePatterns in next.config.js hinzufügen.

width

Die width-Prop repräsentiert die gerenderte Breite in Pixeln und beeinflusst somit, wie groß das Bild erscheint.

Erforderlich, außer für statisch importierte Bilder oder Bilder mit der fill-Prop.

height

Die height-Prop repräsentiert die gerenderte Höhe in Pixeln und beeinflusst somit, wie groß das Bild erscheint.

Erforderlich, außer für statisch importierte Bilder oder Bilder mit der fill-Prop.

alt

Die alt-Prop wird verwendet, um das Bild für Screenreader und Suchmaschinen zu beschreiben. Sie ist auch der Fallback-Text, wenn Bilder deaktiviert wurden oder ein Fehler beim Laden auftritt.

Sie sollte Text enthalten, der das Bild ohne Änderung der Seitenbedeutung ersetzen kann. Sie ist nicht dazu gedacht, das Bild zu ergänzen oder Informationen zu wiederholen, die bereits in den Bildunterschriften enthalten sind.

Wenn das Bild rein dekorativ oder nicht für den Benutzer bestimmt ist, sollte die alt-Prop ein leerer String sein (alt="").

Mehr erfahren

Optionale Props

Die <Image />-Komponente akzeptiert eine Reihe zusätzlicher Eigenschaften neben den erforderlichen. Dieser Abschnitt beschreibt die am häufigsten verwendeten Props der Image-Komponente. Details zu seltener verwendeten Props finden Sie im Abschnitt Erweiterte Props.

loader

Eine benutzerdefinierte Funktion zur Auflösung von Bild-URLs.

Ein loader ist eine Funktion, die einen URL-String für das Bild zurückgibt, basierend auf folgenden Parametern:

• src
• width
• quality

Hier ist ein Beispiel für die Verwendung eines benutzerdefinierten Loaders:

'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="Bild des Autors"
      width={500}
      height={500}
    />
  )
}

Alternativ können Sie die loaderFile-Konfiguration in next.config.js verwenden, um jede Instanz von next/image in Ihrer Anwendung zu konfigurieren, ohne eine Prop zu übergeben.

fill

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

Ein Boolean, der bewirkt, dass das Bild das übergeordnete Element ausfüllt, was nützlich ist, wenn die width und height unbekannt sind.

Das übergeordnete Element muss den Style position: "relative", position: "fixed" oder position: "absolute" zuweisen.

Standardmäßig erhält das img-Element automatisch den Style position: "absolute".

Wenn keine Styles auf das Bild angewendet werden, wird das Bild gestreckt, um den Container auszufüllen. Möglicherweise bevorzugen Sie object-fit: "contain" für ein Bild, das an den Container angepasst wird und das Seitenverhältnis beibehält.

Alternativ bewirkt object-fit: "cover", dass das Bild den gesamten Container ausfüllt und zugeschnitten wird, um das Seitenverhältnis beizubehalten. Damit dies korrekt aussieht, sollte der Style overflow: "hidden" dem übergeordneten Element zugewiesen werden.

Weitere Informationen siehe auch:

• position
• object-fit
• object-position

sizes

Ein String, ähnlich einer Media Query, der Informationen darüber liefert, wie breit das Bild bei verschiedenen Breakpoints sein wird. Der Wert von sizes beeinflusst die Performance für Bilder mit fill oder die stylisiert sind, um eine responsive Größe zu haben, erheblich.

Die sizes-Prop dient zwei wichtigen Zwecken in Bezug auf die Bildperformance:

• Erstens wird der Wert von sizes vom Browser verwendet, um zu bestimmen, welche Größe des Bildes aus dem automatisch generierten srcset von next/image heruntergeladen werden soll. Wenn der Browser auswählt, kennt er die Größe des Bildes auf der Seite noch nicht, daher wählt er ein Bild aus, das genauso groß oder größer als der Viewport ist. Die sizes-Prop ermöglicht es Ihnen, dem Browser mitzuteilen, dass das Bild tatsächlich kleiner als die volle Bildschirmbreite sein wird. Wenn Sie keinen sizes-Wert für ein Bild mit der fill-Prop angeben, wird ein Standardwert von 100vw (volle Bildschirmbreite) verwendet.
• Zweitens ändert die sizes-Prop das Verhalten des automatisch generierten srcset-Werts. Wenn kein sizes-Wert vorhanden ist, wird ein kleiner srcset generiert, der für ein Bild mit fester Größe geeignet ist (1x/2x/etc.). Wenn sizes definiert ist, wird ein großer srcset generiert, der für ein responsives Bild geeignet ist (640w/750w/etc.). Wenn die sizes-Prop Größen wie 50vw enthält, die einen Prozentsatz der Viewport-Breite darstellen, wird der srcset so gekürzt, dass keine Werte enthalten sind, die zu klein sind, um jemals benötigt zu werden.

Wenn Sie beispielsweise wissen, dass Ihr Styling bewirkt, dass ein Bild auf Mobilgeräten die volle Breite einnimmt, in einem 2-Spalten-Layout auf Tablets und in einem 3-Spalten-Layout auf Desktop-Displays, sollten Sie eine sizes-Prop wie folgt einfügen:

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

Dieses sizes-Beispiel könnte einen dramatischen Effekt auf Performance-Metriken haben. Ohne die 33vw-Größe wäre das vom Server ausgewählte Bild dreimal so breit wie nötig. Da die Dateigröße proportional zum Quadrat der Breite ist, würde der Benutzer ohne sizes ein Bild herunterladen, das neunmal größer ist als notwendig.

Mehr über srcset und sizes:

• web.dev
• mdn

quality

quality={75} // {number 1-100}

Die Qualität des optimierten Bildes, eine ganze Zahl zwischen 1 und 100, wobei 100 die beste Qualität und damit die größte Dateigröße ist. Standardwert ist 75.

priority

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

Wenn true, wird das Bild als hochpriorisiert betrachtet und vorabgeladen. Lazy Loading wird für Bilder mit priority automatisch deaktiviert.

Sie sollten die priority-Prop für jedes Bild verwenden, das als Largest Contentful Paint (LCP)-Element erkannt wird. Es kann angemessen sein, mehrere Priority-Bilder zu haben, da verschiedene Bilder für verschiedene Viewport-Größen das LCP-Element sein können.

Sollte nur verwendet werden, wenn das Bild oberhalb des Folds sichtbar ist. Standardwert ist false.

placeholder

placeholder = 'empty' // "empty" | "blur" | "data:image/..."

Ein Platzhalter, der während des Ladens des Bildes verwendet wird. Mögliche Werte sind blur, empty oder data:image/.... Standardwert ist empty.

Wenn blur, wird die blurDataURL-Prop als Platzhalter verwendet. Wenn src ein Objekt aus einem statischen Import ist und das importierte Bild .jpg, .png, .webp oder .avif ist, wird blurDataURL automatisch ausgefüllt, es sei denn, das Bild wird als animiert erkannt.

Für dynamische Bilder müssen Sie die blurDataURL-Prop angeben. Lösungen wie Plaiceholder können bei der base64-Generierung helfen.

Wenn data:image/..., wird die Data URL als Platzhalter während des Ladens des Bildes verwendet.

Wenn empty, gibt es während des Ladens des Bildes keinen Platzhalter, nur leeren Raum.

Ausprobieren:

• Demo des blur-Platzhalters
• Demo des Schimmer-Effekts mit data URL placeholder-Prop
• Demo des Farbeffekts mit blurDataURL-Prop

Erweiterte Props

In einigen Fällen benötigen Sie möglicherweise eine erweiterte Nutzung. Die <Image />-Komponente akzeptiert optional die folgenden erweiterten Eigenschaften.

style

Ermöglicht das Übergeben von CSS-Styles an das zugrunde liegende Bild-Element.

const imageStyle = {
  borderRadius: '50%',
  border: '1px solid #fff',
}

export default function ProfileImage() {
  return <Image src="..." style={imageStyle} />
}

Denken Sie daran, dass die erforderlichen width- und height-Props mit Ihrem Styling interagieren können. Wenn Sie Styling verwenden, um die Breite eines Bildes zu ändern, sollten Sie auch seine Höhe auf auto setzen, um das intrinsische Seitenverhältnis beizubehalten, da das Bild sonst verzerrt wird.

onLoadingComplete

'use client'

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

Eine Callback-Funktion, die aufgerufen wird, sobald das Bild vollständig geladen ist und der Platzhalter entfernt wurde.

Die Callback-Funktion wird mit einem Argument aufgerufen, einer Referenz auf das zugrunde liegende <img>-Element.

onLoad

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

Eine Callback-Funktion, die aufgerufen wird, wenn das Bild geladen ist.

Das load-Ereignis kann auftreten, bevor der Bildplatzhalter entfernt und das Bild vollständig dekodiert ist. Wenn Sie warten möchten, bis das Bild vollständig geladen ist, verwenden Sie stattdessen onLoadingComplete.

onError

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

Eine Callback-Funktion, die aufgerufen wird, wenn das Bild nicht geladen werden kann.

loading

Empfehlung: Diese Prop ist nur für erweiterte Anwendungsfälle gedacht. Das Umschalten eines Bildes auf eager-Laden wird normalerweise die Performance beeinträchtigen. Wir empfehlen die Verwendung der priority-Prop, die das Bild eifrig vorlädt.

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

Das Ladeverhalten des Bildes. Standardwert ist lazy.

Wenn lazy, wird das Laden des Bildes verzögert, bis es einen berechneten Abstand zum Viewport erreicht.

Wenn eager, wird das Bild sofort geladen.

Mehr über das loading-Attribut.

blurDataURL

Eine Data URL, die als Platzhalterbild verwendet wird, bevor das src-Bild erfolgreich geladen wurde. Wirkt nur in Kombination mit placeholder="blur".

Muss ein base64-kodiertes Bild sein. Es wird vergrößert und unscharf dargestellt, daher wird ein sehr kleines Bild (10px oder weniger) empfohlen. Größere Bilder als Platzhalter können die Leistung Ihrer Anwendung beeinträchtigen.

Probieren Sie es aus:

• Demo der standardmäßigen blurDataURL-Eigenschaft
• Demo des Farbeffekts mit der blurDataURL-Eigenschaft

Sie können auch eine Data URL mit einfarbigem Hintergrund generieren, um sie an das Bild anzupassen.

unoptimized

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

Wenn true, wird das Quellbild unverändert ausgeliefert, ohne Qualität, Größe oder Format zu ändern. Standardwert ist false.

import Image from 'next/image'

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

Seit Next.js 12.3.0 kann diese Eigenschaft für alle Bilder festgelegt werden, indem next.config.js mit folgender Konfiguration aktualisiert wird:

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

Weitere Eigenschaften

Andere Eigenschaften der <Image />-Komponente werden an das zugrunde liegende img-Element weitergegeben, mit Ausnahme der folgenden:

• srcSet. Verwenden Sie stattdessen Gerätegrößen (Device Sizes).
• decoding. Ist immer "async".

Konfigurationsoptionen

Zusätzlich zu den Eigenschaften können Sie die Image-Komponente in next.config.js konfigurieren. Folgende Optionen sind verfügbar:

remotePatterns

Um Ihre Anwendung vor böswilligen Nutzern zu schützen, ist eine Konfiguration erforderlich, um externe Bilder zu verwenden. Dadurch wird sichergestellt, dass nur externe Bilder von Ihrem Konto über die Next.js Image Optimization API bereitgestellt werden können. Diese externen Bilder können mit der Eigenschaft remotePatterns in Ihrer next.config.js-Datei konfiguriert werden, wie unten gezeigt:

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

Gut zu wissen: Das obige Beispiel stellt sicher, dass die src-Eigenschaft von next/image mit https://example.com/account123/ beginnen muss. Jedes andere Protokoll, Hostname, Port oder nicht übereinstimmender Pfad führt zu einer 400 Bad Request-Antwort.

Hier ist ein weiteres Beispiel für die remotePatterns-Eigenschaft in der next.config.js-Datei:

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

Gut zu wissen: Das obige Beispiel stellt sicher, dass die src-Eigenschaft von next/image mit https://img1.example.com oder https://me.avatar.example.com oder einer beliebigen Anzahl von Subdomains beginnen muss. Jedes andere Protokoll oder nicht übereinstimmender Hostname führt zu einer 400 Bad Request-Antwort.

Wildcard-Muster können sowohl für pathname als auch für hostname verwendet werden und haben folgende Syntax:

• * passt auf ein einzelnes Pfadsegment oder eine Subdomain
• ** passt auf eine beliebige Anzahl von Pfadsegmenten am Ende oder Subdomains am Anfang

Die **-Syntax funktioniert nicht in der Mitte des Musters.

domains

Warnung: Wir empfehlen, strikte remotePatterns anstelle von domains zu konfigurieren, um Ihre Anwendung vor böswilligen Nutzern zu schützen. Verwenden Sie domains nur, wenn Ihnen alle Inhalte der Domain gehören.

Ähnlich wie remotePatterns kann die domains-Konfiguration verwendet werden, um eine Liste zulässiger Hostnamen für externe Bilder bereitzustellen.

Allerdings unterstützt die domains-Konfiguration keine Wildcard-Muster und kann Protokoll, Port oder Pfad nicht einschränken.

Hier ist ein Beispiel für die domains-Eigenschaft in der next.config.js-Datei:

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

loaderFile

Wenn Sie einen Cloud-Anbieter zur Bildoptimierung verwenden möchten, anstatt die integrierte Next.js Image Optimization API zu nutzen, können Sie loaderFile in Ihrer next.config.js wie folgt konfigurieren:

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

Dies muss auf eine Datei relativ zum Stammverzeichnis Ihrer Next.js-Anwendung verweisen. Die Datei muss eine Standardfunktion exportieren, die einen String zurückgibt, zum Beispiel:

'use client'

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

Alternativ können Sie die loader-Eigenschaft verwenden, um jede Instanz von next/image zu konfigurieren.

Beispiele:

• Benutzerdefinierte Image Loader-Konfiguration

Fortgeschrittene Konfiguration

Die folgende Konfiguration ist für fortgeschrittene Anwendungsfälle gedacht und ist normalerweise nicht notwendig. Wenn Sie die untenstehenden Eigenschaften konfigurieren, überschreiben Sie alle Änderungen an den Next.js-Standardeinstellungen in zukünftigen Updates.

deviceSizes

Wenn Sie die erwarteten Gerätebreiten Ihrer Nutzer kennen, können Sie eine Liste von Breakpoints für Gerätebreiten mit der deviceSizes-Eigenschaft in next.config.js angeben. Diese Breiten werden verwendet, wenn die next/image-Komponente die sizes-Eigenschaft nutzt, um sicherzustellen, dass das richtige Bild für das Gerät des Nutzers bereitgestellt wird.

Wenn keine Konfiguration angegeben wird, wird die folgende Standardeinstellung verwendet:

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

imageSizes

Sie können eine Liste von Bildbreiten mit der images.imageSizes-Eigenschaft in Ihrer next.config.js-Datei angeben. Diese Breiten werden mit dem Array der Gerätegrößen (Device Sizes) kombiniert, um das vollständige Array der Größen zu bilden, das zur Generierung der Bild-srcsets verwendet wird.

Der Grund für die beiden separaten Listen ist, dass imageSizes nur für Bilder verwendet wird, die eine sizes-Eigenschaft bereitstellen, was darauf hinweist, dass das Bild kleiner als die volle Bildschirmbreite ist. Daher sollten alle Größen in imageSizes kleiner sein als die kleinste Größe in deviceSizes.

Wenn keine Konfiguration angegeben wird, wird die folgende Standardeinstellung verwendet:

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

formats

Die standardmäßige Image Optimization API erkennt automatisch die vom Browser unterstützten Bildformate über den Accept-Header der Anfrage.

Wenn der Accept-Header mit mehr als einem der konfigurierten Formate übereinstimmt, wird das erste übereinstimmende Format im Array verwendet. Daher ist die Reihenfolge des Arrays wichtig. Wenn keine Übereinstimmung gefunden wird (oder das Quellbild animiert ist), greift die Image Optimization API auf das ursprüngliche Format des Bildes zurück.

Wenn keine Konfiguration angegeben wird, wird die folgende Standardeinstellung verwendet:

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

Sie können die AVIF-Unterstützung mit folgender Konfiguration aktivieren:

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

Gut zu wissen:

• AVIF benötigt im Allgemeinen 20% mehr Zeit für die Kodierung, komprimiert jedoch 20% besser als WebP. Das bedeutet, dass die erste Anforderung eines Bildes typischerweise langsamer ist und nachfolgende Anforderungen, die zwischengespeichert werden, schneller sind.
• Wenn Sie Next.js selbst hosten und einen Proxy/CDN davor verwenden, müssen Sie den Proxy so konfigurieren, dass er den Accept-Header weitergibt.

Caching-Verhalten

Das Folgende beschreibt den Caching-Algorithmus für den standardmäßigen Loader. Für alle anderen Loader lesen Sie bitte die Dokumentation Ihres Cloud-Anbieters.

Bilder werden dynamisch bei Anfrage optimiert und im Verzeichnis <distDir>/cache/images gespeichert. Das optimierte Bild wird für nachfolgende Anfragen bereitgestellt, bis die Gültigkeitsdauer abgelaufen ist. Wenn eine Anfrage gemacht wird, die auf eine zwischengespeicherte, aber abgelaufene Datei passt, wird das abgelaufene Bild sofort als "stale" bereitgestellt. Dann wird das Bild im Hintergrund neu optimiert (auch Revalidierung genannt) und mit dem neuen Ablaufdatum im Cache gespeichert.

Der Cache-Status eines Bildes kann durch Lesen des Werts des x-nextjs-cache-Antwort-Headers bestimmt werden. Die möglichen Werte sind:

• MISS - Der Pfad ist nicht im Cache (tritt höchstens einmal beim ersten Besuch auf)
• STALE - Der Pfad ist im Cache, hat aber die Revalidierungszeit überschritten und wird im Hintergrund aktualisiert
• HIT - Der Pfad ist im Cache und hat die Revalidierungszeit nicht überschritten

Die Gültigkeitsdauer (oder genauer Max Age) wird entweder durch die minimumCacheTTL-Konfiguration oder den Cache-Control-Header des Upstream-Bildes definiert, je nachdem, welcher Wert größer ist. Insbesondere wird der max-age-Wert des Cache-Control-Headers verwendet. Wenn sowohl s-maxage als auch max-age vorhanden sind, wird s-maxage bevorzugt. Der max-age-Wert wird auch an alle nachgelagerten Clients, einschließlich CDNs und Browser, weitergegeben.

• Sie können minimumCacheTTL konfigurieren, um die Cache-Dauer zu erhöhen, wenn das Upstream-Bild keinen Cache-Control-Header enthält oder der Wert sehr niedrig ist.
• Sie können deviceSizes und imageSizes konfigurieren, um die Gesamtzahl der möglichen generierten Bilder zu reduzieren.
• Sie können Formate (formats) konfigurieren, um mehrere Formate zugunsten eines einzelnen Bildformats zu deaktivieren.

minimumCacheTTL

Sie können die Time to Live (TTL) in Sekunden für zwischengespeicherte, optimierte Bilder konfigurieren. In vielen Fällen ist es besser, einen statischen Bildimport (Static Image Import) zu verwenden, der den Dateiinhalt automatisch hashed und das Bild mit einem Cache-Control-Header von immutable dauerhaft zwischenspeichert.

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

Die Gültigkeitsdauer (oder genauer Max Age) des optimierten Bildes wird entweder durch minimumCacheTTL oder den Cache-Control-Header des Upstream-Bildes definiert, je nachdem, welcher Wert größer ist.

Wenn Sie das Caching-Verhalten pro Bild ändern müssen, können Sie headers konfigurieren, um den Cache-Control-Header auf dem Upstream-Bild zu setzen (z.B. /some-asset.jpg, nicht /_next/image selbst).

Es gibt derzeit keinen Mechanismus zum Ungültigmachen des Caches, daher ist es am besten, minimumCacheTTL niedrig zu halten. Andernfalls müssen Sie möglicherweise die src-Eigenschaft manuell ändern oder <distDir>/cache/images löschen.

disableStaticImages

Das Standardverhalten ermöglicht es Ihnen, statische Dateien wie import icon from './icon.png' zu importieren und dann an die src-Eigenschaft zu übergeben.

In einigen Fällen möchten Sie diese Funktion möglicherweise deaktivieren, wenn sie mit anderen Plugins kollidiert, die erwarten, dass der Import sich anders verhält.

Sie können statische Bildimporte in Ihrer next.config.js deaktivieren:

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

dangerouslyAllowSVG

Der standardmäßige Loader optimiert SVG-Bilder aus mehreren Gründen nicht. Erstens ist SVG ein Vektorformat, was bedeutet, dass es verlustfrei skaliert werden kann. Zweitens hat SVG viele Funktionen, die HTML/CSS ähneln, was ohne eine ordnungsgemäße Content Security Policy zu Sicherheitslücken führen kann.

Wenn Sie SVG-Bilder mit der standardmäßigen Image Optimization API bereitstellen müssen, können Sie dangerouslyAllowSVG in Ihrer next.config.js setzen:

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

Zusätzlich wird dringend empfohlen, contentDispositionType zu setzen, um den Browser zum Herunterladen des Bildes zu zwingen, sowie contentSecurityPolicy, um die Ausführung von Skripten, die in das Bild eingebettet sind, zu verhindern.

Animierte Bilder

Der standardmäßige Loader umgeht die Bildoptimierung automatisch für animierte Bilder und liefert das Bild unverändert.

Die automatische Erkennung animierter Dateien ist bestmöglich und unterstützt GIF, APNG und WebP. Wenn Sie die Bildoptimierung für ein bestimmtes animiertes Bild explizit umgehen möchten, verwenden Sie die unoptimized-Eigenschaft.

Responsive Bilder

Das standardmäßig generierte srcset enthält 1x- und 2x-Bilder, um verschiedene Gerätepixelverhältnisse zu unterstützen. Möglicherweise möchten Sie jedoch ein responsives Bild rendern, das sich mit dem Viewport dehnt. In diesem Fall müssen Sie sizes sowie style (oder className) setzen.

Sie können ein responsives Bild mit einer der folgenden Methoden rendern.

Responsives Bild mit statischem Import

Wenn das Quellbild nicht dynamisch ist, können Sie es statisch importieren, um ein responsives Bild zu erstellen:

import Image from 'next/image'
import me from '../photos/me.jpg'

export default function Author() {
  return (
    <Image
      src={me}
      alt="Bild des Autors"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
    />
  )
}

Probieren Sie es aus:

• Demo des Bildes, das auf den Viewport reagiert

Responsives Bild mit Seitenverhältnis

Wenn das Quellbild dynamisch ist oder eine Remote-URL hat, müssen Sie auch width und height angeben, um das korrekte Seitenverhältnis des responsiven Bildes festzulegen:

import Image from 'next/image'

export default function Page({ photoUrl }) {
  return (
    <Image
      src={photoUrl}
      alt="Bild des Autors"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
      width={500}
      height={300}
    />
  )
}

Probieren Sie es aus:

• Demo des Bildes, das auf den Viewport reagiert

Responsives Bild mit fill

Wenn Sie das Seitenverhältnis nicht kennen, müssen Sie die fill-Eigenschaft setzen und position: relative auf dem übergeordneten Element festlegen. Optional können Sie den object-fit-Stil je nach gewünschtem Dehnungs- oder Zuschneideverhalten setzen:

import Image from 'next/image'

export default function Page({ photoUrl }) {
  return (
    <div style={{ position: 'relative', width: '500px', height: '300px' }}>
      <Image
        src={photoUrl}
        alt="Bild des Autors"
        sizes="500px"
        fill
        style={{
          objectFit: 'contain',
        }}
      />
    </div>
  )
}

Probieren Sie es aus:

• Demo der fill-Eigenschaft

Theme-Erkennung

Wenn Sie für den Hell- und Dunkelmodus unterschiedliche Bilder anzeigen möchten, können Sie eine neue Komponente erstellen, die zwei <Image>-Komponenten umschließt und basierend auf einer CSS-Media-Query das richtige Bild anzeigt.

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

import styles from './theme-image.module.css'
import Image from 'next/image'

const ThemeImage = (props) => {
  const { srcLight, srcDark, ...rest } = props

  return (
    <>
      <Image {...rest} src={srcLight} className={styles.imgLight} />
      <Image {...rest} src={srcDark} className={styles.imgDark} />
    </>
  )
}

Gut zu wissen: Das Standardverhalten von loading="lazy" stellt sicher, dass nur das korrekte Bild geladen wird. Sie können priority oder loading="eager" nicht verwenden, da dies dazu führen würde, dass beide Bilder geladen werden. Stattdessen können Sie fetchPriority="high" verwenden.

Probieren Sie es aus:

• Demo für Hell/Dunkel-Modus Theme-Erkennung

Bekannte Browser-Bugs

Die next/image-Komponente verwendet das native Lazy Loading des Browsers, das für ältere Browser vor Safari 15.4 auf Eager Loading zurückfallen kann. Bei Verwendung des Blur-Up-Platzhalters fallen ältere Browser vor Safari 12 auf einen leeren Platzhalter zurück. Bei Verwendung von Stilen mit width/height von auto kann es auf älteren Browsern vor Safari 15 zu Layout Shift kommen, die das Seitenverhältnis nicht beibehalten. Weitere Details finden Sie in diesem MDN-Video.

• Safari 15 - 16.3 zeigt beim Laden einen grauen Rand an. Safari 16.4 hat dieses Problem behoben. Mögliche Lösungen:
  • CSS verwenden: @supports (font: -apple-system-body) and (-webkit-appearance: none) { img[loading="lazy"] { clip-path: inset(0.6px) } }
  • priority verwenden, wenn das Bild oberhalb des Folds liegt
• Firefox 67+ zeigt beim Laden einen weißen Hintergrund an. Mögliche Lösungen:
  • AVIF formats aktivieren
  • placeholder verwenden

Versionsverlauf