Hook useActionState en React: formularios, errores y carga

useActionState es un hook de React 19 que ejecuta una función async (una acción), guarda como estado lo que devuelve y te dice si todavía se está ejecutando. Lo llamas como const [state, formAction, isPending] = useActionState(action, initialState) y pasas formAction a un <form>.

import { useActionState } from 'react';

function subscribe(email) {
    // Stands in for a real request
    return new Promise((resolve) => setTimeout(resolve, 1000));
}

async function joinList(previousState, formData) {
    const email = formData.get('email');
    if (!email.includes('@')) {
        return { ok: false, message: 'That does not look like an email.' };
    }
    await subscribe(email);
    return { ok: true, message: `Subscribed ${email}.` };
}

export default function App() {
    const [state, formAction, isPending] = useActionState(joinList, { ok: false, message: '' });

    return (
        <form action={formAction}>
            <input name="email" placeholder="you@example.com" />
            <button type="submit" disabled={isPending}>
                {isPending ? 'Subscribing...' : 'Subscribe'}
            </button>
            {state.message && (
                <p style={{ color: state.ok ? 'green' : 'crimson' }}>{state.message}</p>
            )}
        </form>
    );
}

Envía primero el formulario vacío: la acción devuelve un objeto de error y aparece el mensaje. Luego escribe una dirección con @ y vuelve a enviar. Durante un segundo el botón dice "Subscribing..." y está deshabilitado.

La sintaxis

const [state, formAction, isPending] = useActionState(action, initialState, permalink?);

• action es la función a ejecutar. React la llama como action(previousState, ...args). Lo que devuelva (o con lo que se resuelva, si es async) se convierte en el nuevo state.
• initialState es el estado antes de que la acción se haya ejecutado nunca. Usa la misma forma que devuelve la acción, para que el componente también pueda leer state.message en el primer renderizado.
• state es el último resultado.
• formAction es una versión envuelta de tu acción. Pásala a <form action> o <button formAction>, o llámala tú mismo.
• isPending es true desde el momento en que empieza la acción hasta que termina.
• permalink es opcional y solo importa para las Server Functions en un framework: la URL a la que debe ir el formulario si se envía antes de que cargue JavaScript.

La acción recibe el estado anterior como primer argumento. Es el error más común al migrar un formulario: escribir async function save(formData) te da el estado viejo en formData, y formData.get lanza un error.

Leer el formulario con FormData

Cuando formAction se usa como action de un formulario, React llama a tu acción con el FormData del formulario. Contiene cada campo que tenga un name. No necesitas useState para los inputs ni un manejador onChange, y no llamas a e.preventDefault(): React maneja el evento de envío.

import { useActionState } from 'react';

async function order(previousState, formData) {
    const entries = Object.fromEntries(formData);
    console.log('form data:', entries);
    return { count: previousState.count + 1, last: entries };
}

export default function App() {
    const [state, formAction] = useActionState(order, { count: 0, last: null });

    return (
        <form action={formAction}>
            <input name="dish" defaultValue="Ramen" />
            <select name="size" defaultValue="large">
                <option value="small">Small</option>
                <option value="large">Large</option>
            </select>
            <label>
                <input type="checkbox" name="spicy" defaultChecked /> Spicy
            </label>
            <button type="submit">Order</button>
            <p>Orders placed: {state.count}</p>
            {state.last && <p>Last: {state.last.size} {state.last.dish}</p>}
        </form>
    );
}

Desmarca Spicy y vuelve a enviar: la clave spicy desaparece de los datos registrados, porque una casilla sin marcar no envía nada. La acción también lee previousState.count para sumar uno, y por eso el estado anterior va primero.

Devolver errores de validación

La validación va en la acción. Devuelve los errores como parte del estado, y devuelve los valores que escribió el usuario para que el formulario pueda volver a ponerlos. Cuando termina una acción de formulario, React reinicia los campos no controlados, así que un campo sin defaultValue={state.values...} volvería vacío después de un envío fallido.

import { useActionState } from 'react';

function createAccount(name) {
    // Stands in for a real request
    return new Promise((resolve) => setTimeout(() => resolve({ id: 7, name }), 800));
}

async function signUp(previousState, formData) {
    const values = { name: formData.get('name'), password: formData.get('password') };
    const errors = {};
    if (values.name.trim().length < 2) errors.name = 'At least 2 characters.';
    if (values.password.length < 8) errors.password = 'At least 8 characters.';
    if (Object.keys(errors).length > 0) {
        return { values, errors, user: null };
    }
    const user = await createAccount(values.name);
    return { values: { name: '', password: '' }, errors: {}, user };
}

const initial = { values: { name: '', password: '' }, errors: {}, user: null };

