Composant <Image>

Cette référence API vous aidera à comprendre comment utiliser les props et les options de configuration disponibles pour le composant Image. Pour les fonctionnalités et l'utilisation, consultez la page Composant Image.

import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="/profile.png"
      width={500}
      height={500}
      alt="Picture of the author"
    />
  )
}

Props

Voici un résumé des props disponibles pour le composant Image :

Props Requises

Le composant Image nécessite les propriétés suivantes : src, width, height et alt.

import Image from 'next/image'

export default function Page() {
  return (
    <div>
      <Image
        src="/profile.png"
        width={500}
        height={500}
        alt="Picture of the author"
      />
    </div>
  )
}

src

Doit être l'un des suivants :

• Une image importée statiquement
• Une chaîne de chemin. Cela peut être une URL externe absolue ou un chemin interne selon la prop loader.

Lorsque vous utilisez une URL externe, vous devez l'ajouter à remotePatterns dans next.config.js.

width

La propriété width représente la largeur affichée en pixels, elle affectera donc la taille apparente de l'image.

Requis, sauf pour les images importées statiquement ou les images avec la propriété fill.

height

La propriété height représente la hauteur affichée en pixels, elle affectera donc la taille apparente de l'image.

Requis, sauf pour les images importées statiquement ou les images avec la propriété fill.

alt

La propriété alt est utilisée pour décrire l'image pour les lecteurs d'écran et les moteurs de recherche. C'est aussi le texte de remplacement si les images sont désactivées ou si une erreur survient lors du chargement.

Elle doit contenir du texte qui pourrait remplacer l'image sans changer le sens de la page. Elle n'est pas destinée à compléter l'image et ne doit pas répéter les informations déjà fournies dans les légendes au-dessus ou en dessous de l'image.

Si l'image est purement décorative ou non destinée à l'utilisateur, la propriété alt doit être une chaîne vide (alt="").

En savoir plus

Props Optionnelles

Le composant <Image /> accepte un certain nombre de propriétés supplémentaires au-delà de celles qui sont requises. Cette section décrit les propriétés les plus couramment utilisées du composant Image. Pour plus de détails sur les propriétés moins utilisées, consultez la section Props Avancées.

loader

Une fonction personnalisée utilisée pour résoudre les URLs des images.

Un loader est une fonction qui retourne une URL sous forme de chaîne pour l'image, en fonction des paramètres suivants :

• src
• width
• quality

Voici un exemple d'utilisation d'un loader personnalisé :

'use client'

import Image from 'next/image'

const imageLoader = ({ src, width, quality }) => {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}

