Hook useOptimistic en React: UI instantánea con reversión

useOptimistic es un hook de React 19 que permite que la pantalla muestre el resultado de una acción antes de que la acción termine. Defines un valor optimista dentro de una acción; React lo muestra mientras la acción está pendiente y luego vuelve al estado real. Si la petición falló, el estado real nunca cambió, así que la pantalla se revierte sola.

La API falsa de este ejemplo sustituye a una petición real y falla en cada tercera llamada, para que veas ambos resultados.

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

Haz clic en el botón tres veces, esperando un segundo entre clics. Los dos primeros cambian al instante y la línea de lo guardado se pone al día un segundo después. El tercero también cambia al instante, y luego vuelve atrás cuando la petición falla. Cambia calls % 3 por calls % 2 y falla cada segundo clic.

La sintaxis

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

• state es el valor real, normalmente de useState, de las props o de useActionState. Cuando no hay ninguna acción pendiente, optimisticState es exactamente este valor.
• setOptimistic(value) define el valor optimista mientras dure la acción actual.
• updateFn es opcional: (currentState, optimisticValue) => nextState. Con ella, setOptimistic recibe un cambio en lugar de un valor nuevo completo. Mira la forma con reducer más abajo.

El ciclo de vida de un clic siempre es el mismo:

1. Dentro de una acción, llamas a setOptimistic. La pantalla se actualiza al instante.
2. La acción espera la petición.
3. Si tiene éxito, actualizas el estado real (dentro de startTransition cuando viene después de un await).
4. La acción termina. optimisticState vuelve a seguir a state: el valor guardado si tuvo éxito, el valor viejo si falló.

El paso 4 es la razón por la que no hay código de reversión en el ejemplo. El bloque catch solo define un mensaje de error.

Debe ejecutarse dentro de una acción

El valor optimista solo existe mientras una transición está pendiente, así que setOptimistic tiene que llamarse dentro de una. Todas estas cuentan:

• la función que pasas a startTransition (o el startTransition de useTransition),
• una función pasada a <form action={...}> o <button formAction={...}>,
• la acción que le das a useActionState.

Si lo llamas desde un onClick normal, el valor optimista no tiene ninguna acción en la que vivir. React lo revierte enseguida, y en desarrollo registra "An optimistic state update occurred outside a transition or action".

Las actualizaciones del estado real que ocurren después de un await deben ir envueltas en su propio startTransition, como startTransition(() => setLiked(next)) arriba. Después de un await, React no puede saber que sigues dentro de la transición anterior.

Una lista de mensajes con la forma de reducer

Cuando el estado optimista es una lista, pasa una función de actualización como segundo argumento. El setter recibe entonces el nuevo elemento, y React lo agrega a la lista real que haya en ese 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>
    );
}

Envía tres mensajes con textos distintos, uno a la vez. Cada uno aparece atenuado con "(sending...)" y se vuelve sólido cuando se entrega; el tercero desaparece del chat y aparece como "Not sent". Envíalos rápido y los tres se quedan atenuados hasta que termina la última petición, porque React conserva los valores optimistas hasta que todas las acciones pendientes terminaron. La acción del formulario ya es una transición, así que aquí addOptimistic no necesita su propio startTransition.

Dale a cada elemento optimista una key que no choque con los elementos reales. El ejemplo usa pending- más el texto, así que enviar el mismo texto dos veces mientras ambos están pendientes haría que chocaran; una app real crearía un id en el cliente.

Varias actualizaciones a la vez

Como la función de actualización recibe el estado actual, las actualizaciones optimistas se acumulan. Haz clic rápido y cada clic pendiente se aplica encima del anterior.

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

Haz clic cuatro veces rápido. El carrito muestra 4 al instante. Cuando terminan las peticiones, el contador queda en 3, porque la tercera petición falló y la consola lo dice. React conserva los valores optimistas hasta que terminan todas las acciones pendientes, y luego muestra el conteo real.

Cuándo usarlo y cuándo no

Las actualizaciones optimistas sirven para acciones que casi siempre tienen éxito y son fáciles de deshacer: me gusta, estrellas, interruptores, renombrar, agregar un mensaje. El usuario no ve ningún indicador de carga en el caso habitual.

Evítalas donde un falso "hecho" engañaría: pagos, borrar una cuenta, cualquier cosa sobre la que el usuario pueda actuar antes de conocer el resultado. Para esos casos, muestra un estado pendiente con isPending de useActionState o useTransition y espera la respuesta real.

Avisa siempre al usuario cuando ocurre una reversión. Un valor que vuelve atrás en silencio parece un error. Los dos ejemplos de arriba guardan un mensaje de error en un estado normal para que sobreviva a la acción.

Con useActionState

useOptimistic y useActionState encajan bien. La acción de useActionState ya es una transición, así que puedes definir el valor optimista al principio, y el estado devuelto es el valor real al que vuelve el optimista.

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

Mientras se guarda, la página muestra el título nuevo. Cuando se resuelve, state.title contiene el valor guardado. Si saveTitle lanza un error, el error de la acción va al error boundary más cercano; para mostrar el título viejo con un mensaje en su lugar, captura el error dentro de la acción y devuelve el estado anterior más un error.

Errores comunes

Llamar al setter fuera de una acción. El valor optimista no se queda en pantalla, y React avisa en desarrollo. Envuélvelo en startTransition o muévelo a una acción de formulario.

Olvidar actualizar el estado real. Si tiene éxito, la acción debe cambiar el estado que refleja useOptimistic (setLiked, setMessages). Si no, el valor optimista desaparece cuando termina la acción, y una petición exitosa parece una reversión.

Actualizar el estado real después de un await sin una transición. La actualización igual se aplica, pero React puede mostrarla en un momento distinto al final de la acción. Envuélvela en startTransition, como hacen los tres ejemplos.

Usar el valor optimista como fuente de verdad. Envía las peticiones y calcula los totales a partir del estado real. El valor optimista es solo para mostrar y puede descartarse en cualquier momento.