CSS et Stylisation

Astro à été conçu pour rendre la création de style et l’écriture de CSS facile. Écrivez votre propre CSS directement dans un composant Astro ou importez une bibliothèque de style préférée comme Tailwind. Les préprocesseurs comme Sass et Less sont également supportés.

Ajouter du style à un composant Astro est aussi facile que d’ajouter une balise <style> à votre Template de composant ou de page. Quand vous placez une balise <style> dans un composant Astro, Astro détectera le CSS et chargera vos styles pour vous, automatiquement.

<style>
  h1 { color: red; }
</style>

Les règles CSS <style> d’Astro sont automatiquement limitées au composant par défaut. Ces styles sont transpilés en arrière-plan pour ne s’appliquer qu’à l’HTML écrit à l’intérieur du même composant. Le CSS que vous écrivez dans un composant Astro est automatiquement encapsulé dans ce composant.

<style>
  h1 { color: red; }
  h1.astro-HHNQFKH6 { color: red; }
  .text { color: blue; }
  .text.astro-HHNQFKH6 { color: blue; }
</style>

Les styles délimitiés ne se propagent pas et n’affectent pas le reste de votre site. Dans Astro, c’est quelque chose de courant d’utiliser des sélecteurs de bas niveau comme h1 {} ou p {} car ils seront transpilés avec des encapsulations dans les fichiers servis à l’utilisateur final.

Les styles délimités ne s’appliquent pas à d’autres composants Astro contenus dans votre template. Si vous avez besoin d’appliquer des styles à un composant enfant, envisagez de placer ce composant dans une <div> (ou tout autre élément) que vous pourrez ensuite personnaliser.

Même si nous recommandons les styles délimités pour la plupart des composants, vous pouvez éventuellement trouver une raison valide d’écrire du CSS non délimité global. Vous pouvez désactiver l’encapsulation automatique de CSS avec l’attribut <style is:global>.

<style is:global>
  /* Non délimité, délivré directement et sans modifications au navigateur.
     S'applique à tous les <h1> dans votre site. */
  h1 { color: red; }
</style>

Vous pouvez aussi mélanger les règles CSS globales et délimitées dans la même balise <style> en utilisant le sélecteur :global(). Cela devient un modèle puissant pour appliquer des styles CSS aux enfants de votre composant.

<style>
  /* Limité à ce composant seulement. */
  h1 { color: red; }
  /* Mixé : Applique seulement aux éléments enfants `h1` de ce composant. */
  article :global(h1) {
    color: blue;
  }
</style>
<h1>Titre</h1>
<article><slot /></article>

C’est une bonne façon de styliser des éléments comme des articles de blog, ou des documents avec un contenu CMS qui se trouve en dehors d’Astro. Mais soyez prudent : Mais soyez prudent : les composants dont l’apparence varie selon si oui ou non ils ont un certain parent composant peuvent s’en retrouver difficile à débugger.

Les styles délimités devraient être utilisés aussi souvent que possible. Les styles globaux devraient être utilisés seulement quand c’est nécessaire.

La balise <style> d’Astro peut référencer n’importe quelle variable CSS disponible sur la page. Vous pouvez aussi passer des variables CSS directement depuis le frontmatter de votre composant en utilisant la directive define:vars.

---
const foregroundColor = "rgb(221 243 228)";
const backgroundColor = "rgb(24 121 78)";
---
<style define:vars={{ foregroundColor, backgroundColor }}>
  h1 {
    background-color: var(--backgroundColor);
    color: var(--foregroundColor);
  }
</style>
<h1>Bonjour</h1>

📚 Allez voir notre page de référence des directives pour en savoir plus sur define:vars.

Il y a deux façons d’avoir accès à des feuilles de styles globales externes : un import ESM pour les fichiers situés dans le code source de votre projet, et un lien absolu pour les fichiers dans le répertoire public/ ou hébergés en dehors de votre projet.

