Menu

<Image>

Beispiele

Diese API-Referenz hilft dir dabei, die verfügbaren Props und Konfigurationsoptionen der Image-Komponente zu verstehen. Für Features und Verwendung, siehe die Seite Image Component.

app/page.js
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:

PropBeispielTypStatus
srcsrc="/profile.png"StringErforderlich
widthwidth={500}Integer (px)Erforderlich
heightheight={500}Integer (px)Erforderlich
altalt="Bild des Autors"StringErforderlich
loaderloader={imageLoader}Function-
fillfill={true}Boolean-
sizessizes="(max-width: 768px) 100vw, 33vw"String-
qualityquality={80}Integer (1-100)-
prioritypriority={true}Boolean-
placeholderplaceholder="blur"String-
stylestyle={{objectFit: "contain"}}Object-
onLoadingCompleteonLoadingComplete={img => done())}FunctionDeprecated
onLoadonLoad={event => done())}Function-
onErroronError(event => fail()}Function-
loadingloading="lazy"String-
blurDataURLblurDataURL="data:image/jpeg..."String-
overrideSrcoverrideSrc="/seo.png"String-

Erforderliche Props

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

app/page.js
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 als String. Dies kann entweder eine absolute externe URL oder ein interner Pfad sein, abhängig von der loader-Prop.

Bei Verwendung des Standard-Loaders beachte zudem folgendes für Quellbilder:

  • Wenn src eine externe URL ist, muss zusätzlich remotePatterns konfiguriert werden
  • Wenn src animiert ist oder kein bekanntes Format hat (JPEG, PNG, WebP, AVIF, GIF, TIFF), wird das Bild unverändert ausgeliefert
  • Wenn src im SVG-Format vorliegt, wird es blockiert, außer unoptimized oder dangerouslyAllowSVG ist aktiviert

width

Die width-Eigenschaft repräsentiert die intrinsische Bildbreite in Pixeln. Diese Eigenschaft wird verwendet, um das korrekte Seitenverhältnis des Bildes abzuleiten und Layout-Verschiebungen während des Ladens zu vermeiden. Sie bestimmt nicht die gerenderte Größe des Bildes, die durch CSS gesteuert wird, ähnlich wie das width-Attribut im HTML <img>-Tag.

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

height

Die height-Eigenschaft repräsentiert die intrinsische Bildhöhe in Pixeln. Diese Eigenschaft wird verwendet, um das korrekte Seitenverhältnis des Bildes abzuleiten und Layout-Verschiebungen während des Ladens zu vermeiden. Sie bestimmt nicht die gerenderte Größe des Bildes, die durch CSS gesteuert wird, ähnlich wie das height-Attribut im HTML <img>-Tag.

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

Hinweis:

  • Zusammen werden die width- und height-Eigenschaften verwendet, um das Seitenverhältnis des Bildes zu bestimmen, das von Browsern genutzt wird, um Platz für das Bild zu reservieren, bevor es geladen wird.
  • Die intrinsische Größe bedeutet nicht immer die gerenderte Größe im Browser, die durch den übergeordneten Container bestimmt wird. Wenn der übergeordnete Container beispielsweise kleiner ist als die intrinsische Größe, wird das Bild verkleinert, um in den Container zu passen.
  • Du kannst die fill-Eigenschaft verwenden, wenn die Breite und Höhe unbekannt sind.

alt

Die alt-Eigenschaft wird verwendet, um das Bild für Screenreader und Suchmaschinen zu beschreiben. Sie dient auch als Fallback-Text, wenn Bilder deaktiviert sind oder ein Fehler beim Laden des Bildes auftritt.

Sie sollte Text enthalten, der das Bild ohne Änderung der Bedeutung der Seite ersetzen könnte. Sie ist nicht dazu gedacht, das Bild zu ergänzen und sollte keine Informationen wiederholen, die bereits in den Bildunterschriften über oder unter dem Bild enthalten sind.

Wenn das Bild rein dekorativ ist oder nicht für den Benutzer bestimmt ist, sollte die alt-Eigenschaft 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 Eigenschaften der Image-Komponente. Details zu selteneren Eigenschaften findest du im Abschnitt Erweiterte Props.

loader

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

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

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

