Manipuler le DOM avec des refs

Obtenir une ref vers le nœud

Pour accéder à un nœud DOM géré par React, commencez par importer le Hook useRef :

import { useRef } from 'react';

Utilisez-le alors pour déclarer une ref dans votre composant :

const myRef = useRef(null);

Enfin, passez la ref à la prop ref de l’élément JSX dont vous souhaitez référencer le nœud DOM :

<div ref={myRef}>

Le Hook useRef renvoie un objet avec une unique propriété current. Initialement, myRef.current vaudra null. Lorsque React créera un nœud DOM pour le <div>, React placera une référence à ce nœud dans myRef.current. Vous pourrez accéder à ce nœud DOM depuis vos gestionnaires d’événements et utiliser les API navigateur qu’il propose.

// Vous pouvez utiliser n’importe quelle API navigateur, par exemple :
myRef.current.scrollIntoView();

Exemple : donner le focus à un champ

Dans cet exemple, cliquer sur le bouton donnera le focus au champ de saisie :

Pour implémenter ça :

1. Déclarez inputRef avec le Hook useRef.
2. Passez-la dans <input ref={inputRef}>. Ça indique à React de mettre une référence au nœud DOM de ce <input> dans inputRef.current.
3. Dans la fonction handleClick, lisez la référence au nœud DOM depuis inputRef.current et appelez sa méthode focus() avec inputRef.current.focus().
4. Passez le gestionnaire d’événement handleClick à la prop onClick du <button>.

Même si la manipulation du DOM constitue l’essentiel des cas d’usage pour les refs, le Hook useRef peut être utilisé pour stocker d’autres données externes à React, par exemple des ID de timers. Tout comme les variables d’état, les refs sont préservées d’un rendu à l’autre. Elles agissent un peu comme des variables d’état qui ne redéclenchent par un rendu lorsque vous les modifiez. Apprenez-en davantage sur les refs dans Référencer des valeurs avec les refs.

Exemple : défiler jusqu’à un élément

Vous pouvez avoir plus d’une ref dans un même composant. Dans l’exemple qui suit, on affiche un carrousel de trois images. Chaque bouton centre une image en appelant la méthode native scrollIntoView() sur le nœud DOM correspondant :

<ul>
  {items.map((item) => {
    // Ne marche pas !
    const ref = useRef(null);
    return <li ref={ref} />;
  })}
</ul>

import { useRef } from 'react';

export default function CatFriends() {
  const itemsRef = useRef(null);

  function scrollToId(itemId) {
    const map = getMap();
    const node = map.get(itemId);
    node.scrollIntoView({
      behavior: 'smooth',
      block: 'nearest',
      inline: 'center'
    });
  }

  function getMap() {
    if (!itemsRef.current) {
      // Initialise la Map à la première utilisation
      itemsRef.current = new Map();
    }
    return itemsRef.current;
  }

  return (
    <>
      <nav>
        <button onClick={() => scrollToId(0)}>
          Tom
        </button>
        <button onClick={() => scrollToId(5)}>
          Maru
        </button>
        <button onClick={() => scrollToId(9)}>
          Jellylorum
        </button>
      </nav>
      <div>
        <ul>
          {catList.map(cat => (
            <li
              key={cat.id}
              ref={(node) => {
                const map = getMap();
                if (node) {
                  map.set(cat.id, node);
                } else {
                  map.delete(cat.id);
                }
              }}
            >
              <img
                src={cat.imageUrl}
                alt={'Chat #' + cat.id}
              />
            </li>
          ))}
        </ul>
      </div>
    </>
  );
}

const catList = [];
for (let i = 0; i < 10; i++) {
  catList.push({
    id: i,
    imageUrl: 'https://placekitten.com/250/200?image=' + i
  });
}

<li
  key={cat.id}
  ref={node => {
    const map = getMap();
    if (node) {
      // Ajoute à la Map
      map.set(cat.id, node);
    } else {
      // Retire de la Map
      map.delete(cat.id);
    }
  }}
>

Accéder aux nœuds DOM d’un autre composant

Quand vous posez une ref sur un composant natif qui produit un élément navigateur tel que <input />, React place une référence vers le nœud DOM correspondant (le véritable élément <input /> du navigateur) dans la propriété current de cette ref.