export default function Page() {
  return (
    <Image
      loader={imageLoader}
      src="me.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  )
}

Bon à savoir : L'utilisation de props comme loader, qui acceptent une fonction, nécessite d'utiliser des Composants Client pour sérialiser la fonction fournie.

Alternativement, vous pouvez utiliser la configuration loaderFile dans next.config.js pour configurer chaque instance de next/image dans votre application, sans passer de prop.

fill

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

Un booléen qui fait que l'image remplit l'élément parent, ce qui est utile lorsque la width et la height sont inconnues.

L'élément parent doit avoir un style position: "relative", position: "fixed", ou position: "absolute".

Par défaut, l'élément img se verra automatiquement attribuer le style position: "absolute".

Si aucun style n'est appliqué à l'image, celle-ci s'étirera pour remplir le conteneur. Vous pouvez préférer définir object-fit: "contain" pour une image qui est recadrée pour s'adapter au conteneur tout en préservant le ratio d'aspect.

Alternativement, object-fit: "cover" fera que l'image remplira tout le conteneur et sera recadrée pour préserver le ratio d'aspect. Pour que cela fonctionne correctement, le style overflow: "hidden" doit être attribué à l'élément parent.

Pour plus d'informations, voir aussi :

• position
• object-fit
• object-position

sizes

Une chaîne, similaire à une requête média, qui fournit des informations sur la largeur de l'image à différents points de rupture. La valeur de sizes affectera grandement les performances pour les images utilisant fill ou qui sont stylisées pour avoir une taille responsive.

La propriété sizes sert deux objectifs importants liés aux performances des images :

• Premièrement, la valeur de sizes est utilisée par le navigateur pour déterminer quelle taille d'image télécharger, à partir du srcset généré automatiquement par next/image. Lorsque le navigateur choisit, il ne connaît pas encore la taille de l'image sur la page, il sélectionne donc une image de la même taille ou plus grande que la fenêtre d'affichage. La propriété sizes vous permet d'indiquer au navigateur que l'image sera en réalité plus petite que la taille de l'écran. Si vous ne spécifiez pas de valeur sizes pour une image avec la propriété fill, une valeur par défaut de 100vw (largeur totale de l'écran) est utilisée.
• Deuxièmement, la propriété sizes modifie le comportement de la valeur srcset générée automatiquement. Si aucune valeur sizes n'est présente, un petit srcset est généré, adapté à une image de taille fixe (1x/2x/etc). Si sizes est défini, un grand srcset est généré, adapté à une image responsive (640w/750w/etc). Si la propriété sizes inclut des tailles telles que 50vw, qui représentent un pourcentage de la largeur de la fenêtre d'affichage, alors le srcset est tronqué pour ne pas inclure de valeurs trop petites pour être nécessaires.

Par exemple, si vous savez que votre style fera qu'une image sera en pleine largeur sur les appareils mobiles, dans une disposition à 2 colonnes sur les tablettes et à 3 colonnes sur les écrans de bureau, vous devriez inclure une propriété sizes comme suit :

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

Cet exemple sizes pourrait avoir un impact dramatique sur les mesures de performance. Sans le sizes de 33vw, l'image sélectionnée depuis le serveur serait 3 fois plus large que nécessaire. Comme la taille du fichier est proportionnelle au carré de la largeur, sans sizes, l'utilisateur téléchargerait une image 9 fois plus grande que nécessaire.

En savoir plus sur srcset et sizes :

• web.dev
• mdn

quality

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

La qualité de l'image optimisée, un entier entre 1 et 100, où 100 est la meilleure qualité et donc la plus grande taille de fichier. Par défaut à 75.

priority

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

Lorsque true, l'image sera considérée comme haute priorité et préchargée. Le chargement différé est automatiquement désactivé pour les images utilisant priority.

Vous devriez utiliser la propriété priority sur toute image détectée comme l'élément Largest Contentful Paint (LCP). Il peut être approprié d'avoir plusieurs images prioritaires, car différentes images peuvent être l'élément LCP pour différentes tailles de fenêtre d'affichage.

Ne doit être utilisé que lorsque l'image est visible au-dessus de la ligne de flottaison. Par défaut à false.

placeholder

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

Un placeholder à utiliser pendant le chargement de l'image. Les valeurs possibles sont blur, empty, ou data:image/.... Par défaut à empty.

Lorsque blur, la propriété blurDataURL sera utilisée comme placeholder. Si src est un objet provenant d'une importation statique et que l'image importée est .jpg, .png, .webp, ou .avif, alors blurDataURL sera automatiquement remplie, sauf si l'image est détectée comme animée.

Pour les images dynamiques, vous devez fournir la propriété blurDataURL. Des solutions comme Plaiceholder peuvent aider à générer le base64.

Lorsque data:image/..., l'URL Data sera utilisée comme placeholder pendant le chargement de l'image.

Lorsque empty, il n'y aura pas de placeholder pendant le chargement de l'image, seulement un espace vide.

Essayez-le :

• Démo du placeholder blur
• Démo de l'effet scintillement avec la prop placeholder URL Data
• Démo de l'effet couleur avec la prop blurDataURL

Props Avancées

Dans certains cas, vous pourriez avoir besoin d'une utilisation plus avancée. Le composant <Image /> accepte optionnellement les propriétés avancées suivantes.

style

Permet de passer des styles CSS à l'élément image sous-jacent.

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

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

N'oubliez pas que les props requises width et height peuvent interagir avec votre style. Si vous utilisez le style pour modifier la largeur d'une image, vous devriez aussi styliser sa hauteur en auto pour préserver son ratio d'aspect intrinsèque, sinon votre image sera déformée.

onLoadingComplete

'use client'

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

Une fonction de rappel qui est appelée une fois que l'image est complètement chargée et que le placeholder a été supprimé.

La fonction de rappel sera appelée avec un argument, une référence à l'élément <img> sous-jacent.

Bon à savoir : L'utilisation de props comme onLoadingComplete, qui acceptent une fonction, nécessite d'utiliser des Composants Client pour sérialiser la fonction fournie.

onLoad

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

Une fonction de rappel qui est appelée lorsque l'image est chargée.

L'événement load peut se produire avant que le placeholder de l'image ne soit supprimé et que l'image ne soit complètement décodée. Si vous voulez attendre que l'image soit complètement chargée, utilisez plutôt onLoadingComplete.

Bon à savoir : L'utilisation de props comme onLoad, qui acceptent une fonction, nécessite d'utiliser des Composants Client pour sérialiser la fonction fournie.

onError

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

Une fonction de rappel qui est appelée si l'image ne parvient pas à se charger.

Bon à savoir : L'utilisation de props comme onError, qui acceptent une fonction, nécessite d'utiliser des Composants Client pour sérialiser la fonction fournie.

loading

Recommandation : Cette propriété est destinée uniquement à des cas d'utilisation avancés. Passer une image en chargement eager va normalement nuire aux performances. Nous recommandons plutôt d'utiliser la propriété priority, qui préchargera l'image de manière eager.

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

Le comportement de chargement de l'image. Par défaut à lazy.

Lorsque lazy, diffère le chargement de l'image jusqu'à ce qu'elle atteigne une distance calculée depuis la fenêtre d'affichage.

Lorsque eager, charge l'image immédiatement.

En savoir plus sur l'attribut loading.

blurDataURL

Une URL de données (Data URL) à utiliser comme image de substitution avant que l'image src ne soit chargée avec succès. Ne prend effet que lorsqu'elle est combinée avec placeholder="blur".

Doit être une image encodée en base64. Elle sera agrandie et floutée, donc une très petite image (10px ou moins) est recommandée. Inclure des images plus grandes comme substituts peut nuire aux performances de votre application.

Essayez-le :

• Démonstration de la prop blurDataURL par défaut
• Démonstration de l'effet de couleur avec la prop blurDataURL

Vous pouvez aussi générer une URL de données de couleur unie pour correspondre à l'image.

unoptimized

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

Lorsque vrai, l'image source sera servie telle quelle sans modification de qualité, taille ou format. Par défaut à false.

import Image from 'next/image'

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

Depuis Next.js 12.3.0, cette prop peut être assignée à toutes les images en mettant à jour next.config.js avec la configuration suivante :

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

Autres Props

Les autres propriétés du composant <Image /> seront transmises à l'élément img sous-jacent, à l'exception des suivantes :

• srcSet. Utilisez plutôt Device Sizes.
• decoding. Il est toujours "async".

Options de Configuration

En plus des props, vous pouvez configurer le composant Image dans next.config.js. Les options suivantes sont disponibles :

remotePatterns

Pour protéger votre application des utilisateurs malveillants, une configuration est nécessaire pour utiliser des images externes. Cela garantit que seules les images externes de votre compte peuvent être servies par l'API d'optimisation d'images de Next.js. Ces images externes peuvent être configurées avec la propriété remotePatterns dans votre fichier next.config.js, comme indiqué ci-dessous :

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

Bon à savoir : L'exemple ci-dessus garantira que la propriété src de next/image doit commencer par https://example.com/account123/. Tout autre protocole, nom d'hôte, port ou chemin non correspondant renverra une erreur 400 Bad Request.

Voici un autre exemple de la propriété remotePatterns dans le fichier next.config.js :

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

Bon à savoir : L'exemple ci-dessus garantira que la propriété src de next/image doit commencer par https://img1.example.com ou https://me.avatar.example.com ou tout nombre de sous-domaines. Tout autre protocole ou nom d'hôte non correspondant renverra une erreur 400 Bad Request.

Les motifs avec caractères génériques peuvent être utilisés pour pathname et hostname et ont la syntaxe suivante :

• * correspond à un seul segment de chemin ou sous-domaine
• ** correspond à n'importe quel nombre de segments de chemin à la fin ou de sous-domaines au début

La syntaxe ** ne fonctionne pas au milieu du motif.

domains

Avertissement : Nous recommandons de configurer des remotePatterns stricts au lieu de domains pour protéger votre application des utilisateurs malveillants. Utilisez domains uniquement si vous possédez tout le contenu servi depuis le domaine.

Similaire à remotePatterns, la configuration domains peut être utilisée pour fournir une liste de noms d'hôte autorisés pour les images externes.

Cependant, la configuration domains ne prend pas en charge les motifs avec caractères génériques et ne peut pas restreindre le protocole, le port ou le chemin.

Voici un exemple de la propriété domains dans le fichier next.config.js :

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

loaderFile

Si vous souhaitez utiliser un fournisseur de cloud pour optimiser les images au lieu d'utiliser l'API d'optimisation d'images intégrée de Next.js, vous pouvez configurer loaderFile dans votre next.config.js comme suit :

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

Ceci doit pointer vers un fichier relatif à la racine de votre application Next.js. Le fichier doit exporter une fonction par défaut qui renvoie une chaîne, par exemple :

'use client'

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

Alternativement, vous pouvez utiliser la prop loader pour configurer chaque instance de next/image.

Exemples :

• Configuration personnalisée du chargeur d'images

Bon à savoir : Personnaliser le fichier de chargeur d'images, qui accepte une fonction, nécessite d'utiliser des Composants Client pour sérialiser la fonction fournie.

Avancé

La configuration suivante est destinée à des cas d'utilisation avancés et n'est généralement pas nécessaire. Si vous choisissez de configurer les propriétés ci-dessous, vous remplacerez toute modification des valeurs par défaut de Next.js dans les futures mises à jour.

deviceSizes

Si vous connaissez les largeurs d'appareil attendues de vos utilisateurs, vous pouvez spécifier une liste de points de rupture de largeur d'appareil en utilisant la propriété deviceSizes dans next.config.js. Ces largeurs sont utilisées lorsque le composant next/image utilise la prop sizes pour s'assurer que la bonne image est servie pour l'appareil de l'utilisateur.

Si aucune configuration n'est fournie, la valeur par défaut ci-dessous est utilisée.

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

imageSizes

Vous pouvez spécifier une liste de largeurs d'images en utilisant la propriété images.imageSizes dans votre fichier next.config.js. Ces largeurs sont concaténées avec le tableau des tailles d'appareil pour former le tableau complet des tailles utilisées pour générer les srcset d'images.

La raison pour laquelle il y a deux listes séparées est que imageSizes est uniquement utilisé pour les images qui fournissent une prop sizes, ce qui indique que l'image est plus petite que la largeur totale de l'écran. Par conséquent, les tailles dans imageSizes doivent toutes être plus petites que la plus petite taille dans deviceSizes.

Si aucune configuration n'est fournie, la valeur par défaut ci-dessous est utilisée.

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

formats

L'API d'optimisation d'images par défaut détectera automatiquement les formats d'image pris en charge par le navigateur via l'en-tête Accept de la requête.

Si l'en-tête Accept correspond à plus d'un des formats configurés, la première correspondance dans le tableau est utilisée. Par conséquent, l'ordre du tableau est important. S'il n'y a pas de correspondance (ou si l'image source est animée), l'API d'optimisation d'images reviendra au format original de l'image.

Si aucune configuration n'est fournie, la valeur par défaut ci-dessous est utilisée.

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

Vous pouvez activer la prise en charge d'AVIF avec la configuration suivante.

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

Bon à savoir :

• AVIF prend généralement 20 % plus de temps à encoder mais se compresse 20 % plus petit que WebP. Cela signifie que la première fois qu'une image est demandée, elle sera généralement plus lente, puis les requêtes suivantes qui sont mises en cache seront plus rapides.
• Si vous auto-hébergez avec un Proxy/CDN devant Next.js, vous devez configurer le Proxy pour transmettre l'en-tête Accept.

Comportement de la mise en cache

Ce qui suit décrit l'algorithme de mise en cache pour le chargeur par défaut. Pour tous les autres chargeurs, veuillez vous référer à la documentation de votre fournisseur de cloud.

Les images sont optimisées dynamiquement à la demande et stockées dans le répertoire <distDir>/cache/images. Le fichier d'image optimisé sera servi pour les requêtes suivantes jusqu'à ce que l'expiration soit atteinte. Lorsqu'une requête correspond à un fichier mis en cache mais expiré, l'image expirée est servie immédiatement. Ensuite, l'image est optimisée à nouveau en arrière-plan (également appelée revalidation) et sauvegardée dans le cache avec la nouvelle date d'expiration.

Le statut de mise en cache d'une image peut être déterminé en lisant la valeur de l'en-tête de réponse x-nextjs-cache. Les valeurs possibles sont les suivantes :

• MISS - le chemin n'est pas dans le cache (se produit au plus une fois, lors de la première visite)
• STALE - le chemin est dans le cache mais a dépassé le temps de revalidation, donc il sera mis à jour en arrière-plan
• HIT - le chemin est dans le cache et n'a pas dépassé le temps de revalidation

L'expiration (ou plutôt la durée de vie maximale) est définie soit par la configuration minimumCacheTTL, soit par l'en-tête Cache-Control de l'image en amont, selon celle qui est la plus grande. Plus précisément, la valeur max-age de l'en-tête Cache-Control est utilisée. Si s-maxage et max-age sont tous deux trouvés, s-maxage est préféré. Le max-age est également transmis à tous les clients en aval, y compris les CDN et les navigateurs.

• Vous pouvez configurer minimumCacheTTL pour augmenter la durée de mise en cache lorsque l'image en amont n'inclut pas d'en-tête Cache-Control ou que la valeur est très faible.
• Vous pouvez configurer deviceSizes et imageSizes pour réduire le nombre total d'images générées possibles.
• Vous pouvez configurer formats pour désactiver plusieurs formats en faveur d'un seul format d'image.

minimumCacheTTL

Vous pouvez configurer la durée de vie (TTL) en secondes pour les images optimisées mises en cache. Dans de nombreux cas, il est préférable d'utiliser une importation d'image statique qui hachera automatiquement le contenu du fichier et mettra l'image en cache indéfiniment avec un en-tête Cache-Control de immutable.

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

L'expiration (ou plutôt la durée de vie maximale) de l'image optimisée est définie soit par minimumCacheTTL, soit par l'en-tête Cache-Control de l'image en amont, selon celle qui est la plus grande.

Si vous devez modifier le comportement de mise en cache par image, vous pouvez configurer headers pour définir l'en-tête Cache-Control sur l'image en amont (par exemple /some-asset.jpg, et non /_next/image lui-même).

Il n'y a actuellement aucun mécanisme pour invalider le cache, il est donc préférable de garder minimumCacheTTL faible. Sinon, vous devrez peut-être modifier manuellement la prop src ou supprimer <distDir>/cache/images.

disableStaticImages

Le comportement par défaut vous permet d'importer des fichiers statiques tels que import icon from './icon.png' et de les passer à la propriété src.

Dans certains cas, vous pouvez souhaiter désactiver cette fonctionnalité si elle entre en conflit avec d'autres plugins qui s'attendent à ce que l'importation se comporte différemment.

Vous pouvez désactiver les importations d'images statiques dans votre next.config.js :

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

dangerouslyAllowSVG

Le chargeur par défaut n'optimise pas les images SVG pour plusieurs raisons. Premièrement, SVG est un format vectoriel, ce qui signifie qu'il peut être redimensionné sans perte. Deuxièmement, SVG a de nombreuses fonctionnalités similaires à HTML/CSS, ce qui peut entraîner des vulnérabilités sans une Politique de sécurité de contenu (Content Security Policy) appropriée.

Si vous devez servir des images SVG avec l'API d'optimisation d'images par défaut, vous pouvez définir dangerouslyAllowSVG dans votre next.config.js :

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

De plus, il est fortement recommandé de définir également contentDispositionType pour forcer le navigateur à télécharger l'image, ainsi que contentSecurityPolicy pour empêcher l'exécution des scripts intégrés dans l'image.

Images animées

Le chargeur par défaut contournera automatiquement l'optimisation d'images pour les images animées et servira l'image telle quelle.

La détection automatique des fichiers animés est basée sur les meilleurs efforts et prend en charge GIF, APNG et WebP. Si vous souhaitez contourner explicitement l'optimisation d'images pour une image animée donnée, utilisez la prop unoptimized.

Images réactives

Le srcset généré par défaut contient des images 1x et 2x pour prendre en charge différents ratios de pixels d'appareil. Cependant, vous pouvez souhaiter afficher une image réactive qui s'étire avec la fenêtre d'affichage. Dans ce cas, vous devrez définir sizes ainsi que style (ou className).

Vous pouvez afficher une image réactive en utilisant l'une des méthodes ci-dessous.

Image réactive utilisant une importation statique

Si l'image source n'est pas dynamique, vous pouvez l'importer statiquement pour créer une image réactive :

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

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

Essayez-le :

• Démonstration de l'image réactive à la fenêtre d'affichage

Image réactive avec ratio d'aspect

Si l'image source est une URL dynamique ou distante, vous devrez également fournir width et height pour définir le bon ratio d'aspect de l'image réactive :

import Image from 'next/image'

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

Essayez-le :

• Démonstration de l'image réactive à la fenêtre d'affichage

Image réactive avec fill

Si vous ne connaissez pas le ratio d'aspect, vous devrez définir la prop fill et définir position: relative sur le parent. Optionnellement, vous pouvez définir le style object-fit en fonction du comportement d'étirement ou de recadrage souhaité :

import Image from 'next/image'

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

Essayez-le :

• Démonstration de la prop fill

Détection du thème

Si vous souhaitez afficher une image différente pour les modes clair et sombre, vous pouvez créer un nouveau composant qui englobe deux composants <Image> et affiche le bon en fonction d'une requête média CSS.

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

Bon à savoir : Le comportement par défaut de loading="lazy" garantit que seule l'image correcte est chargée. Vous ne pouvez pas utiliser priority ou loading="eager" car cela entraînerait le chargement des deux images. À la place, vous pouvez utiliser fetchPriority="high".

Essayez-le :

• Démonstration de détection de thème clair/sombre

Bugs connus des navigateurs

Ce composant next/image utilise le chargement différé natif des navigateurs, qui peut revenir à un chargement immédiat pour les anciens navigateurs avant Safari 15.4. Lors de l'utilisation du placeholder flou, les anciens navigateurs avant Safari 12 reviendront à un placeholder vide. Lors de l'utilisation de styles avec width/height en auto, il est possible de provoquer un décalage de mise en page (Layout Shift) sur les anciens navigateurs avant Safari 15 qui ne préservent pas le ratio d'aspect. Pour plus de détails, consultez cette vidéo MDN.

• Safari 15 - 16.3 affiche une bordure grise pendant le chargement. Safari 16.4 a corrigé ce problème. Solutions possibles :
  • Utiliser CSS @supports (font: -apple-system-body) and (-webkit-appearance: none) { img[loading="lazy"] { clip-path: inset(0.6px) } }
  • Utiliser priority si l'image est au-dessus de la ligne de flottaison
• Firefox 67+ affiche un fond blanc pendant le chargement. Solutions possibles :
  • Activer formats AVIF
  • Utiliser placeholder

Historique des versions