Hinweis: Die Verwendung von Props wie loader, die eine Funktion akzeptieren, erfordert die Verwendung von Client Components, um die bereitgestellte Funktion zu serialisieren.

Alternativ kannst du die loaderFile-Konfiguration in next.config.js verwenden, um jede Instanz von next/image in deiner Anwendung zu konfigurieren, ohne eine Prop übergeben zu müssen.

fill

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

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

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

Standardmäßig wird dem img-Element automatisch der Style position: "absolute" zugewiesen.

Wenn keine Styles auf das Bild angewendet werden, wird das Bild gedehnt, um in den Container zu passen. Du kannst object-fit: "contain" für ein Bild festlegen, das letterboxed wird, um in den Container zu passen und das Seitenverhältnis zu bewahren.

Alternativ wird object-fit: "cover" dazu führen, dass das Bild den gesamten Container ausfüllt und beschnitten wird, um das Seitenverhältnis zu bewahren.

Für weitere Informationen siehe auch:

sizes

Eine Zeichenkette, ähnlich einer Medienabfrage, die Informationen darüber liefert, wie breit das Bild bei verschiedenen Breakpoints sein wird. Der Wert von sizes wird die Leistung für Bilder stark beeinflussen, die fill verwenden oder responsive gestylt sind.

Die sizes-Eigenschaft dient zwei wichtigen Zwecken im Zusammenhang mit der Bildleistung:

  • 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-Eigenschaft ermöglicht es dir, dem Browser mitzuteilen, dass das Bild tatsächlich kleiner als der volle Bildschirm sein wird. Wenn du keinen sizes-Wert in einem Bild mit der fill-Eigenschaft angibst, wird ein Standardwert von 100vw (volle Bildschirmbreite) verwendet.
  • Zweitens ändert die sizes-Eigenschaft das Verhalten des automatisch generierten srcset-Wertes. Wenn kein sizes-Wert vorhanden ist, wird ein kleines srcset generiert, das für ein Bild mit fester Größe (1x/2x/etc.) geeignet ist. Wenn sizes definiert ist, wird ein großes srcset generiert, das für ein responsives Bild (640w/750w/etc.) geeignet ist. Wenn die sizes-Eigenschaft Größen wie 50vw enthält, die einen Prozentsatz der Viewport-Breite darstellen, dann wird das srcset gekürzt, um keine Werte zu enthalten, die zu klein sind, um jemals benötigt zu werden.

Wenn du beispielsweise weißt, dass dein Styling dazu führt, dass ein Bild auf mobilen Geräten die volle Breite einnimmt, in einem 2-Spalten-Layout auf Tablets und einem 3-Spalten-Layout auf Desktop-Displays, solltest du eine sizes-Eigenschaft wie die folgende einschließen:

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"
        alt="Beispielbild"
      />
    </div>
  )
}

Dieses Beispiel von sizes könnte einen dramatischen Effekt auf die Leistungsmetriken haben. Ohne das 33vw sizes wäre das vom Server ausgewählte Bild 3-mal so breit wie nötig. Da die Dateigröße proportional zum Quadrat der Breite ist, würde der Benutzer ohne sizes ein 9-mal größeres Bild herunterladen als nötig.

Mehr über srcset und sizes erfahren:

quality

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

Die Qualität des optimierten Bildes, eine Ganzzahl 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 hohe Priorität eingestuft und vorgeladen. Lazy Loading wird automatisch für Bilder deaktiviert, die priority verwenden. Wenn die loading-Eigenschaft ebenfalls verwendet wird und auf lazy gesetzt ist, kann die priority-Eigenschaft nicht verwendet werden. Die loading-Eigenschaft ist nur für fortgeschrittene Anwendungsfälle gedacht. Entferne loading, wenn priority benötigt wird.

Du solltest die priority-Eigenschaft für jedes Bild verwenden, das als Largest Contentful Paint (LCP)-Element erkannt wurde. Es kann angemessen sein, mehrere Prioritätsbilder zu haben, da verschiedene Bilder für verschiedene Viewport-Größen das LCP-Element sein können.

Sollte nur verwendet werden, wenn das Bild über der Falz sichtbar ist. Standard 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/.... Standard ist empty.