En revanche, si vous essayez d’obtenir une ref vers votre propre composant, tel que <MyInput />, vous obtiendrez par défaut null. Voici un exemple qui illustre ça : voyez comme les clics sur le bouton ne donnent pas le focus au champ de saisie :

Pour vous aider à repérer le problème, React affichera aussi une erreur dans la console :

(« Attention : les fonctions composants ne peuvent pas recevoir de refs. Toute tentative d’accéder à cette ref échouera. Vouliez-vous utiliser React.forwardRef() ? », NdT)

Le souci vient du fait que par défaut, React ne permet pas aux composants d’accéder aux nœuds DOM d’autre composants. Même pas pour ses propres enfants ! C’est parfaitement voulu. Les refs sont une échappatoire à utiliser avec parcimonie. Manipuler manuellement les nœuds DOM d’un autre composant rend votre code encore plus fragile.

Les composants qui veulent exposer leurs nœuds DOM doivent plutôt choisir un tel comportement. Un composant peut indiquer qu’il « transmettra » sa ref à un de ses enfants. Voici comment MyInput peut utiliser l’API forwardRef :

const MyInput = forwardRef((props, ref) => {
  return <input {...props} ref={ref} />;
});

Voici comment ça fonctionne :

1. <MyInput ref={inputRef} /> indique à React qu’il doit placer le nœud DOM correspondant dans inputRef.current. Ceci dit, c’est au composant MyInput qu’il appartient d’accepter ce comportement : par défaut, ce ne sera pas le cas.
2. Le composant MyInput est déclaré en utilisant forwardRef. Il choisit de recevoir la inputRef ci-avant comme second argument ref de la fonction, déclaré après le premier argument props.
3. MyInput transmettra lui-même la ref reçue à l’<input> qu’il contient.

À présent, cliquer sur le bouton active bien le champ :

Dans les Design Systems, il est courant pour les composants de bas niveau tels que les boutons, champs, etc. de transmettre leurs refs à leurs nœuds DOM. À l’inverse, les composants de haut niveau tels que les formulaires, listes ou sections de page n’exposent généralement pas leurs nœuds DOM pour éviter d’introduire des dépendances indésirables envers la structure de leur DOM.

import {
  forwardRef,
  useRef,
  useImperativeHandle
} from 'react';

const MyInput = forwardRef((props, ref) => {
  const realInputRef = useRef(null);
  useImperativeHandle(ref, () => ({
    // N'expose que la méthode `focus()`, rien de plus
    focus() {
      realInputRef.current.focus();
    },
  }));
  return <input {...props} ref={realInputRef} />;
});

export default function Form() {
  const inputRef = useRef(null);

  function handleClick() {
    inputRef.current.focus();
  }

  return (
    <>
      <MyInput ref={inputRef} />
      <button onClick={handleClick}>
        Activer le champ
      </button>
    </>
  );
}

Quand React associe-t-il les refs ?

Dans React, chaque mise à jour est découpée en deux phases :

• Pendant le rendu, React appelle vos composants pour déterminer quoi afficher à l’écran.
• Pendant le commit, React applique ces modifications au DOM.

En général, vous ne voulez pas accéder aux refs lors du rendu. Ça vaut aussi pour les refs à des nœuds DOM. Lors du premier rendu, les nœuds DOM n’ont pas encore été créés, de sorte que ref.current sera null. Et lors des rendus de mise à jour, les nœuds DOM n’auront pas encore été mis à jour, de sorte qu’il sera trop tôt pour les exploiter.

React met à jour ref.current lors de la phase de commit. Avant de mettre à jour le DOM, React recale les valeurs ref.current à null. Après que le DOM a été mis à jour, React recale immédiatement les références vers les nœuds DOM correspondants.

En général, vous accéderez aux refs depuis des gestionnaires d’événements. Si vous voulez faire quelque chose avec une ref, mais qu’aucun événement particulier ne s’y prête, vous aurez peut-être besoin d’un Effet. Nous explorerons les Effets en détail dans les prochaines pages de ce chapitre.

import { useState, useRef } from 'react';