📚 En savoir plus sur l’utilisation des ressources statiques situées dans public/ ou src/.

⚠️ Vous auriez surement besoin de mettre à jour votre fichier astro.config lorsque vous importez des feuilles de styles depuis des Packages NPM. Voir la section “Importer une feuille de styles depuis un Package npm” ci-dessous.

Vous pouvez importer des feuilles de styles dans le Frontmatter de votre composant Astro en utilisant la syntaxe d’import ESM. Les imports CSS fonctionnent comme tous les autres imports ESM dans un composant Astro, devrait être référencés comme relatifs au composant et être écrits en haut de votre Script de composant, comme toutes les autres importations de ce type.

---
// Astro va automatiquement fusionner et optimiser ce CSS pour vous
// Cela fonctionne aussi pour des fichiers préprocesseurs comme .scss, .styl, etc.
import '../styles/utils.css';
---
<html><!-- Votre page ici --></html>

Les imports CSS via ESM sont supportés dans n’importe quel fichier JavaScript, y compris dans les composants JSX comme React & Preact. Cela peut être utile pour écrire des styles granulaires, par composant, pour vos composants React.

Vous pourriez avoir besoin de charger une feuille de styles depuis un Package NPM. C’est particulièrement utile pour des utilitaires comme Open Props. Si votre Package recommende d’utiliser une extension de fichier (comme package-name/styles.css au lieu de package-name/styles), cela devrait fonctionner comme une feuille de styles locale :

---
import 'package-name/styles.css';
---
<html><!-- Votre page juste ici --></html>

Si votre Package ne recommande pas d’utiliser une extension de fichier (tel que package-name/styles), vous devrez d’abord mettre à jour votre fichier de configuration d’Astro !

Imaginons que vous importez un fichier CSS depuis package-name appelé normalize (et sans l’extension de fichier). Pour s’assurer que nous pouvons afficher votre page correctement, ajoutez package-name à la liste vite.ssr.noExternal.

import { defineConfig } from 'astro/config';
export default defineConfig({
  vite: {
    ssr: {
      noExternal: ['package-name'],
    }
  }
})

Note : Cette option est spécifique à Vite et n’a aucun rapport (ou dépendance) avec le mode SSR d’Astro.

Maintenant, vous êtes libre d’importer package-name/normalize. Il sera intégré et optimisé par Astro comme toutes les autres feuilles de styles locales.

---
import 'package-name/normalize';
---
<html><!-- Votre page juste ici --></html>

Vous pouvez aussi utiliser l’élément <link> pour charger une feuille de styles sur la page. Pour cela, utiliser un chemin absolu vers un fichier CSS situé dans le répertoire /public, ou une URL vers un site web externe. Les valeurs relative “href” sur les balises <link> ne sont pas supportées.

<head>
  <!-- En local: /public/styles/global.css -->
  <link rel="stylesheet" href="/styles/global.css" />
  <!-- Externe  -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.24.1/themes/prism-tomorrow.css">
</head>

Étant donné que cette approche utilise le répertoire public/, Astro n’appliquera ni transformations CSS, ni fusion, optimisation. Si vous avez besoin de ces transformations, utilisez la méthode d’importation une feuille de styles ci-dessus.

Astro fournit le support pour ajouter les bibliothèques CSS populaires, les outils et les frameworks de votre projet comme Tailwind et plus encore !

📚 Consultez le Guide d’intégrations pour les instructions d’installation, d’importation et de configuration de ces intégrations.

Astro supporte les préprocesseurs CSS comme Sass, Stylus, et Less via Vite.

npm install -D sass

Utilisez <style lang="scss"> ou <style lang="sass"> dans les fichiers .astro.

npm install -D stylus

Utilisez <style lang="styl"> ou <style lang="stylus"> dans les fichiers .astro.

npm install -D less

Utilisez <style lang="less"> dans les fichiers .astro.

