6 de setembro de 2025Português

Desbloqueie validações de formulários poderosas e modernas no React. Guia completo sobre useFormStatus, Server Actions e validação por status.

Dominando a Validação de Formulários com `experimental_useFormStatus` do React

Formulários são a base da interação na web. Desde um simples cadastro em uma newsletter até um complexo aplicativo financeiro de múltiplas etapas, eles são o principal canal pelo qual os usuários se comunicam com nossas aplicações. No entanto, por anos, gerenciar o estado de formulários em React tem sido uma fonte de complexidade, código repetitivo e fadiga de dependências. Temos lidado com componentes controlados, lutado com bibliotecas de gerenciamento de estado e escrito inúmeros manipuladores `onChange`, tudo em busca de uma experiência de usuário fluida e intuitiva.

A equipe do React tem repensado esse aspecto fundamental do desenvolvimento web, levando à introdução de um novo e poderoso paradigma centrado em React Server Actions. Este novo modelo, construído sobre os princípios do aprimoramento progressivo, visa simplificar o manuseio de formulários, aproximando a lógica de onde ela pertence — muitas vezes, o servidor. No cerne desta revolução do lado do cliente estão dois novos hooks experimentais: `useFormState` e a estrela da nossa discussão hoje, `experimental_useFormStatus`.

Este guia abrangente o levará a um mergulho profundo no hook `experimental_useFormStatus`. Não olharemos apenas para sua sintaxe; exploraremos o modelo mental que ele permite: Lógica de Validação Baseada em Status. Você aprenderá como este hook desacopla a UI do estado do formulário, simplifica o gerenciamento de estados pendentes e funciona em conjunto com Server Actions para criar formulários robustos, acessíveis e de alto desempenho que funcionam mesmo antes do JavaScript carregar. Prepare-se para repensar tudo o que você achava que sabia sobre a construção de formulários em React.

Uma Mudança de Paradigma: A Evolução dos Formulários React

Para apreciar totalmente a inovação que `useFormStatus` traz, devemos primeiro entender a jornada do gerenciamento de formulários no ecossistema React. Este contexto destaca os problemas que essa nova abordagem resolve elegantemente.

A Velha Guarda: Componentes Controlados e Bibliotecas de Terceiros

Por anos, a abordagem padrão para formulários em React foi o padrão de componente controlado. Isso envolve:

Usar uma variável de estado React (por exemplo, de `useState`) para manter o valor de cada campo de formulário.
Escrever um manipulador `onChange` para atualizar o estado a cada digitação.
Passar a variável de estado de volta para a prop `value` do input.

Embora isso dê ao React controle total sobre o estado do formulário, ele introduz uma quantidade significativa de código repetitivo. Para um formulário com dez campos, você pode precisar de dez variáveis de estado e dez funções manipuladoras. Gerenciar a validação, estados de erro e status de submissão adiciona ainda mais complexidade, muitas vezes levando os desenvolvedores a criar hooks personalizados intrincados ou a recorrer a bibliotecas abrangentes de terceiros.

Bibliotecas como Formik e React Hook Form ganharam destaque abstraindo essa complexidade. Elas fornecem soluções brilhantes para gerenciamento de estado, validação e otimização de desempenho. No entanto, elas representam mais uma dependência a ser gerenciada e geralmente operam inteiramente do lado do cliente, o que pode levar à duplicação de lógica de validação entre o frontend e o backend.

A Nova Era: Aprimoramento Progressivo e Server Actions

React Server Actions introduzem uma mudança de paradigma. A ideia central é construir sobre a base da plataforma web: o elemento padrão `

` do HTML. Um formulário com uma server action funciona como um envio de formulário HTML clássico — ele pode funcionar perfeitamente mesmo que o JavaScript falhe ou esteja desativado. Essa é a essência do aprimoramento progressivo.

Quando o JavaScript carrega, o React intercepta o processo de envio do formulário, impedindo um recarregamento de página completo e executando a server action de forma assíncrona. Isso nos dá o melhor dos dois mundos: a resiliência de aplicações renderizadas no servidor e a experiência rica e interativa de uma aplicação de página única (SPA).