export default function TodoList() {
  const listRef = useRef(null);
  const [text, setText] = useState('');
  const [todos, setTodos] = useState(
    initialTodos
  );

  function handleAdd() {
    const newTodo = { id: nextId++, text: text };
    setText('');
    setTodos([ ...todos, newTodo]);
    listRef.current.lastChild.scrollIntoView({
      behavior: 'smooth',
      block: 'nearest'
    });
  }

  return (
    <>
      <button onClick={handleAdd}>
        Ajouter
      </button>
      <input
        value={text}
        onChange={e => setText(e.target.value)}
      />
      <ul ref={listRef}>
        {todos.map(todo => (
          <li key={todo.id}>{todo.text}</li>
        ))}
      </ul>
    </>
  );
}

let nextId = 0;
let initialTodos = [];
for (let i = 0; i < 20; i++) {
  initialTodos.push({
    id: nextId++,
    text: 'Tâche #' + (i + 1)
  });
}

setTodos([ ...todos, newTodo]);
listRef.current.lastChild.scrollIntoView();

flushSync(() => {
  setTodos([ ...todos, newTodo]);
});
listRef.current.lastChild.scrollIntoView();

import { useState, useRef } from 'react';
import { flushSync } from 'react-dom';

export default function TodoList() {
  const listRef = useRef(null);
  const [text, setText] = useState('');
  const [todos, setTodos] = useState(
    initialTodos
  );

  function handleAdd() {
    const newTodo = { id: nextId++, text: text };
    flushSync(() => {
      setText('');
      setTodos([ ...todos, newTodo]);
    });
    listRef.current.lastChild.scrollIntoView({
      behavior: 'smooth',
      block: 'nearest'
    });
  }

  return (
    <>
      <button onClick={handleAdd}>
        Ajouter
      </button>
      <input
        value={text}
        onChange={e => setText(e.target.value)}
      />
      <ul ref={listRef}>
        {todos.map(todo => (
          <li key={todo.id}>{todo.text}</li>
        ))}
      </ul>
    </>
  );
}

let nextId = 0;
let initialTodos = [];
for (let i = 0; i < 20; i++) {
  initialTodos.push({
    id: nextId++,
    text: 'Tâche #' + (i + 1)
  });
}

Meilleures pratiques pour la manipulation du DOM avec les refs

Les refs sont une échappatoire. Vous ne devriez y recourir que lorsque vous devez « sortir de React ». Les exemples les plus courants incluent la gestion du focus, la position de défilement ou l’appel d’API navigateur que React n’expose pas directement.

Si vous vous en tenez à des actions non destructrices comme le focus ou le défilement, vous ne devriez rencontrer aucun problème. En revanche, si vous tentez de modifier le DOM manuellement, vous risquez d’entrer en conflit avec les modifications effectuées par React.

Pour illustrer le problème, l’exemple ci-dessous inclut un message de bienvenue et deux boutons. Le premier bouton contrôle la présence du bouton au moyen d’un rendu conditionnel et d’une variable d’état, comme vous le feriez habituellement avec React. Le second bouton utilise l’API DOM remove() pour retirer de force le message du DOM, hors du contrôle de React.

Tentez de presser « Basculer avec React » quelques fois. Le message devrait disparaître, réapparaître, et ainsi de suite. Pressez ensuite « Retirer du DOM ». Ça va forcer son retrait. Pour finir, pressez à nouveau « Basculer avec React » :

Après que vous avez manuellement retiré l’élément du DOM, tentez d’utiliser setState pour l’afficher à nouveau : ça plantera l’appli. C’est parce que vous modifié le DOM, et React ne sait plus comment continuer à le gérer correctement.

Évitez de modifier les nœuds DOM gérés par React. Modifier, retirer ou ajouter du contenu aux éléments gérés par React peut entraîner des états visuels incohérents voire des plantages comme dans l’exemple ci-avant.

Ceci étant dit, ça ne signifie pas que l’interdiction est absolue. Il faut juste faire preuve de prudence. Vous pouvez modifier en confiance les parties du DOM que React n’a aucune raison de mettre à jour. Par exemple, si un <div> est toujours vide au niveau JSX, React n’aura aucune raison de toucher à sa liste d’enfants : il est donc concevable d’ajouter ou retirer manuellement du contenu à cet endroit-là.