Image

Die Next.js Image-Komponente erweitert das HTML <img>-Element für die automatische Bildoptimierung.

import Image from 'next/image'

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

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

Referenz

Props

Die folgenden Props sind verfügbar:

src

Die Quelle des Bildes. Kann einer der folgenden sein:

Ein interner Pfad als String.

<Image src="/profile.png" />

Eine absolute externe URL (muss mit remotePatterns konfiguriert werden).

<Image src="https://example.com/profile.png" />

Ein statischer Import.

import profile from './profile.png'

export default function Page() {
  return <Image src={profile} />
}

alt

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

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

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

Erfahren Sie mehr über Richtlinien zur Barrierefreiheit von Bildern.

width und height

Die Eigenschaften width und height repräsentieren die intrinsische Bildgröße in Pixeln. Diese Eigenschaft wird verwendet, um das korrekte Seitenverhältnis abzuleiten, das von Browsern verwendet wird, um Platz für das Bild zu reservieren und Layoutverschiebungen während des Ladens zu vermeiden. Sie bestimmt nicht die gerenderte Größe des Bildes, die von CSS gesteuert wird.

<Image src="/profile.png" width={500} height={500} />

Sie müssen beide Eigenschaften width und height setzen, es sei denn:

• Das Bild wird statisch importiert
• Das Bild hat die fill-Eigenschaft

Wenn Höhe und Breite unbekannt sind, empfehlen wir die Verwendung der fill-Eigenschaft.

fill

Ein Boolean, der bewirkt, dass das Bild auf die Größe des übergeordneten Elements expandiert.

<Image src="/profile.png" fill={true} />

Positionierung:

• Das übergeordnete Element muss position: "relative", "fixed", "absolute" zuweisen.
• Standardmäßig verwendet das <img>-Element position: "absolute".

Object Fit:

Wenn keine Stile auf das Bild angewendet werden, wird das Bild gestreckt, um den Container zu füllen. Sie können objectFit verwenden, um Zuschneiden und Skalierung zu steuern.

• "contain": Das Bild wird verkleinert, um in den Container zu passen und das Seitenverhältnis beizubehalten.
• "cover": Das Bild füllt den Container und wird zugeschnitten.

Erfahren Sie mehr über position und object-fit.

loader

Eine benutzerdefinierte Funktion, die zur Generierung der Bild-URL verwendet wird. Die Funktion erhält die folgenden Parameter und gibt einen URL-String für das Bild zurück:

• src
• width
• quality

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.

sizes

Definiert die Größen des Bildes bei verschiedenen Breakpoints. Wird vom Browser verwendet, um die passendste Größe aus dem generierten srcset auszuwählen.

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 sollte verwendet werden, wenn:

• Das Bild die fill-Prop verwendet
• CSS verwendet wird, um das Bild responsiv zu machen

Wenn sizes fehlt, geht der Browser davon aus, dass das Bild so breit wie der Viewport ist (100vw). Dies kann dazu führen, dass unnötig große Bilder heruntergeladen werden.

Darüber hinaus beeinflusst sizes, wie srcset generiert wird:

• Ohne sizes: Next.js generiert ein begrenztes srcset (z.B. 1x, 2x), geeignet für Bilder mit fester Größe.
• Mit sizes: Next.js generiert ein vollständiges srcset (z.B. 640w, 750w usw.), optimiert für responsive Layouts.

Erfahren Sie mehr über srcset und sizes auf web.dev und mdn.

quality

Eine ganze Zahl zwischen 1 und 100, die die Qualität des optimierten Bildes festlegt. Höhere Werte erhöhen die Dateigröße und die visuelle Qualität. Niedrigere Werte verringern die Dateigröße, können aber die Schärfe beeinträchtigen.

// Standardqualität ist 75
<Image quality={75} />

Wenn Sie qualities in next.config.js konfiguriert haben, muss der Wert einem der erlaubten Einträge entsprechen.

Gut zu wissen: Wenn das Originalbild bereits von geringer Qualität ist, wird eine hohe Qualitätseinstellung die Dateigröße erhöhen, ohne das Erscheinungsbild zu verbessern.

style

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

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

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

Gut zu wissen: Wenn Sie die style-Prop verwenden, um eine benutzerdefinierte Breite festzulegen, stellen Sie sicher, dass Sie auch height: 'auto' setzen, um das Seitenverhältnis des Bildes beizubehalten.