Este modelo move a fonte de verdade para a lógica de negócios e validação de volta para o servidor (ou um ambiente semelhante ao servidor). O código do lado do cliente se torna mais simples, preocupado principalmente em renderizar a UI com base no *status* dessa comunicação do servidor. É precisamente aqui que `useFormStatus` entra em jogo.

Por Dentro: O que é `experimental_useFormStatus`?

O hook `experimental_useFormStatus` é uma ferramenta do lado do cliente projetada para fornecer informações sobre o último envio de um elemento `` pai. É um hook somente leitura que informa a um componente tudo o que ele precisa saber sobre o status de envio do formulário sem a necessidade de passar props.

A Funcionalidade Central

Imagine um botão de envio dentro de um grande formulário. Como esse botão sabe quando o formulário está enviando? Tradicionalmente, você precisaria passar uma variável de estado como `isSubmitting` por várias camadas de componentes (prop drilling). Com `useFormStatus`, o componente do botão pode descobrir essa informação por si só.

O hook deve ser chamado de um componente renderizado *dentro* de um elemento ``. Ele então fornece informações de status sobre o ciclo de vida específico desse formulário.

Anatomia do Hook `useFormStatus`

Quando você chama `const status = useFormStatus()`, você obtém um objeto com as seguintes propriedades principais:

`pending` (booleano): Esta é a propriedade mais usada. É `true` se o formulário pai estiver sendo enviado no momento e `false` caso contrário. É perfeito para desabilitar botões, exibir spinners de carregamento ou estilizar estados pendentes.
`data` (FormData): Um objeto que implementa a interface `FormData`. Ele contém os dados que foram enviados com o formulário. Isso é incrivelmente útil para implementar atualizações de UI otimistas — por exemplo, mostrar o comentário de um usuário em uma lista imediatamente após ele enviá-lo, mesmo antes do servidor confirmar sua criação.
`method` (string): O método HTTP ('get' ou 'post') usado para o envio do formulário.
`action` (function): Uma referência à função server action que foi invocada durante o envio.

A Regra de Ouro: Um Filho do ``

Uma regra crítica a lembrar é que um componente que usa `useFormStatus` deve ser renderizado como um filho do elemento `` que ele está rastreando. Ele não pode estar no mesmo componente que renderiza a tag `` em si, pois precisa acessar o contexto do formulário. É por isso que você quase sempre verá componentes como um `` criados separadamente para abrigar a lógica `useFormStatus`.

Um Exemplo Simples: O Botão de Envio Inteligente