Bei blur wird die blurDataURL-Eigenschaft 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, außer wenn das Bild als animiert erkannt wird.

Für dynamische Bilder musst du die blurDataURL-Eigenschaft bereitstellen. Lösungen wie Plaiceholder können bei der base64-Generierung helfen.

Bei data:image/... wird die Data URL als Platzhalter verwendet, während das Bild lädt.

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

Probiere es aus:

Erweiterte Props

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

style

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

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

Denk daran, dass die erforderlichen width- und height-Props mit deinem Styling interagieren können. Wenn du Styling verwendest, um die Breite eines Bildes zu modifizieren, solltest du auch seine Höhe auf auto setzen, um das intrinsische Seitenverhältnis zu bewahren, sonst wird dein Bild verzerrt.

onLoadingComplete

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

Achtung: Seit Next.js 14 zugunsten von onLoad veraltet.

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.

Hinweis: Die Verwendung von Props wie onLoadingComplete, die eine Funktion akzeptieren, erfordert die Verwendung von Client Components, um die bereitgestellte Funktion zu serialisieren.

onLoad

<Image onLoad={(e) => console.log(e.target.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, dem Event, das ein target hat, das auf das zugrunde liegende <img>-Element verweist.

Hinweis: Die Verwendung von Props wie onLoad, die eine Funktion akzeptieren, erfordert die Verwendung von Client Components, um die bereitgestellte Funktion zu serialisieren.

onError

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

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

Hinweis: Die Verwendung von Props wie onError, die eine Funktion akzeptieren, erfordert die Verwendung von Client Components, um die bereitgestellte Funktion zu serialisieren.

loading

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

Das Ladeverhalten des Bildes. Standard ist lazy.

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

Bei eager wird das Bild sofort geladen.

Mehr über das loading-Attribut erfahren.

blurDataURL

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

Muss ein base64-codiertes Bild sein. Es wird vergrößert und unscharf gemacht, daher wird ein sehr kleines Bild (10px oder weniger) empfohlen. Das Einbinden größerer Bilder als Platzhalter kann die Leistung deiner Anwendung beeinträchtigen.

Probiere es aus:

Du kannst auch eine Data URL für eine einfarbige Fläche generieren, die zum Bild passt.

unoptimized

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

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

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

Seit Next.js 12.3.0 kann diese Prop allen Bildern zugewiesen werden, indem next.config.js mit der folgenden Konfiguration aktualisiert wird:

next.config.js
module.exports = {
  images: {
    unoptimized: true,
  },
}

overrideSrc

Beim Bereitstellen der src-Prop für die <Image>-Komponente werden sowohl die srcset- als auch die src-Attribute automatisch für das resultierende <img> generiert.

input.js
<Image src="/me.jpg" />
output.html
<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"
/>

In manchen Fällen ist es nicht erwünscht, dass das src-Attribut generiert wird, und du möchtest es möglicherweise mit der overrideSrc-Prop überschreiben.

Zum Beispiel möchtest du beim Upgrade einer bestehenden Website von <img> auf <Image> möglicherweise das gleiche src-Attribut für SEO-Zwecke beibehalten, wie zum Beispiel für das Bild-Ranking oder um ein erneutes Crawling zu vermeiden.

input.js
<Image src="/me.jpg" overrideSrc="/override.jpg" />
output.html
<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

Ein Hinweis für den Browser, ob er auf die Dekodierung des Bildes warten soll, bevor andere Inhaltsänderungen präsentiert werden oder nicht. Standard ist async.

Mögliche Werte sind:

  • async - Dekodiere das Bild asynchron und erlaube das Rendern anderer Inhalte, bevor es abgeschlossen ist.
  • sync - Dekodiere das Bild synchron für eine atomare Präsentation mit anderen Inhalten.
  • auto - Keine Präferenz für den Dekodiermodus; der Browser entscheidet, was am besten ist.

Mehr über das decoding-Attribut erfahren.

Andere Props

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

Konfigurationsoptionen

Zusätzlich zu Props kannst du die Image-Komponente in next.config.js konfigurieren. Die folgenden Optionen sind verfügbar:

localPatterns

Du kannst optional localPatterns in deiner next.config.js-Datei konfigurieren, um bestimmte Pfade für die Optimierung zuzulassen und alle anderen Pfade zu blockieren.

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

Hinweis: Das obige Beispiel stellt sicher, dass die src-Eigenschaft von next/image mit /assets/images/ beginnen muss und keine Query-String haben darf. Der Versuch, einen anderen Pfad zu optimieren, wird mit 400 Bad Request beantwortet.

remotePatterns

Um deine Anwendung vor böswilligen Benutzern zu schützen, ist eine Konfiguration erforderlich, um externe Bilder zu verwenden. Dies stellt sicher, dass nur externe Bilder von deinem Konto über die Next.js Image Optimization API bereitgestellt werden können. Diese externen Bilder können mit der remotePatterns-Eigenschaft in deiner next.config.js-Datei konfiguriert werden, wie unten gezeigt:

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

Hinweis: Das obige Beispiel stellt sicher, dass die src-Eigenschaft von next/image mit https://example.com/account123/ beginnen muss und keinen Query-String haben darf. Jedes andere Protokoll, jeder andere Hostname, Port oder nicht übereinstimmender Pfad wird mit 400 Bad Request beantwortet.

Hier ist ein Beispiel für die remotePatterns-Eigenschaft in der next.config.js-Datei mit einem Platzhalter-Muster im hostname:

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

Hinweis: 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. Es darf keinen Port oder Query-String haben. Jedes andere Protokoll oder nicht übereinstimmender Hostname wird mit 400 Bad Request beantwortet.

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

  • * entspricht einem einzelnen Pfadsegment oder einer Subdomain
  • ** entspricht einer beliebigen Anzahl von Pfadsegmenten am Ende oder Subdomains am Anfang

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

Hinweis: Wenn protocol, port, pathname oder search weggelassen werden, wird der Platzhalter ** impliziert. Dies wird nicht empfohlen, da es böswilligen Akteuren ermöglichen könnte, URLs zu optimieren, die du nicht beabsichtigt hast.

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

next.config.js
module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'assets.example.com',
        search: '?v=1727111025337',
      },
    ],
  },
}