priority

Ein Boolean, der angibt, ob das Bild vorab geladen werden soll.

// Standardpriorität ist false
<Image priority={false} />

• true: Lädt das Bild vor. Deaktiviert Lazy Loading.
• false: Lädt das Bild verzögert.

Wann es zu verwenden ist:

• Das Bild befindet sich oberhalb des Folds.
• Das Bild ist das Largest Contentful Paint (LCP)-Element.
• Sie möchten die anfängliche Ladeleistung Ihrer Seite verbessern.

Wann es nicht zu verwenden ist:

• Wenn die loading-Prop verwendet wird (löst Warnungen aus).

loading

Steuert, wann das Bild geladen werden soll.

// Standard ist lazy
<Image loading="lazy" />

• lazy: Verzögert das Laden des Bildes, bis es einen berechneten Abstand zum Viewport erreicht.
• eager: Lädt das Bild sofort, unabhängig von seiner Position auf der Seite.

Verwenden Sie eager nur, wenn Sie sicherstellen möchten, dass das Bild sofort geladen wird.

Erfahren Sie mehr über das loading-Attribut.

placeholder

Gibt einen Platzhalter an, der während des Ladens des Bildes verwendet wird, um die wahrgenommene Ladeleistung zu verbessern.

// Standard ist empty
<Image placeholder="empty" />

• empty: Kein Platzhalter während des Ladens des Bildes.
• blur: Verwendet eine unscharfe Version des Bildes als Platzhalter. Muss mit der blurDataURL-Eigenschaft verwendet werden.
• data:image/...: Verwendet die Data URL als Platzhalter.

Beispiele:

• blur-Platzhalter
• Schimmer-Effekt mit Data URL placeholder-Prop
• Farbeffekt mit blurDataURL-Prop

Erfahren Sie mehr über das placeholder-Attribut.

blurDataURL

Eine Data URL, die als Platzhalterbild verwendet wird, bevor das Bild erfolgreich geladen wird. Kann automatisch gesetzt oder mit der placeholder="blur"-Eigenschaft verwendet werden.

<Image placeholder="blur" blurDataURL="..." />

Das Bild wird automatisch vergrößert und unscharf gemacht, daher wird ein sehr kleines Bild (10px oder weniger) empfohlen.

Automatisch

Wenn src ein statischer Import einer jpg-, png-, webp- oder avif-Datei ist, wird blurDataURL automatisch hinzugefügt — es sei denn, das Bild ist animiert.

Manuell gesetzt

Wenn das Bild dynamisch oder remote ist, müssen Sie blurDataURL selbst bereitstellen. Um eine zu generieren, können Sie Folgendes verwenden:

• Ein Online-Tool wie png-pixel.com
• Eine Bibliothek wie Plaiceholder

Eine große blurDataURL kann die Leistung beeinträchtigen. Halten Sie sie klein und einfach.

Beispiele:

• Standard blurDataURL-Prop
• Farbeffekt mit blurDataURL-Prop

onLoad

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

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

Die Callback-Funktion wird mit einem Argument aufgerufen, dem Event, das ein target hat, das auf das zugrunde liegende <img>-Element verweist.

onError

Eine Callback-Funktion, die aufgerufen wird, wenn das Laden des Bildes fehlschlägt.

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

unoptimized

Ein Boolean, der angibt, ob das Bild optimiert werden soll. Dies ist nützlich für Bilder, die nicht von einer Optimierung profitieren, wie kleine Bilder (weniger als 1KB), Vektorbilder (SVG) oder animierte Bilder (GIF).

import Image from 'next/image'

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

• true: Das Quellbild wird unverändert von src ausgeliefert, anstatt Qualität, Größe oder Format zu ändern.
• false: Das Quellbild wird optimiert.

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

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

overrideSrc

Wenn Sie die src-Prop der <Image>-Komponente bereitstellen, werden sowohl das srcset als auch das src-Attribut automatisch für das resultierende <img> generiert.

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

<img
  srcset="
    /_next/image?url=%2Fme.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fme.jpg&w=828&q=75 2x
  "
  src="/_next/image?url=%2Fme.jpg&w=828&q=75"
/>

