Section courante

A propos

Section administrative du site

useInsertionEffect

 Utilise un effet d'insertion
React

Piège : useInsertionEffect est destiné aux créateurs de bibliothèques CSS-in-JS. À moins que vous ne travailliez sur une bibliothèque CSS-in-JS et que vous ayez besoin d'un emplacement pour injecter les styles, vous préférerez probablement useEffect ou useLayoutEffect.

useInsertionEffect(setup, dependencies?)

Description

useInsertionEffect permet d'insérer des éléments dans le DOM avant le déclenchement des effets de mise en page.

Référence

useInsertionEffect( , dependencies?)

Appelez useInsertionEffect pour insérer des styles avant le déclenchement de tout effet pouvant nécessiter la lecture de la mise en page :

  1. import { useInsertionEffect } from 'react';
  2.  
  3. // À l'intérieur de votre bibliothèque CSS-in-JS
  4. function useCSS(rule) {
  5.   useInsertionEffect(() => {
  6.     // ... injecter les balises <style> ici ...
  7.   });
  8.   return rule;
  9. }

Paramètres

Nom Description
setup La fonction contenant la logique de votre effet. Votre fonction de configuration peut également renvoyer une fonction de nettoyage (optionnelle). Lorsque votre composant est ajouté au DOM, mais avant le déclenchement de tout effet de mise en page, React exécute votre fonction de configuration. Après chaque rendu avec des dépendances modifiées, React exécute d'abord la fonction de nettoyage (si vous l'avez fournie) avec les anciennes valeurs, puis la fonction de configuration avec les nouvelles valeurs. Lorsque votre composant est supprimé du DOM, React exécute la fonction de nettoyage.
dependencies optionnelles : La liste de toutes les valeurs réactives référencées dans le code de configuration. Les valeurs réactives incluent les propriétés, l'état et toutes les variables et fonctions déclarées directement dans le corps de votre composant. Si votre linter est configuré pour React, il vérifie que chaque valeur réactive est correctement spécifiée comme dépendance. La liste des dépendances doit comporter un nombre constant d'éléments et être écrite en ligne, comme [dep1, dep2, dep3]. React compare chaque dépendance à sa valeur précédente grâce à l'algorithme de comparaison Object.is. Si vous ne spécifiez pas du tout les dépendances, votre effet sera réexécuté après chaque nouveau rendu du composante.

Renvoie

useInsertionEffect renvoie undefined.

Avertissements

Utilisation

Injection de styles dynamiques à partir de bibliothèques CSS-in-JS

Traditionnellement, le style des composantes React est appliqué en CSS brut.

  1. // Dans votre fichier JS :
  2. <button className="success" />
  3.      </code>
  4.      et:
  5.      <code>
  6. // Dans votre fichier CSS :
  7. .success { color: green; }

Certaines équipes préfèrent créer des styles directement dans le code JavaScript plutôt que d'écrire des fichiers CSS. Cela nécessite généralement l'utilisation d'une bibliothèque ou d'un outil CSS-in-JS. Il existe trois approches courantes pour CSS-in-JS :

Si vous utilisez CSS-in-JS, nous recommandons une combinaison des deux premières approches (fichiers CSS pour les styles statiques, styles en ligne pour les styles dynamiques). Nous déconseillons l'injection de balises <style> à l'exécution pour deux raisons :

Appelez useInsertionEffect pour insérer les styles avant tout effet de mise en page :

  1. // À l'intérieur de votre bibliothèque CSS-in-JS
  2. let isInserted = new Set();
  3. function useCSS(rule) {
  4.   useInsertionEffect(() => {
  5.     // Comme expliqué précédemment, nous ne recommandons pas l'injection d'exécution de balises <style>.
  6.     // Mais si vous devez le faire, il est important de le faire dans useInsertionEffect.
  7.     if (!isInserted.has(rule)) {
  8.       isInserted.add(rule);
  9.       document.head.appendChild(getStyleForRule(rule));
  10.     }
  11.   });
  12.   return rule;
  13. }
  14.  
  15. function Button() {
  16.   const className = useCSS('...');
  17.   return <div className={className} />;
  18. }

Tout comme useEffect, useInsertionEffect ne s'exécute pas sur le serveur. Si vous souhaitez collecter les règles CSS utilisées sur le serveur, vous pouvez le faire pendant le rendu :

  1. let collectedRulesSet = new Set();
  2.  
  3. function useCSS(rule) {
  4.   if (typeof window === 'undefined') {
  5.     collectedRulesSet.add(rule);
  6.   }
  7.   useInsertionEffect(() => {
  8.     // ...
  9.   });
  10.   return rule;
  11. }     

Dernière mise à jour : Mercredi, le 10 septembre 2025