Hinweis: Das obige Beispiel stellt sicher, dass die src-Eigenschaft von next/image mit https://assets.example.com beginnen und den exakten Query-String ?v=1727111025337 haben muss. Jedes andere Protokoll oder Query-String wird mit 400 Bad Request beantwortet.

domains

Achtung: Seit Next.js 14 zugunsten von strikten remotePatterns veraltet, um deine Anwendung vor böswilligen Benutzern zu schützen. Verwende domains nur, wenn du der Eigentümer aller Inhalte bist, die von der Domain bereitgestellt werden.

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

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

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

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

loaderFile

Wenn du einen Cloud-Provider zur Optimierung von Bildern anstelle der eingebauten Next.js Image Optimization API verwenden möchtest, kannst du den loaderFile in deiner next.config.js wie folgt konfigurieren:

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

Dies muss auf eine Datei relativ zum Root deiner Next.js-Anwendung zeigen. Die Datei muss eine Standard-Funktion exportieren, die eine Zeichenkette zurückgibt, zum Beispiel:

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

Alternativ kannst du die loader-Prop verwenden, um jede Instanz von next/image zu konfigurieren.

Beispiele:

Hinweis: Die Anpassung der Image-Loader-Datei, die eine Funktion akzeptiert, erfordert die Verwendung von Client Components, um die bereitgestellte Funktion zu serialisieren.

Fortgeschritten

Die folgende Konfiguration ist für fortgeschrittene Anwendungsfälle und normalerweise nicht erforderlich. Wenn du dich entscheidest, die folgenden Eigenschaften zu konfigurieren, überschreibst du alle Änderungen an den Next.js-Standardeinstellungen in zukünftigen Updates.

deviceSizes

Wenn du die erwarteten Gerätebreiten deiner Benutzer kennst, kannst du eine Liste von Gerätebreiten-Breakpoints mit der deviceSizes-Eigenschaft in next.config.js angeben. Diese Breiten werden verwendet, wenn die next/image-Komponente die sizes-Prop verwendet, um sicherzustellen, dass das richtige Bild für das Gerät des Benutzers bereitgestellt wird.

Wenn keine Konfiguration bereitgestellt wird, wird der folgende Standard verwendet:

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

imageSizes

