Images

Astro vous propose plusieurs façons d’utiliser des images sur votre site, qu’elles soient stockées localement dans votre projet, liées à une URL externe ou gérées dans un CMS ou un CDN.

Astro fournit des composants Image et Picture, le traitement de la syntaxe d’image Markdown, des composants SVG et une fonction de génération d’images pour optimiser et/ou transformer vos images.

Vous pouvez toujours choisir d’utiliser des images et des fichiers SVG en utilisant des éléments HTML natifs dans les fichiers .astro ou Markdown, ou la manière standard pour votre type de fichier (par exemple <img /> dans MDX et JSX). Cependant, Astro n’effectue aucun traitement ni optimisation de ces images.

Consultez la référence complète de l’API des composants <Image /> et <Picture />.

Où stocker les images

`src/` vs `public/`

Nous recommandons que les images locales soient conservées dans src/ si possible afin qu’Astro puisse les transformer, les optimiser et les regrouper. Les fichiers dans le répertoire /public sont toujours servis ou copiés dans le dossier de construction tels quels, sans aucun traitement.

Vos images locales stockées dans src/ peuvent être utilisées par tous les fichiers de votre projet : .astro, .md, .mdx, .mdoc, et d’autres frameworks d’interface utilisateur. Les images peuvent être stockées dans n’importe quel dossier, y compris avec votre contenu.

Stockez vos images dans le dossier public/ si vous voulez éviter tout traitement ou avoir un lien public direct vers elles.

Images distantes

Vous pouvez également choisir de stocker vos images à distance, dans un système de gestion de contenu (CMS) ou une plateforme de gestion des ressources numériques (DAM). Astro peut récupérer vos données à distance à l’aide d’API ou afficher des images à partir de leur chemin d’accès complet.

Pour une protection supplémentaire lors du traitement de sources externes, les composants d’image et la fonction d’assistance d’Astro traiteront uniquement (par exemple, optimiseront, transformeront) les images provenant de sources d’images autorisées spécifiées dans votre configuration. Les images distantes provenant d’autres sources seront affichées sans traitement.

Images dans les fichiers `.astro`

Dans les fichiers .astro, une image locale doit être importée depuis son chemin relatif. Cette importation fournit la valeur src pour votre image.

Les images distantes et celles dans public/ ne nécessitent pas d’importation, mais nécessitent à la place une URL (chemin complet ou relatif à votre site) pour src.

Importez et utilisez les composants <Image /> et <Picture /> natifs d’Astro pour des images optimisées. La syntaxe Astro prend également en charge l’écriture directe d’une balise HTML <img>, ce qui évite le traitement de l’image.

---
import { Image } from 'astro:assets';
import localBirdImage from '../../images/subfolder/localBirdImage.png';
---
<Image src={localBirdImage} alt="Un oiseau assis sur un nid d'œufs." />
<Image src="/images/bird-in-public-folder.jpg" alt="Un oiseau." width="50" height="50" />
<Image src="https://example.com/remote-bird.jpg" alt="Un oiseau." width="50" height="50" />

<img src={localBirdImage.src} alt="Un oiseau assis sur un nid d'œufs.">
<img src="/images/bird-in-public-folder.jpg" alt="Un oiseau.">
<img src="https://example.com/remote-bird.jpg" alt="Un oiseau.">

Consultez la référence complète de l’API des composants <Image /> et <Picture />.

Méthode associée : Importer dynamiquement des images

Afficher des images optimisées avec le composant `<Image />`

Utilisez le composant Astro intégré <Image /> pour afficher des versions optimisées :

de vos images locales situées dans le dossier src/
d’images distantes configurées provenant de sources autorisées

<Image /> peut transformer les dimensions, le type de fichier et la qualité d’une image locale ou distante autorisée pour contrôler l’image affichée. Cette transformation s’effectue lors de la création des pages pré-rendues. Si votre page est rendue à la demande, elle s’effectue à la volée lors de son affichage. La balise <img> résultante inclut les attributs alt, loading et decoding et déduit les dimensions de l’image pour éviter le décalage cumulatif de mise en page (« Cumulative Layout Shift » en anglais ou CLS).

---
// importer le composant Image et l'image
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png'; // Image est en 1600x900
---

<!-- `alt` est obligatoire pour le composant Image -->
<Image src={myImage} alt="La description de mon image." />

<!-- Résultat du pré-rendu -->
<!-- L'image est optimisée, les attributs appropriés sont appliqués -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="La description de mon image."
/>