export default function App() {
    const [state, formAction, isPending] = useActionState(signUp, initial);

    if (state.user) return <p>Welcome, {state.user.name} (account #{state.user.id}).</p>;

    return (
        <form action={formAction} style={{ display: 'grid', gap: 6, maxWidth: 240 }}>
            <input name="name" placeholder="Name" defaultValue={state.values.name} />
            {state.errors.name && <small style={{ color: 'crimson' }}>{state.errors.name}</small>}
            <input name="password" type="password" placeholder="Password" defaultValue={state.values.password} />
            {state.errors.password && <small style={{ color: 'crimson' }}>{state.errors.password}</small>}
            <button type="submit" disabled={isPending}>{isPending ? 'Creating...' : 'Create account'}</button>
        </form>
    );
}

Escribe un nombre de una letra y una contraseña corta, y envía. Aparecen ambos errores y ambos campos conservan lo que escribiste. Quita defaultValue={state.values.name} y vuelve a enviar: el campo del nombre se vacía solo después del error.

En una app real, deja que el servidor tenga la última palabra. Las comprobaciones en el cliente dan una respuesta rápida, pero cualquiera puede enviar una petición sin tu formulario.

Llamar a la acción fuera de un formulario

formAction es una función, así que un botón o un efecto también pueden llamarla. Cuando la llames tú, envuelve la llamada en startTransition. Un formulario lo hace por ti; un onClick normal no, y sin una transición isPending no se actualiza bien (React registra un error sobre ello en desarrollo).

import { startTransition, useActionState } from 'react';

function fetchNextPage(page) {
    // Stands in for a real request
    return new Promise((resolve) =>
        setTimeout(() => resolve([`Item ${page * 2 - 1}`, `Item ${page * 2}`]), 700),
    );
}

async function loadMore(previousState) {
    const page = previousState.page + 1;
    const items = await fetchNextPage(page);
    return { page, items: [...previousState.items, ...items] };
}

export default function App() {
    const [state, load, isPending] = useActionState(loadMore, { page: 0, items: [] });

    return (
        <div>
            <ul>
                {state.items.map((item) => (
                    <li key={item}>{item}</li>
                ))}
            </ul>
            <button onClick={() => startTransition(() => load())} disabled={isPending}>
                {isPending ? 'Loading...' : 'Load more'}
            </button>
        </div>
    );
}

Haz clic en Load more varias veces. Cada llamada parte del estado que devolvió la anterior, así que las páginas se agregan en orden. Si vuelves a llamar a la acción mientras todavía se está ejecutando, React pone la llamada en cola y la ejecuta después de la actual, cada una con el estado más reciente.

De dónde salió useActionState

Antes de que saliera React 19, este hook estaba disponible en las versiones canary como useFormState, importado desde react-dom. Se renombró a useActionState, se movió a react y recibió el valor isPending. Si encuentras código antiguo como este, la solución es el import y el nombre:

// React canary, before 19
import { useFormState } from 'react-dom';
const [state, formAction] = useFormState(action, initialState);

// React 19
import { useActionState } from 'react';
const [state, formAction, isPending] = useActionState(action, initialState);

Para mostrar un estado pendiente en un botón de envío muy anidado, useFormStatus de react-dom lee el estado del formulario padre sin props. La visión general de React 19 lo enumera junto con las demás funciones de formularios.

Errores y cuándo usar otra cosa

Si la acción lanza un error, React muestra el error boundary más cercano en lugar de actualizar el estado. Para errores que el usuario puede corregir, como la validación o un nombre de usuario ocupado, devuélvelos como estado, como en el ejemplo de registro. Deja que los fallos reales lancen.

useActionState es para el resultado de una acción. Para un valor que se actualiza al instante mientras corre la acción, como un contador de me gusta que debe subir al hacer clic, combínalo con useOptimistic. Para una entrada que cambia en cada pulsación y se lee durante el renderizado, useState y un input controlado siguen siendo la herramienta adecuada.

Errores comunes

Olvidar el parámetro del estado anterior. async function save(formData) recibe el estado anterior en formData. La firma siempre es (previousState, formData) para un formulario.

Inputs sin name. FormData solo contiene los campos que tienen un atributo name. Un campo con solo un id falta en formData.get(...), que devuelve null.

Inputs controlados en todas partes. Todavía puedes usar value y onChange dentro de una acción de formulario, pero no hace falta. Los campos no controlados con name y defaultValue encajan mejor con las acciones, y el reinicio de React después del envío solo afecta a los campos no controlados.

Leer el estado dentro de la acción. El state del componente es el valor del renderizado que creó el manejador. Dentro de la acción, usa previousState, que siempre es el resultado de la llamada anterior, incluso cuando se pusieron varias llamadas en cola.

Lanzar errores para casos esperados. Un error lanzado reemplaza el formulario por el error boundary más cercano. Una contraseña incorrecta no es un fallo; devuélvela como estado.