Du kannst eine Liste von Bildbreiten mit der images.imageSizes-Eigenschaft in deiner next.config.js-Datei angeben. Diese Breiten werden mit dem Array von Gerätebreiten zusammengefügt, um das vollständige Array von Größen zu bilden, das verwendet wird, um Bild-srcsets zu generieren.

Der Grund dafür, dass es zwei separate Listen gibt, ist, dass imageSizes nur für Bilder verwendet wird, die eine sizes-Prop 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 bereitgestellt wird, wird der folgende Standard verwendet:

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

formats

Die Standard-Image Optimization API erkennt automatisch die vom Browser unterstützten Bildformate über den Accept-Header der Anfrage, um das beste Ausgabeformat zu bestimmen.

Wenn der Accept-Header mit mehr als einem der konfigurierten Formate übereinstimmt, wird die erste Übereinstimmung im Array verwendet. Daher ist die Reihenfolge im Array wichtig. Wenn es keine Übereinstimmung gibt (oder das Quellbild animiert ist), wird die Image Optimization API auf das ursprüngliche Bildformat zurückfallen.

Wenn keine Konfiguration bereitgestellt wird, wird der folgende Standard verwendet:

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

Du kannst AVIF-Unterstützung aktivieren und trotzdem auf WebP zurückfallen mit der folgenden Konfiguration:

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

Hinweis:

  • AVIF braucht im Allgemeinen 50% länger zum Kodieren, komprimiert aber 20% kleiner als WebP. Das bedeutet, dass die erste Anfrage nach einem Bild typischerweise langsamer sein wird und dann nachfolgende zwischengespeicherte Anfragen schneller sein werden.
  • Wenn du selbst hostest mit einem Proxy/CDN vor Next.js, musst du den Proxy konfigurieren, um den Accept-Header weiterzuleiten.

Caching-Verhalten

Das Folgende beschreibt den Caching-Algorithmus für den Standard-Loader. Für alle anderen Loader siehe bitte die Dokumentation deines Cloud-Providers.

Bilder werden bei Anfrage dynamisch optimiert und im Verzeichnis <distDir>/cache/images gespeichert. Die optimierte Bilddatei wird für nachfolgende Anfragen bereitgestellt, bis die Ablaufzeit erreicht ist. Wenn eine Anfrage eingeht, die einer zwischengespeicherten, aber abgelaufenen Datei entspricht, wird das abgelaufene Bild sofort veraltet bereitgestellt. Dann wird das Bild im Hintergrund erneut optimiert (auch Revalidierung genannt) und mit dem neuen Ablaufdatum im Cache gespeichert.

Der Cache-Status eines Bildes kann durch Auslesen des Wertes des x-nextjs-cache Response-Headers ermittelt werden. Die möglichen Werte sind:

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

Die Ablaufzeit (oder besser gesagt die maximale Alter) wird entweder durch die minimumCacheTTL-Konfiguration oder den Cache-Control-Header des Quellbildes definiert, je nachdem, welcher Wert größer ist. Speziell wird der max-age-Wert des Cache-Control-Headers verwendet. Wenn sowohl s-maxage als auch max-age gefunden werden, wird s-maxage bevorzugt. Der max-age wird auch an alle nachgelagerten Clients einschließlich CDNs und Browser weitergegeben.

  • Du kannst minimumCacheTTL konfigurieren, um die Cache-Dauer zu erhöhen, wenn das Quellbild keinen Cache-Control-Header enthält oder der Wert sehr niedrig ist.
  • Du kannst deviceSizes und imageSizes konfigurieren, um die Gesamtzahl möglicher generierter Bilder zu reduzieren.
  • Du kannst formats konfigurieren, um mehrere Formate zugunsten eines einzelnen Bildformats zu deaktivieren.

minimumCacheTTL

Du kannst die Time to Live (TTL) in Sekunden für zwischengespeicherte optimierte Bilder konfigurieren. In vielen Fällen ist es besser, einen Statischen Bild-Import zu verwenden, der automatisch den Dateiinhalt hasht und das Bild mit einem Cache-Control-Header von immutable auf ewig zwischenspeichert.

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