<!-- Résultat du rendu à la demande -->
<!-- src utilisera un point de terminaison généré à la demande -->
<img
  src="/_image?href=%2F_astro%2Fmy_image.hash.webp&amp;w=1600&amp;h=900&amp;f=webp"
  <!-- ... -->
/>

Le composant <Image /> accepte plusieurs propriétés de composant ainsi que tous les attributs acceptés par la balise HTML <img>.

L’exemple suivant fournit une classe (class) au composant Image qui s’appliquera à l’élément final <img>.

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---

<!-- `alt` est obligatoire pour le composant Image -->
<Image src={myImage} alt="" class="my-class" />

<!-- Résultat du pré-rendu -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  class="my-class"
  alt=""
/>

Créez des images réactives avec le composant `<Picture />`

Ajouté à la version : astro@3.3.0

Utilisez le composant Astro intégré <Picture /> pour afficher une image réactive avec plusieurs formats et/ou tailles. Comme pour le composant <Image />, les images sont traitées au moment de la construction des pages pré-rendues. Lorsque votre page est rendue à la demande, le traitement s’effectue à la volée lors de son affichage.

---
import { Picture } from 'astro:assets';
import myImage from '../assets/my_image.png'; // Image est de 1600x900
---

<!-- `alt` est obligatoire pour le composant Image -->
<Picture src={myImage} formats={['avif', 'webp']} alt="Une description de mon image." />

<!-- Résultat du pré-rendu -->
<picture>
  <source srcset="/_astro/my_image.hash.avif" type="image/avif" />
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="Une description de mon image."
  />
</picture>

Consultez le détail des propriétés du composant <Picture /> dans la référence astro:assets.

Afficher les images non traitées avec la balise HTML `<img>`

La syntaxe de template Astro prend également en charge l’écriture directe d’une balise <img>, avec un contrôle total sur sa sortie finale. Ces images ne seront pas traitées ni optimisées. Elle accepte toutes les propriétés de balise HTML <img>, et la seule propriété requise est src.

Les images locales doivent être importées à partir du chemin relatif du fichier .astro existant, ou vous pouvez configurer et utiliser un alias d’importation. Ensuite, vous pouvez accéder à la source (src) de l’image et aux autres propriétés à utiliser dans la balise <img>.

Les ressources d’image importées correspondent à la signature suivante :

interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}

L’exemple suivant utilise les propriétés height et width de l’image pour éviter le décalage de mise en page cumulé (CLS) et améliorer les Core Web Vitals :

---
// importer des images locales
import myDog from '../../images/pets/local-dog.jpg';
---
// accéder aux propriétés de l'image
<img src={myDog.src} width={myDog.width} height={myDog.height} alt="Un chien qui aboie." />

Images dans `public/`

Pour les images situées dans public/, utilisez le chemin du fichier de l’image par rapport au dossier public comme valeur pour src :

<img src="/images/public-cat.jpg" alt="Un chat qui dort." >

Images distantes

Pour les images distantes, utilisez l’URL complète de l’image comme valeur pour src :

<img src="https://example.com/remote-cat.jpg" alt="Un chat qui dort." >

Choisir entre `<Image />` et `<img>`

Le composant <Image /> optimise votre image et déduit la largeur et la hauteur (pour les images qu’il peut traiter) en se basant sur le rapport hauteur/largeur d’origine afin d’éviter le CLS. C’est la manière à privilégier pour utiliser des images dans les fichiers .astro chaque fois que cela est possible.

Utilisez l’élément HTML <img> lorsque vous ne pouvez pas utiliser le composant <Image />, par exemple :

pour les formats d’image non pris en charge
lorsque vous ne souhaitez pas que votre image soit optimisée par Astro
pour accéder à l’attribut src et de le modifier dynamiquement côté client

Définition des valeurs par défaut

Actuellement, il n’existe aucun moyen de spécifier des valeurs par défaut pour tous les composants <Image /> ou <Picture/>. Les attributs obligatoires doivent être définis sur chaque composant individuel.

Comme alternative, vous pouvez envelopper ces composants dans un autre composant Astro pour les réutiliser. Par exemple, vous pouvez créer un composant pour les images de vos articles de blog qui reçoit des attributs en tant que props et applique des styles cohérents à chaque image :

---
import { Image } from 'astro:assets';

const { src, ...attrs } = Astro.props;
---
<Image src={src} {...attrs} />

<style>
  img {
    margin-block: 2.5rem;
    border-radius: 0.75rem;
  }
</style>

Autoriser les images distantes

