Le hook useOptimistic de React : interface instantanée

useOptimistic est un hook de React 19 qui permet à l'écran d'afficher le résultat d'une action avant qu'elle se termine. Vous définissez une valeur optimiste dans une action ; React l'affiche tant que l'action est en attente, puis revient à l'état réel. Si la requête a échoué, l'état réel n'a jamais changé, donc l'écran revient en arrière tout seul.

La fausse API de cet exemple remplace une vraie requête et échoue un appel sur trois, pour que vous puissiez voir les deux issues.

import { startTransition, useOptimistic, useState } from 'react';

let calls = 0;
function saveLike(liked) {
    // Stands in for a real request. Every third call fails.
    calls += 1;
    const fails = calls % 3 === 0;
    return new Promise((resolve, reject) =>
        setTimeout(() => (fails ? reject(new Error('Network error')) : resolve(liked)), 1000),
    );
}

export default function App() {
    const [liked, setLiked] = useState(false);
    const [optimisticLiked, setOptimisticLiked] = useOptimistic(liked);
    const [error, setError] = useState('');

    function toggle() {
        const next = !optimisticLiked;
        setError('');
        startTransition(async () => {
            setOptimisticLiked(next);
            try {
                await saveLike(next);
                startTransition(() => setLiked(next));
            } catch (e) {
                setError(`${e.message}, so the change was undone.`);
            }
        });
    }

    return (
        <div>
            <button onClick={toggle}>{optimisticLiked ? 'Liked' : 'Like'}</button>
            <p style={{ color: '#666' }}>Saved on the server: {liked ? 'liked' : 'not liked'}</p>
            {error && <p style={{ color: 'crimson' }}>{error}</p>}
        </div>
    );
}

Cliquez trois fois sur le bouton, en attendant une seconde entre les clics. Les deux premiers basculent tout de suite et la ligne enregistrée suit une seconde plus tard. Le troisième bascule aussi tout de suite, puis revient en arrière quand la requête échoue. Remplacez calls % 3 par calls % 2 et un clic sur deux échoue.

La syntaxe

const [optimisticState, setOptimistic] = useOptimistic(state, updateFn?);

• state est la vraie valeur, généralement issue de useState, des props ou de useActionState. Quand aucune action n'est en attente, optimisticState est exactement cette valeur.
• setOptimistic(value) définit la valeur optimiste pour toute la durée de l'action en cours.
• updateFn est facultatif : (currentState, optimisticValue) => nextState. Avec lui, setOptimistic reçoit un changement plutôt qu'une valeur entièrement nouvelle. Voir la forme reducer plus bas.

Le cycle de vie d'un clic est toujours le même :

1. Dans une action, vous appelez setOptimistic. L'écran se met à jour tout de suite.
2. L'action attend la requête.
3. En cas de succès, vous mettez à jour l'état réel (dans startTransition quand cela vient après un await).
4. L'action se termine. optimisticState suit à nouveau state : la valeur enregistrée en cas de succès, l'ancienne valeur en cas d'échec.

L'étape 4 explique pourquoi il n'y a aucun code de retour en arrière dans l'exemple. Le bloc catch ne fait que définir un message d'erreur.

Il doit s'exécuter dans une action

La valeur optimiste n'existe que pendant qu'une transition est en attente, donc setOptimistic doit être appelé dans une transition. Tous ces cas comptent :

• la fonction que vous passez à startTransition (ou au startTransition de useTransition),
• une fonction passée à <form action={...}> ou <button formAction={...}>,
• l'action que vous donnez à useActionState.

Appelée depuis un simple onClick, la valeur optimiste n'a pas d'action dans laquelle vivre. React l'annule aussitôt, et en développement React affiche "An optimistic state update occurred outside a transition or action".

Les mises à jour de l'état réel qui ont lieu après un await doivent être enveloppées dans leur propre startTransition, comme startTransition(() => setLiked(next)) ci-dessus. Après un await, React ne peut pas savoir que vous êtes toujours dans la transition précédente.

Une liste de messages avec la forme reducer

Quand l'état optimiste est une liste, passez une fonction de mise à jour en second argument. Le setter reçoit alors le nouvel élément, et React l'ajoute à ce qu'est la vraie liste à ce moment-là.

import { startTransition, useOptimistic, useState } from 'react';

let calls = 0;
function deliver(text) {
    // Stands in for a real request. Every third message fails.
    calls += 1;
    const id = calls;
    const fails = id % 3 === 0;
    return new Promise((resolve, reject) =>
        setTimeout(() => (fails ? reject(new Error('failed')) : resolve({ id, text })), 1200),
    );
}

export default function App() {
    const [messages, setMessages] = useState([{ id: 0, text: 'Hi there' }]);
    const [failed, setFailed] = useState([]);
    const [optimisticMessages, addOptimistic] = useOptimistic(messages, (current, text) => [
        ...current,
        { id: `pending-${text}`, text, sending: true },
    ]);

    async function send(formData) {
        const text = formData.get('text');
        addOptimistic(text);
        try {
            const saved = await deliver(text);
            startTransition(() => setMessages((list) => [...list, saved]));
        } catch {
            setFailed((list) => [...list, text]);
        }
    }

    return (
        <div>
            {optimisticMessages.map((m) => (
                <p key={m.id} style={{ margin: '4px 0', opacity: m.sending ? 0.5 : 1 }}>
                    {m.text} {m.sending && <small>(sending...)</small>}
                </p>
            ))}
            {failed.map((text, i) => (
                <p key={i} style={{ color: 'crimson', margin: '4px 0' }}>Not sent: {text}</p>
            ))}
            <form action={send}>
                <input name="text" defaultValue="Hello" />
                <button type="submit">Send</button>
            </form>
        </div>
    );
}