Die Ablaufzeit (oder besser gesagt das maximale Alter) des optimierten Bildes wird entweder durch die minimumCacheTTL oder den Cache-Control-Header des Quellbildes definiert, je nachdem, welcher Wert größer ist.

Wenn du das Caching-Verhalten pro Bild ändern musst, kannst du headers konfigurieren, um den Cache-Control-Header für das Quellbild zu setzen (z.B. /some-asset.jpg, nicht /_next/image selbst).

Zurzeit gibt es keinen Mechanismus, um den Cache zu invalidieren, daher ist es am besten, minimumCacheTTL niedrig zu halten. Andernfalls musst du möglicherweise manuell die src-Prop ändern oder <distDir>/cache/images löschen.

disableStaticImages

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

In einigen Fällen möchtest du diese Funktion möglicherweise deaktivieren, wenn sie mit anderen Plugins in Konflikt steht, die erwarten, dass der Import sich anders verhält.

Du kannst statische Bildimporte in deiner next.config.js deaktivieren:

next.config.js
module.exports = {
  images: {
    disableStaticImages: true,
  },
}

dangerouslyAllowSVG

Der Standard-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 der gleichen Funktionen wie HTML/CSS, was ohne angemessene Content Security Policy (CSP) Header zu Sicherheitslücken führen kann.

Daher empfehlen wir die Verwendung der unoptimized-Prop, wenn die src-Prop bekanntermaßen SVG ist. Dies geschieht automatisch, wenn src mit ".svg" endet.

Wenn du jedoch SVG-Bilder mit der Standard Image Optimization API bereitstellen musst, kannst du dangerouslyAllowSVG in deiner next.config.js setzen:

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

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

contentDispositionType

Der Standard-Loader setzt den Content-Disposition-Header auf attachment für zusätzlichen Schutz, da die API beliebige externe Bilder bereitstellen kann.

Der Standardwert ist attachment, was den Browser zwingt, das Bild beim direkten Besuch herunterzuladen. Dies ist besonders wichtig, wenn dangerouslyAllowSVG true ist.

Optional kannst du inline konfigurieren, um dem Browser zu erlauben, das Bild beim direkten Besuch zu rendern, ohne es herunterzuladen.

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

Animierte Bilder

Der Standard-Loader umgeht automatisch die Bildoptimierung für animierte Bilder und stellt das Bild unverändert bereit.

Die automatische Erkennung für animierte Dateien erfolgt nach bestem Bemühen und unterstützt GIF, APNG und WebP. Wenn du die Bildoptimierung für ein bestimmtes animiertes Bild explizit umgehen möchtest, verwende die unoptimized-Prop.

Responsive Bilder

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

Du kannst ein responsives Bild mit einer der folgenden Methoden rendern.

Responsives Bild mit statischem Import

Wenn das Quellbild nicht dynamisch ist, kannst du es statisch importieren, um ein responsives Bild zu erstellen:

components/author.js
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',
      }}
    />
  )
}

Probiere es aus:

Responsives Bild mit Seitenverhältnis

Wenn das Quellbild eine dynamische oder remote URL ist, musst du auch width und height angeben, um das korrekte Seitenverhältnis des responsiven Bildes festzulegen:

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

Responsives Bild mit fill

Wenn du das Seitenverhältnis nicht kennst, musst du die fill-Prop setzen und position: relative auf dem übergeordneten Element festlegen. Optional kannst du den object-fit-Style je nach gewünschtem Streck- oder Schneide-Verhalten setzen:

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

Probiere es aus:

Theme Detection CSS

Wenn du ein anderes Bild für den hellen und dunklen Modus anzeigen möchtest, kannst du eine neue Komponente erstellen, die zwei <Image>-Komponenten umschließt und die richtige basierend auf einer CSS-Medienabfrage anzeigt.

components/theme-image.module.css
.imgDark {
  display: none;
}
 
@media (prefers-color-scheme: dark) {
  .imgLight {
    display: none;
  }
  .imgDark {
    display: unset;
  }
}
components/theme-image.tsx
TypeScript
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} />
    </>
  )
}

Hinweis: Das Standardverhalten von loading="lazy" stellt sicher, dass nur das richtige Bild geladen wird. Du kannst nicht priority oder loading="eager" verwenden, da dies dazu führen würde, dass beide Bilder geladen werden. Stattdessen kannst du fetchPriority="high" verwenden.