In einigen Fällen ist es nicht wünschenswert, das src-Attribut generieren zu lassen, und Sie möchten es möglicherweise mit der overrideSrc-Prop überschreiben.

Zum Beispiel, wenn Sie eine bestehende Website von <img> auf <Image> aktualisieren, möchten Sie möglicherweise dasselbe src-Attribut für SEO-Zwecke wie Bildranking oder Vermeidung von erneutem Crawling beibehalten.

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

<img
  srcset="
    /_next/image?url=%2Fme.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fme.jpg&w=828&q=75 2x
  "
  src="/override.jpg"
/>

decoding

Ein Hinweis an den Browser, ob er warten soll, bis das Bild decodiert ist, bevor andere Inhaltsaktualisierungen angezeigt werden oder nicht.

// Standard ist async
<Image decoding="async" />

• async: Decodiert das Bild asynchron und ermöglicht das Rendern anderer Inhalte, bevor es abgeschlossen ist.
• sync: Decodiert das Bild synchron für eine atomare Darstellung mit anderen Inhalten.
• auto: Keine Präferenz. Der Browser wählt den besten Ansatz.

Erfahren Sie mehr über das decoding-Attribut.

Andere Props

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

• srcSet: Verwenden Sie stattdessen Device Sizes.

Veraltete Props

onLoadingComplete

Warnung: In Next.js 14 veraltet, verwenden Sie stattdessen onLoad.

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.

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

Konfigurationsoptionen

Sie können die Image-Komponente in next.config.js konfigurieren. Folgende Optionen sind verfügbar:

localPatterns

Verwenden Sie localPatterns in Ihrer next.config.js-Datei, um Bilder von bestimmten lokalen Pfaden zu optimieren und alle anderen zu blockieren.

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

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, führt zu einem 400 Bad Request Fehler.

remotePatterns

Verwenden Sie remotePatterns in Ihrer next.config.js-Datei, um Bilder von bestimmten externen Pfaden zuzulassen und alle anderen zu blockieren. Dies stellt sicher, dass nur externe Bilder von Ihrem Konto bereitgestellt werden können.

module.exports = {
  images: {
    remotePatterns: [new URL('https://example.com/account123/**')],
  },
}

Falls Sie eine Version vor 15.3.0 verwenden, können Sie remotePatterns mit dem Objekt konfigurieren:

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

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

Wildcard-Muster:

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 beliebig viele Pfadsegmente am Ende oder Subdomains am Anfang. Diese Syntax funktioniert nicht in der Mitte des Musters.

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

Dies erlaubt Subdomains wie image.example.com. Query-Strings und benutzerdefinierte Ports sind weiterhin blockiert.

Gut zu wissen: Wenn Sie protocol, port, pathname oder search weglassen, wird implizit ** angenommen. Dies wird nicht empfohlen, da es böswilligen Akteuren ermöglichen könnte, URLs zu optimieren, die Sie nicht beabsichtigt haben.

Query-Strings:

Sie können auch Query-Strings mit der search-Eigenschaft einschränken:

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

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 führt zu einem 400 Bad Request.

loaderFile

loaderFiles ermöglicht es Ihnen, einen benutzerdefinierten Bildoptimierungsdienst anstelle von Next.js zu verwenden.

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

Der Pfad muss relativ zum Projektroot sein. Die Datei muss eine Standardfunktion exportieren, die einen URL-String zurückgibt:

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

Beispiel:

• Benutzerdefinierte Image-Loader-Konfiguration

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

deviceSizes

deviceSizes ermöglicht es Ihnen, eine Liste von Breakpoints für Gerätebreiten anzugeben. 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 angegeben wird, wird folgende Standardeinstellung verwendet:

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

imageSizes

imageSizes ermöglicht es Ihnen, eine Liste von Bildbreiten anzugeben. Diese Breiten werden mit dem Array der Gerätegrößen kombiniert, um das vollständige Array der Größen zu bilden, das zur Generierung der Bild-srcset verwendet wird.

Wenn keine Konfiguration angegeben wird, wird folgende Standardeinstellung verwendet:

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

imageSizes wird nur für Bilder verwendet, 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.

qualities

qualities ermöglicht es Ihnen, eine Liste von Bildqualitätswerten anzugeben.

module.exports = {
  images: {
    qualities: [25, 50, 75],
  },
}