Vous pouvez configurer des listes de domaines d’URL de sources d’images autorisées et des modèles pour l’optimisation des images en utilisant image.domains et image.remotePatterns. Cette configuration est une couche de sécurité supplémentaire pour protéger votre site lorsqu’il affiche des images provenant d’une source externe.

Les images distantes provenant d’autres sources ne seront pas optimisées, mais l’utilisation du composant <Image /> pour ces images empêchera le décalage cumulatif de la mise en page (CLS).

Par exemple, la configuration suivante permet d’optimiser seulement les images distantes provenant de astro.build :

export default defineConfig({
  image: {
    domains: ["astro.build"],
  }
});

La configuration suivante n’autorise que les images distantes provenant d’hôtes HTTPS :

export default defineConfig({
  image: {
    remotePatterns: [{ protocol: "https" }],
  }
});

Composants SVG

Ajouté à la version : astro@5.7.0 Nouveau

Astro vous permet d’importer des fichiers SVG et de les utiliser comme composants Astro. Astro intègre le contenu SVG dans votre sortie HTML.

Référencez l’importation par défaut de tout fichier .svg local. Cette importation étant traitée comme un composant Astro, vous devez utiliser les mêmes conventions (par exemple, la casse) que pour l’utilisation de balises dynamiques.

---
import Logo from './chemin/vers/un/fichier.svg';
---

<Logo />

Votre composant SVG, comme <Image /> ou tout autre composant Astro, n’est pas disponible dans les composants de framework UI, mais peut être transmis à un composant du framework dans un composant .astro.

Attributs des composants SVG

Vous pouvez transmettre des props tels que width, height, fill, stroke et tout autre attribut accepté par l’élément natif <svg>. Ces attributs seront automatiquement appliqués à l’élément <svg> sous-jacent. Si une propriété est présente dans le fichier .svg d’origine et transmise au composant, la valeur transmise au composant remplacera la valeur d’origine.

---
import Logo from '../assets/logo.svg';
---

<Logo width={64} height={64} fill="currentColor" />

Utilisation d’images provenant d’un CMS ou d’un CDN

Les CDN d’images fonctionnent avec toutes les options d’images d’Astro. Utilisez l’URL complète d’une image comme attribut src dans le composant <Image />, une balise <img>, ou dans la notation Markdown. Pour l’optimisation des images distantes, il faut également configurer les domaines autorisés ou les modèles d’URL.

Alternativement, le CDN peut fournir ses propres SDK pour s’intégrer plus facilement dans un projet Astro. Par exemple, Cloudinary prend en charge un SDK Astro qui vous permet de déposer facilement des images avec leur composant CldImage ou un SDK Node.js qui peut générer des URL à utiliser avec une balise <img> dans un environnement Node.js.

Consultez la référence complète de l’API des composants <Image /> et <Picture />.

Images dans les fichiers Markdown

Utilisez la syntaxe Markdown standard ![alt](src) dans vos fichiers .md. Cette syntaxe fonctionne avec l’API du Service d’images d’Astro pour optimiser vos images locales stockées dans src/ et les images distantes. Les images stockées dans le dossier public/ ne sont jamais optimisées.

# Ma Page Markdown

<!-- Image locale stockée dans src/assets/ -->
<!-- Utiliser un chemin d'accès relatif ou un alias d'importation -->
![Un ciel étoilé.](../assets/stars.png)

<!-- Image stockée dans public/images/ -->
<!-- Utiliser le chemin d'accès relatif à public/ -->
![Un ciel étoilé.](/images/stars.png)