Probiere es aus:

getImageProps

Für fortgeschrittenere Anwendungsfälle kannst du getImageProps() aufrufen, um die Props zu erhalten, die an das zugrunde liegende <img>-Element übergeben würden, und sie stattdessen an eine andere Komponente, ein Style, ein Canvas etc. übergeben.

Dies vermeidet auch den Aufruf von React useState(), was zu besserer Leistung führen kann, aber es kann nicht mit der placeholder-Prop verwendet werden, da der Platzhalter nie entfernt wird.

Theme Detection Picture

Wenn du ein anderes Bild für den hellen und dunklen Modus anzeigen möchtest, kannst du das <picture>-Element verwenden, um ein anderes Bild basierend auf dem bevorzugten Farbschema des Benutzers anzuzeigen.

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

Art Direction

Wenn du ein anderes Bild für mobile und Desktop-Geräte anzeigen möchtest, manchmal auch Art Direction genannt, kannst du verschiedene src, width, height und quality Props an getImageProps() übergeben.

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

Background CSS

Du kannst sogar den srcSet-String in die image-set() CSS-Funktion umwandeln, um ein Hintergrundbild zu optimieren.

app/page.js
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>Hallo Welt</h1>
    </main>
  )
}

Bekannte Browser-Bugs

Diese next/image-Komponente verwendet natives 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 Styles mit width/height von auto ist es möglich, Layout-Verschiebungen auf älteren Browsern vor Safari 15 zu verursachen, die das Seitenverhältnis nicht bewahren. Weitere Details findest du in diesem MDN-Video.

  • Safari 15 - 16.3 zeigt während des Ladens einen grauen Rand an. Safari 16.4 hat dieses Problem behoben. Mögliche Lösungen:
    • Verwende CSS @supports (font: -apple-system-body) and (-webkit-appearance: none) { img[loading="lazy"] { clip-path: inset(0.6px) } }
    • Verwende priority, wenn das Bild above the fold ist
  • Firefox 67+ zeigt während des Ladens einen weißen Hintergrund an. Mögliche Lösungen:

Versionshistorie

VersionÄnderungen
v15.0.0decoding-Prop hinzugefügt. contentDispositionType-Konfiguration Standard auf attachment geändert.
v14.2.0overrideSrc-Prop hinzugefügt.
v14.1.0getImageProps() ist stabil.
v14.0.0onLoadingComplete-Prop und domains-Config veraltet.
v13.4.14placeholder-Prop-Unterstützung für data:/image...
v13.2.0contentDispositionType-Konfiguration hinzugefügt.
v13.0.6ref-Prop hinzugefügt.
v13.0.0Der next/image-Import wurde zu next/legacy/image umbenannt. Der next/future/image-Import wurde zu next/image umbenannt. Ein Codemod ist verfügbar, um deine Importe sicher und automatisch umzubenennen. <span>-Wrapper entfernt. layout, objectFit, objectPosition, lazyBoundary, lazyRoot-Props entfernt. alt ist erforderlich. onLoadingComplete erhält Referenz zum img-Element. Eingebaute Loader-Konfiguration entfernt.
v12.3.0remotePatterns und unoptimized-Konfiguration ist stabil.
v12.2.0Experimentelles remotePatterns und experimentelle unoptimized-Konfiguration hinzugefügt. layout="raw" entfernt.
v12.1.1style-Prop hinzugefügt. Experimentelle Unterstützung für layout="raw" hinzugefügt.
v12.1.0dangerouslyAllowSVG und contentSecurityPolicy-Konfiguration hinzugefügt.
v12.0.9lazyRoot-Prop hinzugefügt.
v12.0.0formats-Konfiguration hinzugefügt.
AVIF-Unterstützung hinzugefügt.
Wrapper <div> zu <span> geändert.
v11.1.0onLoadingComplete und lazyBoundary-Props hinzugefügt.
v11.0.0src-Prop-Unterstützung für statischen Import.
placeholder-Prop hinzugefügt.
blurDataURL-Prop hinzugefügt.
v10.0.5loader-Prop hinzugefügt.
v10.0.1layout-Prop hinzugefügt.
v10.0.0next/image eingeführt.