Im obigen Beispiel sind nur drei Qualitäten erlaubt: 25, 50 und 75. Wenn die quality-Prop nicht mit einem Wert in diesem Array übereinstimmt, schlägt das Bild mit einem 400 Bad Request fehl.

formats

formats ermöglicht es Ihnen, eine Liste von Bildformaten anzugeben, die verwendet werden sollen.

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

Next.js 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 des Arrays wichtig. Wenn keine Übereinstimmung vorliegt (oder das Quellbild animiert ist), wird das ursprüngliche Format des src-Bildes verwendet.

Sie können AVIF-Unterstützung aktivieren, die auf das ursprüngliche Format des src-Bildes zurückfällt, wenn der Browser AVIF nicht unterstützt:

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

Gut zu wissen:

• Wir empfehlen weiterhin WebP für die meisten Anwendungsfälle.
• AVIF benötigt in der Regel 50% mehr Zeit für die Kodierung, komprimiert jedoch 20% kleiner im Vergleich zu WebP. Das bedeutet, dass die erste Anforderung eines Bildes in der Regel langsamer ist, aber nachfolgende Anfragen, die zwischengespeichert werden, schneller sind.
• Wenn Sie selbst hosten mit einem Proxy/CDN vor Next.js, müssen Sie den Proxy so konfigurieren, dass er den Accept-Header weiterleitet.

minimumCacheTTL

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

Wenn keine Konfiguration angegeben wird, wird folgende Standardeinstellung verwendet:

module.exports = {
  images: {
    minimumCacheTTL: 60, // 1 Minute
  },
}

Sie können die TTL erhöhen, um die Anzahl der Revalidierungen und potenziell die Kosten zu reduzieren:

module.exports = {
  images: {
    minimumCacheTTL: 2678400, // 31 Tage
  },
}

Die Ablaufzeit (oder eher Max Age) des optimierten Bildes wird entweder durch minimumCacheTTL oder den Cache-Control-Header des Upstream-Bildes definiert, je nachdem, welcher 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, um den Cache zu invalidieren, daher ist es am besten, minimumCacheTTL niedrig zu halten. Andernfalls müssen Sie möglicherweise manuell die src-Prop ändern oder die zwischengespeicherte Datei <distDir>/cache/images löschen.

disableStaticImages

disableStaticImages ermöglicht es Ihnen, statische Bildimporte zu deaktivieren.

Das Standardverhalten ermöglicht es Ihnen, statische Dateien wie import icon from './icon.png' zu importieren und diese dann der src-Eigenschaft zuzuweisen. In einigen Fällen möchten Sie diese Funktion möglicherweise deaktivieren, wenn sie mit anderen Plugins kollidiert, die erwarten, dass sich der Import anders verhält.

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

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

dangerouslyAllowSVG

dangerouslyAllowSVG ermöglicht es Ihnen, SVG-Bilder bereitzustellen.

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

Standardmäßig optimiert Next.js SVG-Bilder aus einigen Gründen nicht:

• SVG ist ein Vektorformat, was bedeutet, dass es verlustfrei skaliert werden kann.
• SVG hat viele der gleichen Funktionen wie HTML/CSS, was ohne entsprechende Content Security Policy (CSP)-Header zu Sicherheitslücken führen kann.

Wir empfehlen die Verwendung der unoptimized-Prop, wenn bekannt ist, dass die src-Prop SVG ist. Dies geschieht automatisch, wenn src mit ".svg" endet.

<Image src="/my-image.svg" unoptimized />

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.

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

contentDispositionType

contentDispositionType ermöglicht es Ihnen, den Content-Disposition-Header zu konfigurieren.

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

Standardmäßig setzt der Loader den Content-Disposition-Header auf attachment, um zusätzlichen Schutz zu bieten, da die API beliebige Remote-Bilder bereitstellen kann.

Der Standardwert ist attachment, was den Browser zwingt, das Bild herunterzuladen, wenn es direkt aufgerufen wird. Dies ist besonders wichtig, wenn dangerouslyAllowSVG aktiviert ist.

Sie können optional inline konfigurieren, um dem Browser zu erlauben, das Bild direkt zu rendern, ohne es herunterzuladen.

Veraltete Konfigurationsoptionen

domains