Vamos ver o caso de uso mais comum em ação. Em vez de um `); }

Arquivo: SignUpForm.js

import { SubmitButton } from './SubmitButton'; import { signUpAction } from './actions'; // Uma server action export function SignUpForm() { return ( Email: ); }

Neste exemplo, o `SubmitButton` é completamente autônomo. Ele não recebe nenhuma prop. Ele usa `useFormStatus` para saber quando o `SignUpForm` está pendente e automaticamente se desabilita e muda seu texto. Este é um padrão poderoso para desacoplamento e criação de componentes reutilizáveis e cientes de formulários.

O Coração da Questão: Lógica de Validação Baseada em Status

Agora chegamos ao conceito central. `useFormStatus` não é apenas para estados de carregamento; é um facilitador chave de uma maneira diferente de pensar sobre validação.

Definindo "Validação de Status"

Validação Baseada em Status é um padrão onde o feedback de validação é entregue principalmente ao usuário em resposta a uma tentativa de envio de formulário. Em vez de validar a cada digitação (`onChange`) ou quando um usuário sai de um campo (`onBlur`), a lógica principal de validação é executada quando o usuário envia o formulário. O resultado desse envio — seu *status* (por exemplo, sucesso, erro de validação, erro do servidor) — é então usado para atualizar a UI.

Essa abordagem se alinha perfeitamente com React Server Actions. A server action se torna a única fonte de verdade para a validação. Ela recebe os dados do formulário, valida-os contra suas regras de negócios (por exemplo, "este e-mail já está em uso?") e retorna um objeto de estado estruturado indicando o resultado.

O Papel de seu Parceiro: `experimental_useFormState`

`useFormStatus` nos diz *o que* está acontecendo (pendente), mas não nos diz o *resultado* do que aconteceu. Para isso, precisamos de seu hook irmão: `experimental_useFormState`.

`useFormState` é um hook projetado para atualizar o estado com base no resultado de uma ação de formulário. Ele recebe a função de ação e um estado inicial como argumentos e retorna um novo estado e uma função de ação encapsulada para passar para o seu formulário.

const [state, formAction] = useFormState(myAction, initialState);

`state`: Este conterá o valor de retorno da última execução de `myAction`. É aqui que obteremos nossas mensagens de erro.
`formAction`: Esta é uma nova versão da sua ação que você deve passar para a prop `action` do `
`. Quando esta for chamada, ela acionará a ação original e atualizará o `state`.

O Fluxo de Trabalho Combinado: Do Clique ao Feedback

Veja como `useFormState` e `useFormStatus` trabalham juntos para criar um loop de validação completo:

Renderização Inicial: O formulário é renderizado com um estado inicial fornecido por `useFormState`. Nenhum erro é exibido.
Envio do Usuário: O usuário clica no botão de envio.
Estado Pendente: O hook `useFormStatus` no botão de envio relata imediatamente `pending: true`. O botão fica desabilitado e exibe uma mensagem de carregamento.
Execução da Ação: A server action (encapsulada por `useFormState`) é executada com os dados do formulário. Ela realiza a validação.
Ação Retorna: A ação falha na validação e retorna um objeto de estado, por exemplo:
`{ message: "Falha na validação", errors: { email: "Este e-mail já está em uso." } }`
Atualização de Estado: `useFormState` recebe este valor de retorno e atualiza sua variável `state`. Isso aciona uma nova renderização do componente de formulário.
Feedback da UI: O formulário é renderizado novamente. O status `pending` de `useFormStatus` se torna `false`. O componente agora pode ler `state.errors.email` e exibir a mensagem de erro ao lado do campo de entrada de e-mail.

Todo esse fluxo fornece feedback claro e autorizado pelo servidor ao usuário, impulsionado inteiramente pelo status e resultado do envio.

Mestrado Prático: Construindo um Formulário de Registro com Múltiplos Campos

Vamos solidificar esses conceitos construindo um formulário de registro completo, no estilo de produção. Usaremos uma server action para validação e tanto `useFormState` quanto `useFormStatus` para criar uma ótima experiência do usuário.

Etapa 1: Definindo a Server Action com Validação

Primeiro, precisamos de nossa server action. Para validação robusta, usaremos a popular biblioteca Zod. Esta ação ficará em um arquivo separado, marcada com a diretiva `'use server';` se você estiver usando um framework como o Next.js.

Arquivo: actions/authActions.js

'use server'; import { z } from 'zod'; // Define o esquema de validação const registerSchema = z.object({ username: z.string().min(3, 'O nome de usuário deve ter pelo menos 3 caracteres.'), email: z.string().email('Por favor, insira um endereço de e-mail válido.'), password: z.string().min(8, 'A senha deve ter pelo menos 8 caracteres.'), }); // Define o estado inicial para nosso formulário export const initialState = { message: '', errors: {}, }; export async function registerUser(prevState, formData) { // 1. Valida os dados do formulário const validatedFields = registerSchema.safeParse( Object.fromEntries(formData.entries()) ); // 2. Se a validação falhar, retorne os erros if (!validatedFields.success) { return { message: 'Falha na validação. Por favor, verifique os campos.', errors: validatedFields.error.flatten().fieldErrors, }; } // 3. (Simular) Verificar se o usuário já existe no banco de dados // Em um aplicativo real, você consultaria seu banco de dados aqui. if (validatedFields.data.email === 'user@example.com') { return { message: 'Falha no registro.', errors: { email: ['Este e-mail já está registrado.'] }, }; } // 4. (Simular) Criar o usuário console.log('Criando usuário:', validatedFields.data); // 5. Retorna um estado de sucesso // Em um aplicativo real, você pode redirecionar aqui usando `redirect()` de 'next/navigation' return { message: 'Usuário registrado com sucesso!', errors: {}, }; }

Esta server action é o cérebro do nosso formulário. Ela é autônoma, segura e fornece uma estrutura de dados clara para estados de sucesso e erro.

Etapa 2: Construindo Componentes Reutilizáveis e Cientes de Status

Para manter nosso componente de formulário principal limpo, criaremos componentes dedicados para nossos inputs e botão de envio.

Arquivo: components/SubmitButton.js

'use client'; import { experimental_useFormStatus as useFormStatus } from 'react-dom'; export function SubmitButton({ label }) { const { pending } = useFormStatus(); return ( ); }

Note o uso de `aria-disabled={pending}`. Esta é uma prática importante de acessibilidade, garantindo que leitores de tela anunciem corretamente o estado desabilitado.

Etapa 3: Montando o Formulário Principal com `useFormState`

Agora, vamos juntar tudo em nosso componente de formulário principal. Usaremos `useFormState` para conectar nossa UI à ação `registerUser`.

Arquivo: components/RegistrationForm.js

'use client'; import { experimental_useFormState as useFormState } from 'react-dom'; import { registerUser, initialState } from '../actions/authActions'; import { SubmitButton } from './SubmitButton'; export function RegistrationForm() { const [state, formAction] = useFormState(registerUser, initialState); return (

`Registrar`



      {state?.message && !state.errors && {state.message}}
      {state?.message && state.errors && {state.message}}

      
        Nome de Usuário
        
        {state?.errors?.username && (
          
            {state.errors.username[0]}
          
        )}
      

      
        E-mail
        
        {state?.errors?.email && (
          
            {state.errors.email[0]}
          
        )}
      

      
        Senha
        
        {state?.errors?.password && (
          
            {state.errors.password[0]}
          
        )}
      

      
    
  );
}

Este componente agora é declarativo e limpo. Ele não gerencia nenhum estado próprio, exceto o objeto `state` fornecido por `useFormState`. Sua única tarefa é renderizar a UI com base nesse estado. A lógica para desabilitar o botão está encapsulada em `SubmitButton`, e toda a lógica de validação reside em `authActions.js`. Essa separação de responsabilidades é uma grande vitória para a manutenibilidade.

Técnicas Avançadas e Melhores Práticas Profissionais

Embora o padrão básico seja poderoso, aplicações do mundo real geralmente exigem mais nuances. Vamos explorar algumas técnicas avançadas.

A Abordagem Híbrida: Mesclando Validação Instantânea e Pós-Envio

A validação baseada em status é excelente para verificações do lado do servidor, mas esperar por uma viagem de ida e volta da rede para informar ao usuário que seu e-mail é inválido pode ser lento. Uma abordagem híbrida é frequentemente a melhor:

Use Validação HTML5: Não se esqueça do básico! Atributos como `required`, `type="email"`, `minLength` e `pattern` fornecem feedback instantâneo, nativo do navegador, sem nenhum custo.
Validação Leve do Lado do Cliente: Para verificações puramente cosméticas ou de formatação (por exemplo, indicador de força da senha), você ainda pode usar uma quantidade mínima de `useState` e manipuladores `onChange`.
Autoridade do Lado do Servidor: Reserve a server action para a validação mais crítica, de lógica de negócios, que não pode ser feita no cliente (por exemplo, verificar nomes de usuário únicos, validar contra registros do banco de dados).

Isso lhe dá o melhor dos dois mundos: feedback imediato para erros simples e validação autoritativa para regras complexas.

Acessibilidade (A11y): Construindo Formulários para Todos

A acessibilidade é inegociável. Ao implementar a validação baseada em status, tenha estes pontos em mente:

Anuncie Erros: Em nosso exemplo, usamos `aria-live="polite"` nos contêineres de mensagens de erro. Isso informa aos leitores de tela para anunciar a mensagem de erro assim que ela aparecer, sem interromper o fluxo atual do usuário.
Associe Erros a Inputs: Para uma conexão mais robusta, use o atributo `aria-describedby`. O input pode apontar para o ID de seu contêiner de mensagem de erro, criando um link programático.
Gerenciamento de Foco: Após um envio com erros, considere mover programaticamente o foco para o primeiro campo inválido. Isso economiza aos usuários a necessidade de procurar o que deu errado.

UI Otimista com a Propriedade `data` de `useFormStatus`

Imagine um aplicativo de mídia social onde um usuário posta um comentário. Em vez de mostrar um spinner por um segundo, você pode fazer o aplicativo parecer instantâneo. A propriedade `data` de `useFormStatus` é perfeita para isso.

Quando o formulário é enviado, `pending` se torna verdadeiro e `data` é preenchido com o `FormData` do envio. Você pode imediatamente renderizar o novo comentário em um estado visual temporário, 'pendente', usando esses `data`. Se a server action for bem-sucedida, você substitui o comentário pendente pelos dados finais do servidor. Se falhar, você pode remover o comentário pendente e exibir um erro. Isso faz o aplicativo parecer incrivelmente responsivo.

Navegando pelas Águas "Experimentais"

É crucial abordar o prefixo "experimental" em `experimental_useFormStatus` e `experimental_useFormState`.

O que "Experimental" Realmente Significa

Quando o React rotula uma API como experimental, isso significa:

A API pode mudar: O nome, argumentos ou valores de retorno podem ser alterados em uma futura versão do React sem seguir o versionamento semântico padrão (SemVer) para alterações de quebra.
Pode haver bugs: Como um novo recurso, ele pode ter casos extremos que ainda não foram totalmente compreendidos ou resolvidos.
A documentação pode ser escassa: Embora os conceitos centrais sejam documentados, guias detalhados sobre padrões avançados ainda podem estar em evolução.

Quando Adotar e Quando Esperar

Então, você deve usá-lo em seu projeto? A resposta depende do seu contexto:

Bom para: Projetos pessoais, ferramentas internas, startups ou equipes confortáveis em gerenciar potenciais mudanças de API. Usá-lo dentro de um framework como o Next.js (que integrou esses recursos ao seu App Router) é geralmente uma aposta mais segura, pois o framework pode ajudar a abstrair parte da volatilidade.
Use com Cautela para: Aplicações corporativas de grande escala, sistemas de missão crítica ou projetos com contratos de manutenção de longo prazo onde a estabilidade da API é primordial. Nesses casos, pode ser prudente esperar até que os hooks sejam promovidos para uma API estável.

Sempre fique de olho no blog oficial do React e na documentação para anúncios sobre a estabilização desses hooks.

Conclusão: O Futuro dos Formulários em React

A introdução de `experimental_useFormStatus` e suas APIs relacionadas é mais do que apenas uma nova ferramenta; representa uma mudança filosófica em como construímos experiências interativas com React. Ao abraçar os fundamentos da plataforma web e co-localizar a lógica com estado no servidor, podemos construir aplicações que são mais simples, mais resilientes e frequentemente mais performáticas.

Vimos como `useFormStatus` fornece uma maneira limpa e desacoplada para os componentes reagirem ao ciclo de vida de um envio de formulário. Ele elimina o prop drilling para estados pendentes e permite componentes de UI elegantes e autônomos, como um `SubmitButton` inteligente. Quando combinado com `useFormState`, ele desbloqueia o poderoso padrão de validação baseada em status, onde o servidor é a autoridade final, e a principal responsabilidade do cliente é renderizar o estado retornado pela server action.

Embora o rótulo "experimental" exija um certo grau de cautela, a direção é clara. O futuro dos formulários em React é de aprimoramento progressivo, gerenciamento de estado simplificado e uma integração poderosa e perfeita entre a lógica do cliente e do servidor. Ao dominar esses novos hooks hoje, você não está apenas aprendendo uma nova API; está se preparando para a próxima geração de desenvolvimento de aplicações web com React.