Le hook useRef de React : refs DOM et valeurs persistantes

useRef renvoie un objet, { current: initialValue }, que React conserve pendant toute la vie du composant. Modifier ref.current ne provoque aucun nouveau rendu. Les refs conviennent donc à deux tâches : détenir un nœud DOM pour appeler des méthodes comme focus() dessus, et mémoriser d'un rendu à l'autre une valeur que l'écran n'a pas besoin d'afficher.

import { useRef } from 'react';

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

    function handleClick() {
        inputRef.current.focus();
        console.log('focused:', inputRef.current.tagName);
    }

    return (
        <div>
            <input ref={inputRef} placeholder="Click the button" />{' '}
            <button onClick={handleClick}>Focus the input</button>
        </div>
    );
}

Passer l'objet ref à ref={inputRef} indique à React de placer le nœud DOM <input> dans inputRef.current. Remplacez focus() par select(), tapez quelque chose et cliquez à nouveau : le texte est surligné.

La syntaxe

const myRef = useRef(initialValue);

myRef.current;          // read
myRef.current = value;  // write, no re-render

• initialValue n'est utilisée qu'au premier rendu. Pour les refs DOM, elle vaut null.
• React renvoie le même objet à chaque rendu. Seul current change.
• Lire et écrire current relève du JavaScript ordinaire. React ne le suit pas.

Une valeur qui ne provoque pas de rendu

L'état sert à ce que l'écran affiche. Une ref sert à ce dont le composant doit se souvenir sans l'afficher. Ce bloc garde un compteur dans une ref et un autre dans l'état, et affiche les deux dans la console :

import { useRef, useState } from 'react';

export default function App() {
    const clicks = useRef(0);
    const [renders, setRenders] = useState(0);

    console.log('render: ref =', clicks.current, ', state =', renders);

    function addToRef() {
        clicks.current = clicks.current + 1;
        console.log('ref.current is now', clicks.current, '(no render)');
    }

    return (
        <div>
            <p>Ref counter: {clicks.current}</p>
            <p>State counter: {renders}</p>
            <button onClick={addToRef}>Ref + 1</button>{' '}
            <button onClick={() => setRenders(renders + 1)}>State + 1</button>
        </div>
    );
}

Cliquez plusieurs fois sur Ref + 1. La console montre ref.current qui augmente, mais la page affiche toujours 0 et aucun rendu n'est signalé. Cliquez maintenant sur State + 1 : le composant refait un rendu, et le compteur de la ref à l'écran saute au nombre que la ref contenait déjà. La ref a gardé sa valeur tout du long ; React n'avait simplement aucune raison de la dessiner.

Refs ou état

En cas de doute, demandez-vous si le JSX lit la valeur. Si oui, elle a sa place dans l'état.

Stocker un identifiant de minuteur

setInterval renvoie un identifiant dont vous avez besoin plus tard pour arrêter le minuteur. C'est un bon usage pour une ref : le gestionnaire Stop en a besoin, mais l'écran ne l'affiche jamais, et le garder dans une simple variable le perdrait au rendu suivant.

import { useRef, useState } from 'react';

export default function App() {
    const [seconds, setSeconds] = useState(0);
    const intervalRef = useRef(null);

    function start() {
        if (intervalRef.current !== null) return;
        intervalRef.current = setInterval(() => setSeconds((s) => s + 1), 1000);
        console.log('started timer', intervalRef.current);
    }

    function stop() {
        clearInterval(intervalRef.current);
        console.log('stopped timer', intervalRef.current);
        intervalRef.current = null;
    }

    return (
        <div>
            <p>{seconds} s</p>
            <button onClick={start}>Start</button>{' '}
            <button onClick={stop}>Stop</button>
        </div>
    );
}

Remplacez useRef(null) par let intervalRef = { current: null };, cliquez sur Start, attendez deux secondes, puis cliquez sur Stop : le minuteur continue. Chaque tic refait le rendu du composant, ce qui crée un nouvel objet, donc Stop n'arrête rien.

Mémoriser la valeur précédente

Un effet s'exécute après le rendu : il peut donc comparer la nouvelle valeur à celle stockée dans une ref, puis enregistrer la nouvelle pour la fois suivante :

import { useEffect, useRef, useState } from 'react';

export default function App() {
    const [color, setColor] = useState('red');
    const previous = useRef(null);

    useEffect(() => {
        if (previous.current !== null) {
            console.log('changed from', previous.current, 'to', color);
        }
        previous.current = color;
    }, [color]);

    return (
        <div>
            {['red', 'green', 'blue'].map((c) => (
                <button key={c} onClick={() => setColor(c)}>{c}</button>
            ))}
            <p style={{ color }}>The color is {color}</p>
        </div>
    );
}