Warnung: Seit Next.js 14 veraltet, zugunsten der strikten remotePatterns, um Ihre Anwendung vor böswilligen Benutzern zu schützen. Verwenden Sie domains nur, wenn Sie den gesamten Inhalt, der von der Domain bereitgestellt wird, besitzen.

Ähnlich wie remotePatterns kann die domains-Konfiguration verwendet werden, um eine Liste von erlaubten Hostnamen für externe Bilder bereitzustellen. Die domains-Konfiguration unterstützt jedoch keine Wildcard-Muster und kann Protokoll, Port oder Pfad nicht einschränken.

Unten sehen Sie ein Beispiel für die domains-Eigenschaft in der next.config.js-Datei:

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

Funktionen

getImageProps

Die getImageProps-Funktion kann verwendet werden, um die Props zu erhalten, die an das zugrunde liegende <img>-Element übergeben würden, und sie stattdessen an eine andere Komponente, ein Stil, ein Canvas usw. zu übergeben.

import { getImageProps } from 'next/image'

const props = getImageProps({
  src: 'https://example.com/image.jpg',
  alt: 'Eine malerische Bergansicht',
  width: 1200,
  height: 800,
})

function ImageWithCaption() {
  return (
    <figure>
      <img {...props} />
      <figcaption>Eine malerische Bergansicht</figcaption>
    </figure>
  )
}

Dies vermeidet auch den Aufruf von React useState(), was zu einer besseren Leistung führen kann, kann jedoch nicht mit der placeholder-Prop verwendet werden, da der Platzhalter niemals entfernt wird.

Bekannte Browser-Bugs

Diese 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 der Verwendung von Stilen mit width/height von auto kann es bei älteren Browsern vor Safari 15, die das Seitenverhältnis nicht beibehalten, zu Layout Shift kommen. Weitere Details finden Sie in diesem MDN-Video.

• Safari 15 - 16.3 zeigt einen grauen Rand während des Ladens an. Safari 16.4 hat dieses Problem behoben. Mögliche Lösungen:

  • Verwenden Sie CSS @supports (font: -apple-system-body) and (-webkit-appearance: none) { img[loading="lazy"] { clip-path: inset(0.6px) } }
  • Verwenden Sie priority, wenn das Bild oberhalb des Folds liegt

• Firefox 67+ zeigt einen weißen Hintergrund während des Ladens an. Mögliche Lösungen:

  • Aktivieren Sie AVIF formats
  • Verwenden Sie placeholder

Beispiele

Styling von Bildern

Das Styling der Image-Komponente ähnelt dem Styling eines normalen <img>-Elements, aber es gibt einige Richtlinien zu beachten:

Verwenden Sie className oder style, nicht styled-jsx. In den meisten Fällen empfehlen wir die Verwendung der className-Prop. Dies kann ein importiertes CSS-Modul, ein globales Stylesheet usw. sein.

import styles from './styles.module.css'

export default function MyImage() {
  return <Image className={styles.image} src="/my-image.png" alt="Mein Bild" />
}

Sie können auch die style-Prop verwenden, um Inline-Styles zuzuweisen.

export default function MyImage() {
  return (
    <Image style={{ borderRadius: '8px' }} src="/my-image.png" alt="Mein Bild" />
  )
}

Bei Verwendung von fill muss das übergeordnete Element position: relative oder display: block haben. Dies ist notwendig für das korrekte Rendering des Bildelements in diesem Layoutmodus.

<div style={{ position: 'relative' }}>
  <Image fill src="/my-image.png" alt="Mein Bild" />
</div>

Sie können styled-jsx nicht verwenden, da es auf die aktuelle Komponente beschränkt ist (es sei denn, Sie markieren den Style als global).

Responsive Bilder mit statischem Export

Wenn Sie ein statisches Bild importieren, setzt Next.js automatisch dessen Breite und Höhe basierend auf der Datei. Sie können das Bild responsiv machen, indem Sie den Stil festlegen:

import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Responsive() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column' }}>
      <Image
        alt="Mountains"
        // Der Import eines Bildes setzt automatisch
        // die Breite und Höhe
        src={mountains}
        sizes="100vw"
        // Das Bild wird in voller Breite angezeigt
        // und behält sein Seitenverhältnis bei
        style={{
          width: '100%',
          height: 'auto',
        }}
      />
    </div>
  )
}