Envoyez trois messages avec des textes différents, un par un. Chacun apparaît estompé avec "(sending...)" et devient net une fois livré ; le troisième disparaît du chat et apparaît comme "Not sent". Envoyez-les plutôt rapidement et les trois restent estompés jusqu'à la fin de la dernière requête, car React garde les valeurs optimistes jusqu'à ce que toutes les actions en attente soient terminées. L'action de formulaire est déjà une transition, donc addOptimistic n'a pas besoin ici de son propre startTransition.

Donnez à chaque élément optimiste une key qui n'entrera pas en conflit avec les vrais éléments. L'exemple utilise pending- suivi du texte, donc envoyer deux fois le même texte pendant que les deux sont en attente provoquerait un conflit ; une vraie application créerait un identifiant côté client.

Plusieurs mises à jour à la fois

Comme la fonction de mise à jour reçoit l'état actuel, les mises à jour optimistes s'empilent. Cliquez rapidement et chaque clic en attente s'applique par-dessus le précédent.

import { startTransition, useOptimistic, useState } from 'react';

let calls = 0;
function addToCart() {
    // Stands in for a real request. Every third call fails.
    calls += 1;
    const fails = calls % 3 === 0;
    return new Promise((resolve, reject) => setTimeout(() => (fails ? reject(new Error()) : resolve()), 1500));
}

export default function App() {
    const [count, setCount] = useState(0);
    const [optimisticCount, addOptimistic] = useOptimistic(count, (current, delta) => current + delta);

    function handleClick() {
        startTransition(async () => {
            addOptimistic(1);
            try {
                await addToCart();
                startTransition(() => setCount((c) => c + 1));
            } catch {
                console.log('one request failed');
            }
        });
    }

    return (
        <div>
            <button onClick={handleClick}>Add to cart</button>
            <p>In cart: {optimisticCount}</p>
            <p style={{ color: '#666' }}>Confirmed: {count}</p>
        </div>
    );
}

Cliquez quatre fois rapidement. Le panier affiche 4 tout de suite. Quand les requêtes se terminent, le compteur se stabilise à 3, car la troisième requête a échoué et la console le signale. React garde les valeurs optimistes jusqu'à ce que toutes les actions en attente soient terminées, puis affiche le vrai compteur.

Quand l'utiliser, et quand l'éviter

Les mises à jour optimistes conviennent aux actions qui réussissent presque toujours et sont faciles à annuler : likes, étoiles, bascules, renommage, ajout d'un message. Dans le cas courant, l'utilisateur ne voit aucun spinner.

Évitez-les là où un faux « c'est fait » induirait en erreur : paiements, suppression d'un compte, tout ce sur quoi l'utilisateur pourrait agir avant de connaître le résultat. Dans ces cas, affichez un état d'attente avec isPending issu de useActionState ou de useTransition et attendez la vraie réponse.

Prévenez toujours l'utilisateur quand un retour en arrière a lieu. Une valeur qui revient en arrière sans bruit ressemble à un bug. Les deux exemples ci-dessus gardent un message d'erreur dans un état ordinaire pour qu'il survive à l'action.

Avec useActionState

useOptimistic et useActionState s'accordent bien. L'action de useActionState est déjà une transition, vous pouvez donc définir la valeur optimiste au début de celle-ci, et l'état renvoyé est la vraie valeur sur laquelle la valeur optimiste se rabat.

const [state, formAction] = useActionState(async (previous, formData) => {
    const title = formData.get('title');
    setOptimisticTitle(title);
    const saved = await saveTitle(title);
    return { title: saved.title };
}, { title: 'Untitled' });

const [optimisticTitle, setOptimisticTitle] = useOptimistic(state.title);

Pendant l'enregistrement, la page affiche le nouveau titre. Quand il se résout, state.title contient la valeur enregistrée. Si saveTitle lève une erreur, l'erreur de l'action va à l'error boundary la plus proche ; pour afficher plutôt l'ancien titre avec un message, interceptez l'erreur dans l'action et renvoyez l'état précédent avec une erreur.

Erreurs courantes

Appeler le setter en dehors d'une action. La valeur optimiste ne reste pas à l'écran, et React avertit en développement. Enveloppez l'appel dans startTransition ou déplacez-le dans une action de formulaire.

Oublier de mettre à jour l'état réel. En cas de succès, l'action doit modifier l'état que useOptimistic reflète (setLiked, setMessages). Sinon, la valeur optimiste disparaît à la fin de l'action, et une requête réussie ressemble à un retour en arrière.

Mettre à jour l'état réel après un await sans transition. La mise à jour a bien lieu, mais React peut l'afficher à un autre moment que la fin de l'action. Enveloppez-la dans startTransition, comme le font les trois exemples.

Utiliser la valeur optimiste comme source de vérité. Envoyez les requêtes et calculez les totaux à partir de l'état réel. La valeur optimiste ne sert qu'à l'affichage et peut être jetée à tout moment.