Cliquez sur green, puis sur blue : la console affiche changed from red to green et changed from green to blue. Cliquer sur la couleur déjà sélectionnée n'affiche rien, car l'effet ne s'exécute que lorsque color change.

Travailler avec le DOM

Les refs permettent d'appeler les API du navigateur pour lesquelles React n'a pas de prop : focus(), select(), scrollIntoView(), play() sur une vidéo, ou lire une taille avec getBoundingClientRect().

const lastItemRef = useRef(null);

function scrollToLast() {
    lastItemRef.current.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
}

<li ref={lastItemRef}>Last item</li>

ref.current vaut null pendant le premier rendu, car React n'a pas encore créé le nœud DOM, et à nouveau après le retrait de l'élément. Lisez-le dans les gestionnaires d'événements et les effets, là où le nœud existe. Pour mesurer un élément et positionner quelque chose avant que le navigateur affiche la page, lisez la ref dans useLayoutEffect.

Ne lisez ni n'écrivez ref.current pendant le rendu

React attend que le corps du composant soit un calcul pur : mêmes props et même état, même JSX. Une ref change en dehors de ce modèle, donc un rendu qui la lit ou l'écrit peut afficher des résultats différents pour les mêmes entrées, et React peut appeler le corps plus souvent que vous ne le pensez.

function Bad() {
    const count = useRef(0);
    count.current++;              // writing during render
    return <p>{count.current}</p>; // reading during render
}

Lisez et écrivez les refs dans les gestionnaires d'événements et les effets. La seule exception est l'initialisation paresseuse, où vous remplissez la ref une seule fois au premier rendu :

const playerRef = useRef(null);
if (playerRef.current === null) {
    playerRef.current = new VideoPlayer(); // runs once
}

(La démo du compteur dans une ref ci-dessus lit volontairement clicks.current dans le JSX, pour montrer que l'écran ne la suit pas. Ne reproduisez pas cela dans du vrai code.)

Ref callbacks

Au lieu d'un objet ref, vous pouvez passer une fonction à ref. React l'appelle avec le nœud DOM quand l'élément est ajouté. Dans React 19, la fonction peut renvoyer un nettoyage, que React appelle quand l'élément est retiré. C'est pratique pour une liste, où vous ne pouvez pas appeler useRef une fois par élément :

import { useState } from 'react';

function trackNode(node) {
    console.log('attached', node.textContent);
    return () => console.log('detached', node.textContent);
}

export default function App() {
    const [items, setItems] = useState(['Apples', 'Bread', 'Cheese']);

    return (
        <div>
            <button onClick={() => setItems(items.slice(0, -1))}>Remove last</button>
            <ul>
                {items.map((item) => (
                    <li key={item} ref={trackNode}>{item}</li>
                ))}
            </ul>
        </div>
    );
}

Au chargement, la console affiche une ligne attached par élément. Cliquez sur Remove last et seul detached Cheese apparaît. trackNode est défini hors du composant, c'est donc la même fonction à chaque rendu et React laisse les autres éléments tranquilles. Écrivez-le inline sous la forme ref={(node) => { ... }} et chaque clic détache puis rattache tous les éléments, car chaque rendu passe une nouvelle fonction.

Passer une ref à votre propre composant

Dans React 19, ref est une prop ordinaire pour les composants fonctions. Le parent crée la ref, et l'enfant la place sur l'élément DOM qu'il veut exposer :

import { useRef } from 'react';

function SearchInput({ ref, ...props }) {
    return <input ref={ref} {...props} style={{ padding: 6 }} />;
}

export default function App() {
    const searchRef = useRef(null);

    return (
        <div>
            <SearchInput ref={searchRef} placeholder="Search" />{' '}
            <button onClick={() => searchRef.current.focus()}>Focus search</button>
        </div>
    );
}

Avant React 19, il fallait forwardRef, qui fonctionne toujours. La page sur forwardRef montre les deux versions et comment n'exposer que quelques méthodes avec useImperativeHandle.

Erreurs courantes

Afficher la valeur d'une ref dans le JSX. L'écran ne la suit pas. Si l'utilisateur doit voir la valeur, utilisez l'état.

Utiliser ref.current comme dépendance d'un effet. [ref.current] lit la valeur pendant le rendu et React ne sait pas quand elle change, donc l'effet ne se relance pas quand elle change. Utilisez une ref callback pour réagir au rattachement d'un nœud.

Lire une ref DOM pendant le premier rendu. Elle vaut null tant que React n'a pas créé le nœud. Lisez-la dans un effet ou un gestionnaire.

Créer un nouvel objet au lieu d'utiliser le hook. const ref = { current: null } dans le corps du composant est un nouvel objet à chaque rendu. Seul useRef vous donne le même à chaque fois.