Responsive Bilder mit Remote-URL

Wenn das Quellbild eine dynamische oder Remote-URL ist, müssen Sie die Props width und height angeben, damit Next.js das Seitenverhältnis berechnen kann:

import Image from 'next/image'

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

Probieren Sie es aus:

• Demo des auf die Viewport-Größe reagierenden Bildes

Responsives Bild mit fill

Wenn Sie das Seitenverhältnis des Bildes nicht kennen, können Sie die fill-Prop mit der objectFit-Prop auf cover setzen. Dadurch füllt das Bild die gesamte Breite seines Elterncontainers aus.

import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Fill() {
  return (
    <div
      style={{
        display: 'grid',
        gridGap: '8px',
        gridTemplateColumns: 'repeat(auto-fit, minmax(400px, auto))',
      }}
    >
      <div style={{ position: 'relative', width: '400px' }}>
        <Image
          alt="Mountains"
          src={mountains}
          fill
          sizes="(min-width: 808px) 50vw, 100vw"
          style={{
            objectFit: 'cover', // cover, contain, none
          }}
        />
      </div>
      {/* Und weitere Bilder im Raster... */}
    </div>
  )
}

Hintergrundbild

Verwenden Sie die fill-Prop, um das Bild den gesamten Bildschirmbereich ausfüllen zu lassen:

import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Background() {
  return (
    <Image
      alt="Mountains"
      src={mountains}
      placeholder="blur"
      quality={100}
      fill
      sizes="100vw"
      style={{
        objectFit: 'cover',
      }}
    />
  )
}

Beispiele für die Verwendung der Image-Komponente mit verschiedenen Stilen finden Sie in der Image Component Demo.

Remote-Bilder

Um ein Remote-Bild zu verwenden, sollte die src-Property eine URL-Zeichenkette sein.

import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="https://s3.amazonaws.com/my-bucket/profile.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  )
}

Da Next.js während des Build-Prozesses keinen Zugriff auf Remote-Dateien hat, müssen Sie die Props width, height und optional blurDataURL manuell angeben.

Die Attribute width und height werden verwendet, um das korrekte Seitenverhältnis des Bildes abzuleiten und Layoutverschiebungen durch das Laden des Bildes zu vermeiden. Die width und height bestimmen nicht die gerenderte Größe der Bilddatei.

Um die Optimierung von Bildern sicher zu ermöglichen, definieren Sie eine Liste unterstützter URL-Muster in next.config.js. Seien Sie so spezifisch wie möglich, um böswillige Nutzung zu verhindern. Beispielsweise erlaubt die folgende Konfiguration nur Bilder von einem bestimmten AWS S3-Bucket:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 's3.amazonaws.com',
        port: '',
        pathname: '/my-bucket/**',
        search: '',
      },
    ],
  },
}

Theme-Erkennung

Wenn Sie ein anderes Bild für den Hell- und Dunkelmodus anzeigen möchten, können Sie eine neue Komponente erstellen, die zwei <Image>-Komponenten umschließt und die richtige basierend auf einer CSS-Media-Query 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} />
    </>
  )
}

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 der Hell/Dunkelmodus-Theme-Erkennung

Art Direction

Wenn Sie ein anderes Bild für Mobilgeräte und Desktop anzeigen möchten, manchmal auch als Art Direction bezeichnet, können Sie verschiedene src, width, height und quality Props an getImageProps() übergeben.

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

Hintergrund-CSS

Sie können die srcSet-Zeichenkette sogar in die image-set() CSS-Funktion umwandeln, um ein Hintergrundbild zu optimieren.

import { getImageProps } from 'next/image'

function getBackgroundImage(srcSet = '') {
  const imageSet = srcSet
    .split(', ')
    .map((str) => {
      const [url, dpi] = str.split(' ')
      return `url("${url}") ${dpi}`
    })
    .join(', ')
  return `image-set(${imageSet})`
}

export default function Home() {
  const {
    props: { srcSet },
  } = getImageProps({ alt: '', width: 128, height: 128, src: '/img.png' })
  const backgroundImage = getBackgroundImage(srcSet)
  const style = { height: '100vh', width: '100vw', backgroundImage }

  return (
    <main style={style}>
      <h1>Hello World</h1>
    </main>
  )
}

Versionsverlauf