<!-- Image distante sur un autre serveur -->
<!-- Utiliser l'URL complète de l'image -->
![Astro](https://example.com/images/remote-image.png)

La balise HTML <img> peut également être utilisée pour afficher des images stockées dans public/ ou des images distantes sans aucune optimisation ou traitement d’image. Cependant, <img> n’est pas prise en charge pour vos images locales dans src.

Les composants <Image /> et <Picture /> ne sont pas disponibles dans les fichiers .md. Si vous avez besoin de plus de contrôle sur les attributs de votre image, nous vous recommandons d’utiliser l’intégration MDX d’Astro pour ajouter la prise en charge du format de fichier .mdx. MDX permet d’utiliser des options d’image supplémentaires disponibles dans MDX, y compris la combinaison de composants avec la syntaxe Markdown.

Images dans les fichiers MDX

Vous pouvez utiliser les composants <Image /> et <Picture /> d’Astro dans vos fichiers .mdx en important à la fois le composant et votre image. Utilisez-les tels qu’ils sont utilisés dans les fichiers .astro. La balise JSX <img /> est également prise en charge pour les images non traitées et utilise la même importation d’image que la balise HTML <img>.

De plus, il y a un support pour la syntaxe standard Markdown ![alt](src) sans importation nécessaire

---
title: Le titre de ma page
---
import { Image } from 'astro:assets';
import rocket from '../assets/rocket.png';

# Ma Page MDX

// Image locale stockée dans le même dossier
![Houston dans la nature](houston.png)

// Image locale stockée dans src/assets/
<Image src={rocket} alt="Une fusée dans l'espace." />
<img src={rocket.src} alt="Une fusée dans l'espace." />
![Une fusée dans l'espace.](../assets/rocket.png)

// Image stockée dans public/images/
<Image src="/images/stars.png" alt="Un ciel étoilé." />
<img src="/images/stars.png" alt="Un ciel étoilé." />
![Un ciel étoilé.](/images/stars.png)

// Image distante sur un autre serveur
<Image src="https://example.com/images/remote-image.png" />
<img src="https://example.com/images/remote-image.png" />
![Astro](https://example.com/images/remote-image.png)

Consultez la référence complète de l’API des composants <Image /> et <Picture />.

Images dans les collections de contenus

Les images dans les collections de contenus seront traitées de la même manière que dans Markdown et MDX selon le type de fichier que vous utilisez.

En outre, vous pouvez déclarer une image associée à une entrée de la collection de contenus, telle que l’image de couverture d’un article de blog, dans votre frontmatter en utilisant son chemin d’accès relatif au dossier courant :

---
title: "Mon premier article de blog"
cover: "./firstpostcover.jpeg" # se résoudra en "src/content/blog/firstblogcover.jpeg"
coverAlt: "Photographie d'un coucher de soleil derrière une chaîne de montagnes."
---

Ceci est un article de blog

L’assistant image pour le schéma des collections de contenu vous permet de valider et d’importer l’image.

import { defineCollection, z } from "astro:content";

const blogCollection = defineCollection({
  schema: ({ image }) => z.object({
    title: z.string(),
    cover: image(),
    coverAlt: z.string(),
  }),
});

export const collections = {
  blog: blogCollection,
};

L’image sera importée et transformée en métadonnées, vous permettant de la passer comme src à <Image/>, <img>, ou getImage().

L’exemple ci-dessous montre une page d’index de blog qui rend la photo de couverture et le titre de chaque article de blog à partir du schéma ci-dessus :

---
import { Image } from "astro:assets";
import { getCollection } from "astro:content";
const allBlogPosts = await getCollection("blog");
---

{
  allBlogPosts.map((post) => (
    <div>
      <Image src={post.data.cover} alt={post.data.coverAlt} />
      <h2>
        <a href={"/blog/" + post.slug}>{post.data.title}</a>
      </h2>
    </div>
  ))
}

Images dans les composants framework UI

Le composant <Image />, comme tout autre composant Astro, n’est pas disponible dans les composants de framework UI.

Mais vous pouvez transmettre le contenu statique généré par <Image /> à un composant de framework à l’intérieur d’un fichier .astro en tant qu’enfants ou en utilisant un <slot/> nommé :

---
import ReactComponent from './ReactComponent.jsx';
import { Image } from 'astro:assets';
import stars from '~/stars/docline.png';
---

<ReactComponent>
  <Image src={stars} alt="Un ciel nocturne étoilé." />
</ReactComponent>

Vous pouvez également utiliser la syntaxe d’image propre au framework pour restituer une image (par exemple <img /> dans JSX, <img> dans Svelte).

Les images locales doivent d’abord être importées pour accéder à leurs propriétés d’image telles que src.

import stars from "../assets/stars.png";

export default function ReactImage() {
  return (
    <img src={stars.src} alt="Un ciel étoilé." />
  )
}

<script>
  import stars from '../assets/stars.png';
</script>

<img src={stars.src} alt="Un ciel étoilé." />

Générer des images avec `getImage()`

La fonction getImage() est prévue pour générer des images destinées à être utilisées ailleurs que directement en HTML, par exemple dans une route d’API. Lorsque vous avez besoin d’options que les composants <Picture> et <Image> ne prennent pas actuellement en charge, vous pouvez utiliser la fonction getImage() pour créer votre propre composant <Image /> personnalisé.

Pour en savoir plus, consultez la référence getImage().

Méthode associée : Créer un composant image personnalisé

Texte alternatif

Tous les utilisateurs ne voient pas les images de la même manière. L’accessibilité est donc une préoccupation particulièrement importante lors de l’utilisation d’images. Utilisez l’attribut alt pour fournir un texte alternatif descriptif pour les images.

Cet attribut est requis pour les composants <Image /> et <Picture />. Si aucun texte alt n’est fourni, un message d’erreur utile vous rappellera d’inclure l’attribut alt.

Si l’image est simplement décorative (c’est-à-dire qu’elle ne contribue pas à la compréhension de la page), définissez alt="" pour que les lecteurs d’écran sachent qu’ils doivent ignorer l’image.

Service d’images par défaut

Sharp est le service d’images par défaut utilisé pour astro:assets. Vous pouvez configurer le service d’images en utilisant l’option image.service.

Lorsque vous utilisez un gestionnaire de paquet strict comme pnpm, vous pouvez avoir besoin d’installer manuellement Sharp dans votre projet même si c’est une dépendance d’Astro :

pnpm add sharp

Configurer le service no-op passthrough

Si votre adaptateur ne supporte pas l’optimisation d’image Sharp intégrée à Astro (par exemple Deno, Cloudflare), vous pouvez configurer un service d’image no-op pour vous permettre d’utiliser les composants <Image /> et <Picture />. Notez qu’Astro n’effectue aucune transformation ou traitement d’image dans ces environnements. Cependant, vous pouvez toujours profiter des autres avantages de l’utilisation de astro:assets, y compris l’absence de décalage cumulatif de la mise en page (CLS), l’application de l’attribut alt, et une expérience de création cohérente.

Configurez passthroughImageService() pour éviter les traitements d’image Sharp :

import { defineConfig, passthroughImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: passthroughImageService()
  }
});

Mise en cache des ressources

Astro stocke les images traitées dans un répertoire cache lors de la création du site, tant pour les images locales que pour les images distantes provenant de sources autorisées. En préservant le répertoire de cache entre les constructions, les ressources traitées sont réutilisées, ce qui améliore le temps de construction et l’utilisation de la bande passante.

Le répertoire de cache par défaut est ./node_modules/.astro, mais il peut être modifié en utilisant le paramètre de configuration cacheDir.

Images distantes

Les images distantes dans le cache des ressources sont gérées sur la base de HTTP Caching, et respectent l’En-tête Cache-Control renvoyé par le serveur distant. Les images sont mises en cache si l’en-tête Cache-Control le permet et seront utilisées jusqu’à ce qu’elles ne soient plus fraîches.

Revalidation

Ajouté à la version : astro@5.1.0

La Revalidation réduit l’utilisation de la bande passante et le temps de construction en vérifiant auprès du serveur distant si une image mise en cache qui a expiré est toujours d’actualité. Si le serveur indique que l’image est encore fraîche, la version mise en cache est réutilisée, sinon l’image est téléchargée à nouveau.

La revalidation nécessite que le serveur distant envoie des en-têtes Last-Modified et/ou Etag (entity tag) avec ses réponses. Cette fonction est disponible pour les serveurs distants qui prennent en charge les en-têtes If-Modified-Since et If-None-Match.

Intégrations communautaires

Il existe plusieurs intégrations d’images communautaires pour optimiser et travailler avec des images dans votre projet Astro.

Contribuer Communauté Parrainer

Images

Où stocker les images

src/ vs public/

Images distantes

Images dans les fichiers .astro

Afficher des images optimisées avec le composant <Image />

Créez des images réactives avec le composant <Picture />

Afficher les images non traitées avec la balise HTML <img>

Images dans public/

Images distantes

Choisir entre <Image /> et <img>

Définition des valeurs par défaut

Autoriser les images distantes

Composants SVG

Attributs des composants SVG

Utilisation d’images provenant d’un CMS ou d’un CDN

Images dans les fichiers Markdown

Images dans les fichiers MDX

Images dans les collections de contenus

Images dans les composants framework UI

Générer des images avec getImage()

Texte alternatif

Service d’images par défaut

Configurer le service no-op passthrough

Mise en cache des ressources

Images distantes

Revalidation

Intégrations communautaires

`src/` vs `public/`

Images dans les fichiers `.astro`

Afficher des images optimisées avec le composant `<Image />`

Créez des images réactives avec le composant `<Picture />`

Afficher les images non traitées avec la balise HTML `<img>`

Images dans `public/`

Choisir entre `<Image />` et `<img>`

Générer des images avec `getImage()`