Composant <Image>

Bon à savoir : Si vous utilisez une version de Next.js antérieure à la 13, vous devrez consulter la documentation next/legacy/image car le composant a été renommé.

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, veuillez consulter la page Composant Image.

import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="/profile.png"
      width={500}
      height={500}
      alt="Photo de l'auteur"
    />
  )
}

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="Photo de l'auteur"
      />
    </div>
  )
}

src

Doit être l'un des éléments suivants :

• Un fichier image importé statiquement
• Une chaîne de caractères représentant un chemin. Cela peut être soit une URL externe absolue, soit un chemin interne en fonction de 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 également le texte de remplacement si les images sont désactivées ou si une erreur se produit lors du chargement de l'image.

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 des 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. Vous trouverez des détails sur les propriétés moins fréquemment utilisées dans la section Props Avancées.

loader

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

Un loader est une fonction qui renvoie une chaîne d'URL pour l'image, en fonction des paramètres suivants :

• src
• width
• quality

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

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="Photo de l'auteur"
      width={500}
      height={500}
    />
  )
}

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, l'image s'étirera pour s'adapter au conteneur. Vous pouvez préférer définir object-fit: "contain" pour une image qui est recadrée pour s'adapter au conteneur et préserver le rapport d'aspect.

Alternativement, object-fit: "cover" fera que l'image remplira tout le conteneur et sera recadrée pour préserver le rapport d'aspect. Pour que cela soit correct, 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 de caractères, 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 réduit 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 mise en page à 2 colonnes sur les tablettes et une mise en page à 3 colonnes sur les écrans de bureau, vous devriez inclure une propriété sizes telle que la suivante :

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 effet 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.

Si la configuration qualities est définie dans next.config.js, la prop quality doit correspondre à l'une des valeurs définies dans la configuration.

Bon à savoir : Si l'image source originale était déjà de faible qualité, définir la prop quality trop élevée pourrait faire que l'image optimisée résultante soit plus grande que l'image source originale.

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 espace réservé à 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 espace réservé. 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 de données sera utilisée comme espace réservé pendant le chargement de l'image.

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

Essayez-le :

• Démo de l'espace réservé blur
• Démo de l'effet de scintillement avec la prop placeholder en URL de données
• Démo de l'effet de 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 également styliser sa hauteur en auto pour préserver son rapport d'aspect intrinsèque, sinon votre image sera déformée.

onLoadingComplete

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

Avertissement : Déprécié depuis Next.js 14 en faveur de onLoad.

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

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

onLoad

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

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

La fonction de rappel sera appelée avec un argument, l'Event qui a une target référençant l'élément <img> sous-jacent.

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.

loading

Recommandation : Cette propriété est destinée uniquement à des cas d'utilisation avancés. Basculer une image en chargement eager va généralement nuire aux performances. Nous recommandons plutôt d'utiliser la propriété priority, qui préchargera activement l'image.

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

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

Avec lazy, le chargement de l'image est différé jusqu'à ce qu'elle atteigne une distance calculée par rapport à la fenêtre d'affichage.

Avec eager, l'image est chargée immédiatement.

En savoir plus sur l'attribut loading.

blurDataURL

Une 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émo de la prop blurDataURL par défaut
• Démo de l'effet couleur avec la prop blurDataURL

Vous pouvez aussi générer une Data URL 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 appliquée à toutes les images en mettant à jour next.config.js avec la configuration suivante :

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

overrideSrc

Lorsque vous fournissez la prop src au composant <Image>, les attributs srcset et src sont générés automatiquement pour l'élément <img> résultant.

<Image src="/me.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"
/>

Dans certains cas, il n'est pas souhaitable que l'attribut src soit généré et vous pouvez souhaiter le remplacer en utilisant la prop overrideSrc.

Par exemple, lors de la mise à niveau d'un site web existant de <img> vers <Image>, vous pouvez vouloir conserver le même attribut src pour des raisons de SEO comme le classement des images ou éviter un nouveau crawl.

<Image src="/me.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

Un indice pour le navigateur indiquant s'il doit attendre que l'image soit décodée avant d'afficher d'autres mises à jour de contenu ou non. Par défaut à async.

Les valeurs possibles sont les suivantes :

• async - Décoder l'image de manière asynchrone et permettre à d'autres contenus d'être rendus avant que cela ne soit terminé.
• sync - Décoder l'image de manière synchrone pour une présentation atomique avec d'autres contenus.
• auto - Aucune préférence pour le mode de décodage ; le navigateur décide ce qui est le mieux.

En savoir plus sur l'attribut decoding.

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.

Options de Configuration

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

localPatterns

Vous pouvez éventuellement configurer localPatterns dans votre fichier next.config.js afin d'autoriser l'optimisation de chemins spécifiques et bloquer tous les autres chemins.

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

Bon à savoir : L'exemple ci-dessus garantira que la propriété src de next/image doit commencer par /assets/images/ et ne doit pas avoir de chaîne de requête. Toute tentative d'optimiser un autre chemin répondra avec 400 Bad Request.

remotePatterns

