useActionState y useFormStatus

useActionState(action, initialState) es un hook de React 19 que envuelve un Server Action para realizar un seguimiento de su estado entre envíos. Recibe la función de acción y un valor de estado inicial, y devuelve una tupla que puede utilizar para controlar toda la experiencia del formulario.

El hook devuelve [state, formAction, isPending]. state contiene el valor devuelto más reciente por la acción (inicialmente es null o el valor inicial). formAction es la acción envuelta que debe pasar al formulario. isPending es true mientras la acción se ejecuta en el servidor.

Cada vez que se envía el formulario, se ejecuta el Server Action y su valor devuelto se convierte en el nuevo state. En el primer renderizado, state es igual a initialState. Esto facilita mostrar una interfaz diferente según haya habido envíos anteriores y según lo que hayan devuelto.

Si el Server Action devuelve { errors: { email: 'Invalid email' } }, puede mostrar el error en línea: {state.errors?.email && <p>{state.errors.email}</p>}. Como el estado persiste entre los nuevos renderizados, el mensaje de error permanece visible hasta que un envío correcto posterior sustituye el estado.

Cuando la acción devuelve { success: true }, el componente puede mostrar un mensaje de éxito: {state?.success && <p>Form submitted!</p>}. El formulario puede ocultarse o sustituirse condicionalmente por el mensaje de éxito según el valor del estado.

useFormStatus() es un hook que lee el estado pendiente del elemento <form> antecesor más cercano. Devuelve un objeto que incluye { pending: boolean }. Este hook debe utilizarse dentro de un componente que sea hijo del formulario, no en el componente que renderiza el propio formulario.

La restricción que exige utilizar useFormStatus dentro del formulario existe porque el hook lee el contexto del formulario desde el árbol de React que se encuentra por encima. Si se llamara desde el mismo componente que renderiza el formulario, sería un componente hermano del formulario, no un descendiente, y no tendría acceso al estado del formulario.

El patrón estándar consiste en extraer el botón de envío a su propio componente: function SubmitButton() { const { pending } = useFormStatus(); return <button disabled={pending}>Submit</button>; }. Después, este componente se coloca dentro del formulario, lo que le permite acceder al estado pendiente del formulario.

Establecer disabled={pending} en el botón de envío evita los envíos duplicados. Cuando el usuario hace clic en enviar y el Server Action se está ejecutando, pending es true, por lo que el botón se desactiva y no se puede pulsar. Cuando la acción termina, pending vuelve a false y el botón se habilita de nuevo.

El patrón completo de experiencia de usuario para formularios combina ambos hooks: useActionState en el componente del formulario realiza un seguimiento del resultado de la acción y proporciona formAction, mientras que useFormStatus dentro de un componente hijo SubmitButton realiza un seguimiento del estado pendiente. Juntos proporcionan la visualización de errores de validación y un botón de envío adaptable.

Para obtener una respuesta aún más rápida, useOptimistic se combina con useActionState. La interfaz se actualiza inmediatamente con el resultado esperado antes de que responda el servidor y después se ajusta cuando llega la respuesta real. Este patrón es habitual en botones de «Me gusta», listas de tareas y otras interacciones que requieren una respuesta inmediata.

¿Dónde debe llamarse a useFormStatus para que funcione correctamente?

useActionState(action, initialState) devuelve [state, formAction, isPending] para realizar un seguimiento de los resultados de Server Actions. El estado contiene el valor devuelto por la acción, lo que permite mostrar errores y mensajes de éxito en línea. useFormStatus() proporciona { pending } dentro de los componentes hijos del formulario, lo que permite crear botones de envío adaptables. Ambos hooks juntos crean una experiencia de formulario completa y accesible.