useActionState e useFormStatus

useActionState(action, initialState) é um gancho do React 19 que envolve uma Ação do servidor para acompanhar seu estado entre os envios. Ele recebe a função de ação e um valor de estado inicial e retorna uma tupla que pode ser usada para controlar toda a experiência do formulário.

O gancho retorna [state, formAction, isPending]. O state contém o valor retornado mais recentemente pela ação, começando como null ou como o seu valor inicial. formAction é a ação envolvida que deve ser passada ao formulário. isPending é true enquanto a ação está sendo executada no servidor.

Cada vez que o formulário é enviado, a Ação do servidor é executada e seu valor retornado se torna o novo state. Na primeira renderização, state é igual a initialState. Isso facilita exibir diferentes partes da interface dependendo de já ter havido envios anteriores e do que eles retornaram.

Se a Ação do servidor retornar { errors: { email: 'Invalid email' } }, você poderá exibir o erro no próprio formulário: {state.errors?.email && <p>{state.errors.email}</p>}. Como o estado persiste entre as renderizações, a mensagem de erro permanece visível até que o próximo envio bem-sucedido substitua o estado.

Quando a ação retorna { success: true }, o componente pode renderizar uma mensagem de sucesso: {state?.success && <p>Form submitted!</p>}. O formulário pode ser ocultado ou substituído condicionalmente pela mensagem de sucesso com base no valor do estado.

useFormStatus() é um gancho que lê o estado pendente do elemento <form> ancestral mais próximo. Ele retorna um objeto que inclui { pending: boolean }. Esse gancho deve ser usado dentro de um componente que seja filho do formulário, e não no componente que renderiza o próprio formulário.

A restrição que exige o uso de useFormStatus dentro do formulário existe porque o gancho lê o contexto do formulário na árvore do React acima dele. Se fosse chamado no mesmo componente que renderiza o formulário, ele seria um irmão do formulário, não um descendente, e não teria acesso ao estado do formulário.

O padrão comum é extrair o botão de envio para seu próprio componente: function SubmitButton() { const { pending } = useFormStatus(); return <button disabled={pending}>Submit</button>; }. Esse componente é então colocado dentro do formulário, permitindo que ele acesse o estado pendente do formulário.

Definir disabled={pending} no botão de envio evita envios duplicados. Quando o usuário clica em enviar e a Ação do servidor está sendo executada, pending é true, o botão fica desabilitado e não pode ser clicado. Quando a ação é concluída, pending volta a false e o botão é habilitado novamente.

O padrão completo de experiência do usuário para formulários combina os dois ganchos: useActionState no componente do formulário acompanha o resultado da ação e fornece formAction, enquanto useFormStatus, dentro de um componente filho SubmitButton, acompanha o estado pendente. Juntos, eles oferecem a exibição de erros de validação e um botão de envio responsivo.

Para uma experiência ainda mais responsiva, useOptimistic funciona em conjunto com useActionState. Você atualiza imediatamente a interface com o resultado esperado antes que o servidor responda e depois a sincroniza quando a resposta real chega. Esse padrão é comum em botões de curtida, listas de tarefas e outras interações que exigem retorno rápido.

Onde useFormStatus deve ser chamado para funcionar corretamente?

useActionState(action, initialState) retorna [state, formAction, isPending] para acompanhar os resultados das Ações do servidor. O estado contém o valor retornado pela ação, permitindo exibir erros e mensagens de sucesso no próprio formulário. useFormStatus() fornece { pending } dentro dos componentes filhos do formulário, permitindo criar botões de envio responsivos. Juntos, os dois ganchos criam uma experiência de formulário completa e acessível.