Vous pouvez aussi utiliser tous les préprocesseurs CSS ci-dessus aussi bien dans les frameworks JS que dans d’autres! Assurez-vous de suivre les patterns recommandés par chacun des frameworks :

• React / Preact: import Styles from './styles.module.scss';
• Vue: <style lang="scss">
• Svelte: <style lang="scss">

Astro intégres PostCSS par défaut, de par avec Vite. Pour configurer PostCSS pour votre projet, créez un fichier postcss.config.js dans le répertoire racine de votre projet. Vous pouvez importer des plugins en utilisant require().

module.exports = {
  plugins: [
    require('postcss-preset-env'),
    require('autoprefixer'),
  ],
};

Les fichiers .jsx supportent aussi les CSS globaux et les modules CSS. Pour activer le dernier, utilisez l’extension .module.css (ou .module.scss/scss si vous utilisez Sass).

import './global.css'; // inclus du CSS global
import Styles from './styles.module.css'; // Utilise les modules CSS (doit se terminer par `.module.css`, `.module.scss`, ou `.module.sass`!)

Vue Astro supporte les mêmes méthodes que vue-loader :

• vue-loader - CSS Portés
• vue-loader - Modules CSS

Svelte fonctionne aussi à la perfection dans Astro : Documentation de Style sur Svelte.

Toutes les méthodes de stylisme Astro sont disponibles pour un composant de mise en page Markdown.

Vous pouvez appliquer des styles globaux à votre contenu Markdown en ajoutant des balises <style> et des feuilles de style importées à la mise en page qui englobe le contenu de votre page. Vous pouvez également ajouter des intégrations CSS, notamment Tailwind (EN).

Si vous utilisez Tailwind, le plugin de typographie peut être utile pour styliser le Markdown.

⚠️ATTENTION⚠️ : Soyez vigilant lorsque vous ignorez la compression du CSS intégré à Astro. Les styles ne seront pas automatiquement inclus dans le code généré, et votre responsabilité de vous assurer que le fichier référencé est bien inclus dans la sortie finale.

Pour certain cas spécifiques, il est possible d’importer directement du CSS depuis le disque sans qu’il soit compressé ou optimisé par Astro. Cela peut être utile lorsque vous avez besoin d’un contrôle total sur votre CSS, et que vous avez besoin d’ignorer le traitement automatique du CSS par Astro.

Ceci n’est pas recommandé pour la plupart des utilisateurs.

---
// Exemple avancé ! Non-recommandé pour la plupart des utilisateurs.
import rawStylesCSS from '../styles/main.css?raw';
---
<style is:inline set:html={rawStylesCSS}></style>

Voir la documentation de Vite pour plus de détails.

Dans certain cas spécifiques, vous pouvez importer une référence URL directe pour un fichier CSS dans le répertoire src/ de votre projet. Cela peut être utile lorsque vous avez besoin d’un contrôle total sur la manière dont un fichier CSS est chargé sur la page. Cependant, cela empêchera la compression de ce fichier avec les autres styles de votre page.

Ceci n’est pas recommandé pour la plupart des utilisateurs. À la place, mettez vos fichiers CSS dans le dossier public/ pour obtenir une référence URL consistente.

⚠️ATTENTION⚠️ : Importer un fichier CSS minime avec ?url peut renvoyer son contenus CSS encodés en base64 en temps qu’URL, mais uniquement en production. Vous devrez écrire votre code pour supporter les URL de données (data:text/css;base64,...) ou alors définir l’option vite.build.assetsInlineLimit à 0 pour désactiver cette fonctionnalité.

---
// Exemple avancé ! Non-recommandé pour la plupart des utilisateurs.
import stylesUrl from '../styles/main.css?url';
---
<link rel="preload" href={stylesUrl} as="style">
<link rel="stylesheet" href={stylesUrl}>

Voir la documentation de Vite pour plus de détails.