L'hook useOptimistic di React: UI istantanea con ripristino

useOptimistic è un hook di React 19 che permette allo schermo di mostrare il risultato di un'azione prima che l'azione termini. Imposti un valore ottimistico dentro un'azione; React lo mostra mentre l'azione è in attesa, poi torna allo stato reale. Se la richiesta è fallita, lo stato reale non è mai cambiato, quindi lo schermo si ripristina da solo.

La finta API di questo esempio fa le veci di una richiesta reale e fallisce a ogni terza chiamata, così puoi vedere entrambi gli esiti.

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>
    );
}

Clicca il pulsante tre volte, aspettando un secondo tra un clic e l'altro. I primi due cambiano subito e la riga del salvataggio si allinea un secondo dopo. Anche il terzo cambia subito, poi torna indietro quando la richiesta fallisce. Cambia calls % 3 in calls % 2 e fallisce un clic ogni due.

La sintassi

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

• state è il valore reale, di solito da useState, dalle props o da useActionState. Quando nessuna azione è in attesa, optimisticState è esattamente questo valore.
• setOptimistic(value) imposta il valore ottimistico per tutto il tempo in cui l'azione attuale è in esecuzione.
• updateFn è facoltativa: (currentState, optimisticValue) => nextState. Con essa, setOptimistic riceve una modifica invece di un valore completamente nuovo. Vedi la forma con reducer qui sotto.

Il ciclo di vita di un clic è sempre lo stesso:

1. Dentro un'azione, chiami setOptimistic. Lo schermo si aggiorna subito.
2. L'azione attende la richiesta.
3. In caso di successo aggiorni lo stato reale (dentro startTransition quando avviene dopo un await).
4. L'azione termina. optimisticState torna a seguire state: il valore salvato in caso di successo, il vecchio valore in caso di errore.

Il passaggio 4 è il motivo per cui nell'esempio non c'è codice di ripristino. Il blocco catch imposta solo un messaggio di errore.

Deve essere eseguito dentro un'azione

Il valore ottimistico esiste solo mentre una transizione è in attesa, quindi setOptimistic deve essere chiamato dentro una transizione. Valgono tutti questi casi:

• la funzione che passi a startTransition (o allo startTransition di useTransition),
• una funzione passata a <form action={...}> o a <button formAction={...}>,
• l'azione che dai a useActionState.

Chiamato da un semplice onClick, il valore ottimistico non ha un'azione in cui vivere. React lo annulla subito, e in sviluppo registra "An optimistic state update occurred outside a transition or action".

Gli aggiornamenti dello stato reale che avvengono dopo un await vanno racchiusi nel loro startTransition, come startTransition(() => setLiked(next)) qui sopra. Dopo un await, React non riesce a capire che sei ancora dentro la transizione precedente.

Una lista di messaggi con la forma con reducer

Quando lo stato ottimistico è una lista, passa una funzione di aggiornamento come secondo argomento. Il setter riceve allora il nuovo elemento, e React lo aggiunge in fondo a qualunque sia la lista reale in quel momento.

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>
    );
}

Invia tre messaggi con testi diversi, uno alla volta. Ognuno compare attenuato con "(sending...)" e diventa pieno una volta consegnato; il terzo sparisce dalla chat e compare come "Not sent". Inviali invece rapidamente e tutti e tre restano attenuati finché l'ultima richiesta non termina, perché React mantiene i valori ottimistici finché ogni azione in attesa non è terminata. La form action è già una transizione, quindi qui addOptimistic non ha bisogno di un suo startTransition.

Dai a ogni elemento ottimistico una key che non entri in conflitto con gli elementi reali. L'esempio usa pending- più il testo, quindi inviare lo stesso testo due volte mentre entrambi sono in attesa creerebbe un conflitto; un'app reale creerebbe un id sul client.

Più aggiornamenti contemporaneamente

Poiché la funzione di aggiornamento riceve lo stato attuale, gli aggiornamenti ottimistici si sommano. Clicca rapidamente e ogni clic in attesa viene applicato sopra l'ultimo.

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>
    );
}

Clicca quattro volte velocemente. Il carrello mostra subito 4. Quando le richieste terminano, il conteggio si stabilizza su 3, perché la terza richiesta è fallita e la console lo dice. React mantiene i valori ottimistici finché ogni azione in attesa non è terminata, poi mostra il conteggio reale.

Quando usarlo, e quando no

Gli aggiornamenti ottimistici vanno bene per azioni che riescono quasi sempre e sono facili da annullare: mi piace, stelle, interruttori, rinominare, aggiungere un messaggio. Nel caso comune l'utente non vede alcuno spinner.

Evitali dove un falso "fatto" sarebbe fuorviante: pagamenti, eliminazione di un account, qualsiasi cosa su cui l'utente potrebbe agire prima di conoscere il risultato. In questi casi mostra uno stato di attesa con isPending di useActionState o di useTransition e aspetta la risposta reale.

Avvisa sempre l'utente quando avviene un ripristino. Un valore che torna indietro in silenzio sembra un bug. Entrambi gli esempi qui sopra tengono un messaggio di errore in uno stato normale così sopravvive all'azione.

Con useActionState

useOptimistic e useActionState vanno d'accordo. L'azione di useActionState è già una transizione, quindi puoi impostare il valore ottimistico all'inizio, e lo stato restituito è il valore reale a cui torna quello ottimistico.

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);

Mentre il salvataggio è in corso, la pagina mostra il nuovo titolo. Quando si risolve, state.title contiene il valore salvato. Se saveTitle genera un errore, l'errore dell'azione va all'error boundary più vicino; per mostrare invece il vecchio titolo con un messaggio, intercetta l'errore dentro l'azione e restituisci lo stato precedente più un errore.

Errori comuni

Chiamare il setter fuori da un'azione. Il valore ottimistico non resta sullo schermo, e React avvisa in sviluppo. Racchiudilo in startTransition o spostalo in una form action.

Dimenticare di aggiornare lo stato reale. In caso di successo, l'azione deve cambiare lo stato che useOptimistic rispecchia (setLiked, setMessages). Altrimenti il valore ottimistico sparisce quando l'azione termina, e una richiesta riuscita sembra un ripristino.

Aggiornare lo stato reale dopo un await senza una transizione. L'aggiornamento arriva comunque, ma React potrebbe mostrarlo in un momento diverso dalla fine dell'azione. Racchiudilo in startTransition, come fanno tutti e tre gli esempi.

Usare il valore ottimistico come fonte di verità. Invia le richieste e calcola i totali a partire dallo stato reale. Il valore ottimistico serve solo per la visualizzazione e può essere buttato via in qualsiasi momento.