Pour protéger votre application des utilisateurs malveillants, une configuration est requise 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/**',
        search: '',
      },
    ],
  },
}

Bon à savoir : L'exemple ci-dessus garantira que la propriété src de next/image doit commencer par https://example.com/account123/ et ne doit pas avoir de chaîne de requête. Tout autre protocole, nom d'hôte, port ou chemin non correspondant répondra avec 400 Bad Request.

Voici un exemple de la propriété remotePatterns dans le fichier next.config.js utilisant un motif générique dans hostname :

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

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. Il ne peut pas avoir de port ou de chaîne de requête. Tout autre protocole ou nom d'hôte non correspondant répondra avec 400 Bad Request.

Les motifs 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.

Bon à savoir : Lorsque vous omettez protocol, port, pathname ou search, alors le générique ** est implicite. Ce n'est pas recommandé car cela peut permettre à des acteurs malveillants d'optimiser des URLs que vous ne souhaitiez pas.

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

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

Bon à savoir : L'exemple ci-dessus garantira que la propriété src de next/image doit commencer par https://assets.example.com et doit avoir exactement la chaîne de requête ?v=1727111025337. Tout autre protocole ou chaîne de requête répondra avec 400 Bad Request.

domains

Avertissement : Déprécié depuis Next.js 14 en faveur des remotePatterns stricts afin de 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ôtes autorisés pour les images externes.

Cependant, la configuration domains ne prend pas en charge les motifs 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 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',
  },
}

Cela 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 :

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

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 écraserez 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 distinctes est que imageSizes est uniquement utilisé pour les images qui fournissent une prop sizes, ce qui indique que l'image est moins large que l'écran complet. 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],
  },
}

qualities

L'API d'optimisation d'images par défaut autorisera automatiquement toutes les qualités de 1 à 100. Si vous souhaitez restreindre les qualités autorisées, vous pouvez ajouter une configuration à next.config.js.

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

Dans l'exemple ci-dessus, seules trois qualités sont autorisées : 25, 50 et 75. Si la prop quality ne correspond pas à une valeur dans ce tableau, l'image échouera avec 400 Bad Request.

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 d'origine 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 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 il 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 et 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 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 cloud.

Les images sont optimisées dynamiquement lors de la requête 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 (stale). Ensuite, l'image est optimisée à nouveau en arrière-plan (également appelé 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 Max Age) est définie soit par la configuration minimumCacheTTL, soit par l'en-tête Cache-Control de l'image en amont, selon la valeur 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 trouvés, alors 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 le Time to Live (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 Max Age) 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 la valeur 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 elle-même).

Il n'y a pas de mécanisme pour invalider le cache à ce stade, donc il est 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' puis 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'import se comporte différemment.

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

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

dangerouslyAllowSVG

Le loader 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 de qualité. Deuxièmement, SVG possède de nombreuses fonctionnalités similaires à HTML/CSS, ce qui peut entraîner des vulnérabilités sans les bonnes en-têtes de politique de sécurité du contenu (CSP).

Par conséquent, nous recommandons d'utiliser la propriété unoptimized lorsque la propriété src est connue pour être une SVG. Cela se fait automatiquement lorsque src se termine par ".svg".

Cependant, si vous avez besoin de servir des images SVG avec l'API d'optimisation d'image 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 de scripts intégrés dans l'image.

Images animées

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

La détection automatique des fichiers animés est effectuée au mieux et prend en charge GIF, APNG et WebP. Si vous souhaitez contourner explicitement l'optimisation d'image pour une image animée donnée, utilisez la propriété unoptimized.

Images responsives

Le srcset généré par défaut contient des images 1x et 2x pour prendre en charge différentes densités de pixels des appareils. Cependant, vous pouvez souhaiter afficher une image responsive 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 responsive en utilisant l'une des méthodes suivantes.

Image responsive avec import statique

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

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 responsive à la fenêtre d'affichage

Image responsive avec ratio d'aspect

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

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 responsive à la fenêtre d'affichage

Image responsive avec fill

Si vous ne connaissez pas le ratio d'aspect, vous devrez définir la propriété fill et définir position: relative sur l'élément 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: '300px', height: '500px' }}>
      <Image
        src={photoUrl}
        alt="Photo de l'auteur"
        sizes="300px"
        fill
        style={{
          objectFit: 'contain',
        }}
      />
    </div>
  )
}

Essayez-le :

• Démonstration de la propriété fill

Détection de thème CSS

Si vous souhaitez afficher une image différente pour les modes clair et sombre, vous pouvez créer un nouveau composant qui encapsule 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 la bonne image 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 la détection de thème clair/sombre

getImageProps

Pour des cas d'utilisation plus avancés, vous pouvez appeler getImageProps() pour obtenir les props qui seraient passés à l'élément <img> sous-jacent, et les passer à un autre composant, style, canvas, etc.

Cela évite également d'appeler useState() de React, ce qui peut améliorer les performances, mais ne peut pas être utilisé avec la propriété placeholder car le placeholder ne sera jamais supprimé.

Détection de thème avec Picture

Si vous souhaitez afficher une image différente pour les modes clair et sombre, vous pouvez utiliser l'élément <picture> pour afficher une image différente en fonction du schéma de couleurs préféré de l'utilisateur.

import { getImageProps } from 'next/image'

export default function Page() {
  const common = { alt: 'Exemple de thème', 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>
  )
}

Direction artistique

Si vous souhaitez afficher une image différente pour mobile et bureau, parfois appelée Direction artistique, vous pouvez fournir différentes props src, width, height et quality à getImageProps().

import { getImageProps } from 'next/image'

export default function Home() {
  const common = { alt: 'Exemple de direction artistique', 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>
  )
}

Arrière-plan CSS

Vous pouvez même convertir la chaîne srcSet en fonction CSS image-set() pour optimiser une image d'arrière-plan.

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>Bonjour le monde</h1>
    </main>
  )
}

Bogues connus des navigateurs

Ce composant next/image utilise le chargement différé natif des navigateurs, qui peut revenir à un chargement immédiat pour les navigateurs plus anciens que Safari 15.4. Lors de l'utilisation du placeholder flou, les navigateurs plus anciens que 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 navigateurs plus anciens que Safari 15 qui ne préservent pas le ratio d'aspect. Pour plus de détails, voir 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 arrière-plan blanc pendant le chargement. Solutions possibles :
  • Activer les formats formats AVIF
  • Utiliser placeholder

Historique des versions