Formulários

Q: Qual é a diferença entre inputs controlados e não controlados?

Controlados: O estado do React impulsiona o input via value + onChange - o React é a fonte da verdade Não Controlados: O DOM segura o valor via defaultValue - leia sob demanda com uma ref ou FormData Use controlados para validação em tempo real; não controlados para formulários simples ou entradas sensíveis ao desempenho

Q: O que são ações de formulário do React 19?

Você pode passar uma função async diretamente para . O React a chama com um objeto FormData no envio, lida com o estado pendente e se integra com useActionState para gerenciar valores de retorno - sem necessidade de e.preventDefault().

Q: O que é useActionState e como funciona?

useActionState(actionFn, initialState) retorna [state, formAction, isPending]. No envio, ele chama actionFn(prevState, formData) e atualiza state com o resultado. isPending é true enquanto a ação é executada.

Q: Por que meu input controlado está somente leitura?

Definir value sem um manipulador onChange torna o input não editável - o React trava o valor no estado. Adicione onChange para atualizar o estado, ou mude para defaultValue para um input não controlado.

Q: Por que mudar defaultValue não atualiza meu input?

defaultValue apenas define o valor inicial do DOM na montagem. Mudanças após a montagem não têm efeito. Use value controlado se o React precisar impulsionar as atualizações, ou adicione uma prop key para forçar a remontagem.

Q: Como lidar com checkboxes e radio buttons?

Use checked / defaultChecked em vez de value / defaultValue:

Q: Como obter um número de um input numérico?

e.target.value é sempre uma string, mesmo para . Analise explicitamente: Number(e.target.value) ou parseInt(e.target.value, 10).

Q: O que é useFormStatus e onde posso usá-lo?

useFormStatus() retorna { pending } para mostrar o estado de carregamento durante uma ação de formulário. Ele deve ser chamado em um componente que seja um filho de um - não no mesmo componente que renderiza o formulário.

Manipule a entrada do usuário com componentes controlados, refs não controladas ou ações de formulário do React 19.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// Input controlado
const [email, setEmail] = useState("");
<input value={email} onChange={e => setEmail(e.target.value)} />
 
// Input não controlado com ref
const inputRef = useRef<HTMLInputElement>(null);
<input ref={inputRef} defaultValue="" />
// Leia depois: inputRef.current?.value
 
// Ação de formulário do React 19
async function createUser(formData: FormData) {
  const name = formData.get("name") as string;
  await saveToDatabase(name);
}
<form action={createUser}>
  <input name="name" required />
  <button type="submit">Criar</button>
</form>
 
// useActionState do React 19
const [state, formAction, isPending] = useActionState(submitFn, initialState);

Quando usar isso: Sempre que você coletar entrada do usuário - formulários de login, barras de pesquisa, páginas de configurações, assistentes de várias etapas.

Exemplo de Trabalho

"use client";
 
import { useState, useActionState } from "react";
 
// --- Formulário Controlado ---
 
export function ControlledSignup() {
  const [form, setForm] = useState({ name: "", email: "", role: "viewer" });
  const [submitted, setSubmitted] = useState(false);
 
  function updateField(field: string, value: string) {
    setForm(prev => ({ ...prev, [field]: value }));
  }
 
  function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    setSubmitted(true);
  }
 
  if (submitted) {
    return (
      <div className="rounded bg-green-50 p-4 text-green-800">
        Bem-vindo(a), {form.name}! Enviamos uma confirmação para {form.email}.
      </div>
    );
  }
 
  return (
    <form onSubmit={handleSubmit} className="max-w-sm space-y-3 rounded border p-4">
      <div>
        <label htmlFor="name" className="block text-sm font-medium">Nome</label>
        <input
          id="name"
          value={form.name}
          onChange={e => updateField("name", e.target.value)}
          required
          className="w-full rounded border px-3 py-1"
        />
      </div>
      <div>
        <label htmlFor="email" className="block text-sm font-medium">Email</label>
        <input
          id="email"
          type="email"
          value={form.email}
          onChange={e => updateField("email", e.target.value)}
          required
          className="w-full rounded border px-3 py-1"
        />
      </div>
      <div>
        <label htmlFor="role" className="block text-sm font-medium">Função</label>
        <select
          id="role"
          value={form.role}
          onChange={e => updateField("role", e.target.value)}
          className="w-full rounded border px-3 py-1"
        >
          <option value="viewer">Visualizador</option>
          <option value="editor">Editor</option>
          <option value="admin">Admin</option>
        </select>
      </div>
      <button type="submit" className="rounded bg-blue-600 px-4 py-2 text-white">
        Inscrever-se
      </button>
    </form>
  );
}
 
// --- Ação de Formulário do React 19 com useActionState ---
 
interface FormState {
  message: string;
  error: boolean;
}
 
async function submitFeedback(
  prevState: FormState,
  formData: FormData
): Promise<FormState> {
  const feedback = formData.get("feedback") as string;
 
  // Simula atraso do servidor
  await new Promise(resolve => setTimeout(resolve, 1000));
 
  if (feedback.length < 10) {
    return { message: "O feedback deve ter pelo menos 10 caracteres.", error: true };
  }
 
  return { message: `Obrigado pelo seu feedback!`, error: false };
}
 
export function FeedbackForm() {
  const [state, formAction, isPending] = useActionState(submitFeedback, {
    message: "",
    error: false,
  });
 
  return (
    <form action={formAction} className="max-w-sm space-y-3 rounded border p-4">
      <label htmlFor="feedback" className="block text-sm font-medium">
        Seu Feedback
      </label>
      <textarea
        id="feedback"
        name="feedback"
        required
        rows={3}
        className="w-full rounded border px-3 py-1"
        placeholder="Diga-nos o que você pensa..."
      />
 
      {state.message && (
        <p className={state.error ? "text-sm text-red-600" : "text-sm text-green-600"}>
          {state.message}
        </p>
      )}
 
      <button
        type="submit"
        disabled={isPending}
        className="rounded bg-blue-600 px-4 py-2 text-white disabled:opacity-50"
      >
        {isPending ? "Enviando..." : "Enviar Feedback"}
      </button>
    </form>
  );
}

O que isso demonstra:

Formulário controlado com value + onChange para cada input
useActionState (React 19) gerenciando o estado de envio do formulário, indicador de pendência e validação
API FormData para ler valores do formulário sem estado controlado
Combinação acessível de label + htmlFor
Botão de envio desabilitado durante a ação assíncrona

Mergulho Profundo

Como Funciona

Componentes controlados mantêm os valores de entrada no estado do React - o componente é a fonte da verdade, e a entrada reflete value em cada renderização
Componentes não controlados deixam o DOM segurar o valor - você o lê sob demanda via ref ou FormData
Ações de formulário do React 19 permitem que você passe uma função async para <form action={fn}>. O React lida com o envio, fornece isPending e se integra com useActionState para gerenciar valores de retorno
useActionState(actionFn, initialState) retorna [state, wrappedAction, isPending] - ele chama actionFn(prevState, formData) no envio e atualiza o estado com o resultado

Controlado vs. Não Controlado vs. Ações

Abordagem	Fonte da Verdade	Melhor Para
Controlado (`value` + `onChange`)	Estado do React	Validação em tempo real, campos condicionais, entradas interdependentes complexas
Não Controlado (`defaultValue` + ref)	DOM	Formulários simples, integrações de terceiros, entradas sensíveis ao desempenho
Ações de Formulário (React 19)	FormData	Mutações do lado do servidor, melhoria progressiva, redução de estado do cliente

Parâmetros e Valores de Retorno

useActionState:

Parâmetro	Tipo	Descrição
`action`	`(prevState: T, formData: FormData) => T or Promise<T>`	Função chamada no envio do formulário
`initialState`	`T`	Estado inicial antes do primeiro envio
`permalink?`	`string`	URL opcional para melhoria progressiva com SSR

Retorno	Tipo	Descrição
`state`	`T`	Estado atual (atualizado após a conclusão da ação)
`formAction`	`(formData: FormData) => void`	Ação encapsulada para passar para `<form action>`
`isPending`	`boolean`	`true` enquanto a ação estiver em execução

Variações

Não Controlado com FormData (sem necessidade de useState):

function SearchForm() {
  function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    const query = formData.get("query") as string;
    router.push(`/search?q=${encodeURIComponent(query)}`);
  }
 
  return (
    <form onSubmit={handleSubmit}>
      <input name="query" defaultValue="" />
      <button type="submit">Pesquisar</button>
    </form>
  );
}

useFormStatus para botões de envio aninhados:

import { useFormStatus } from "react-dom";
 
function SubmitButton() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? "Salvando..." : "Salvar"}
    </button>
  );
}
 
// Uso - SubmitButton deve ser um filho de um <form>
<form action={saveAction}>
  <input name="title" />
  <SubmitButton />
</form>

Atualizações otimistas com useOptimistic:

import { useOptimistic } from "react";
 
function MessageList({ messages, sendAction }: Props) {
  const [optimisticMessages, addOptimistic] = useOptimistic(
    messages,
    (state, newMessage: string) => [
      ...state,
      { id: "temp", text: newMessage, sending: true },
    ]
  );
 
  async function handleSubmit(formData: FormData) {
    const text = formData.get("message") as string;
    addOptimistic(text);
    await sendAction(formData);
  }
 
  return (
    <form action={handleSubmit}>
      <ul>
        {optimisticMessages.map(msg => (
          <li key={msg.id} style={{ opacity: msg.sending ? 0.5 : 1 }}>
            {msg.text}
          </li>
        ))}
      </ul>
      <input name="message" />
      <button type="submit">Enviar</button>
    </form>
  );
}

Notas de TypeScript

// Tipando onChange para diferentes tipos de input
function handleChange(e: React.ChangeEvent<HTMLInputElement>) { ... }
function handleSelectChange(e: React.ChangeEvent<HTMLSelectElement>) { ... }
function handleTextareaChange(e: React.ChangeEvent<HTMLTextAreaElement>) { ... }
 
// Tipando o estado da ação do formulário
interface ActionState {
  success: boolean;
  errors: Record<string, string>;
}
 
async function myAction(
  prev: ActionState,
  formData: FormData
): Promise<ActionState> {
  // validar e retornar novo estado
}

Armadilhas

Falta de value ou onChange - Definir value sem onChange torna o input somente leitura. O React avisa sobre isso. Correção: Adicione um manipulador onChange ou use defaultValue para inputs não controlados.
defaultValue não atualiza - Alterar defaultValue após a montagem não tem efeito, pois ele apenas define o valor inicial do DOM. Correção: Use value controlado se precisar que o React impulsione as atualizações, ou adicione uma key para remontar o input.
checked de Checkbox e Rádio - Estes usam checked / defaultChecked, não value / defaultValue. Correção: <input type="checkbox" checked={isOn} onChange={e => setIsOn(e.target.checked)} />.
Number inputs retornam strings - e.target.value é sempre uma string, mesmo para <input type="number">. Correção: Analise explicitamente: Number(e.target.value) ou parseInt(e.target.value, 10).
useFormStatus fora de um formulário - useFormStatus só funciona quando o componente é renderizado como um descendente de um <form>. Chamá-lo no mesmo componente que renderiza o <form> retorna dados desatualizados. Correção: Extraia o botão de envio para um componente filho.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
React Hook Form	Validação complexa, muitos campos, formulários críticos de desempenho	Formulários simples com 1-3 campos
Zod + Server Actions	Mutações de servidor validadas por esquema em Next.js	Formulários apenas do lado do cliente sem servidor
Formik	Projetos legados que já o utilizam	Novos projetos (React Hook Form é mais leve)
`<dialog>` nativo + `<form method="dialog">`	Diálogos de confirmação modais	Coleta de dados de vários campos

FAQs

Qual é a diferença entre inputs controlados e não controlados?

Controlados: O estado do React impulsiona o input via value + onChange - o React é a fonte da verdade
Não Controlados: O DOM segura o valor via defaultValue - leia sob demanda com uma ref ou FormData
Use controlados para validação em tempo real; não controlados para formulários simples ou entradas sensíveis ao desempenho

O que são ações de formulário do React 19?

Você pode passar uma função async diretamente para <form action={fn}>. O React a chama com um objeto FormData no envio, lida com o estado pendente e se integra com useActionState para gerenciar valores de retorno - sem necessidade de e.preventDefault().

O que é useActionState e como funciona?

useActionState(actionFn, initialState) retorna [state, formAction, isPending]. No envio, ele chama actionFn(prevState, formData) e atualiza state com o resultado. isPending é true enquanto a ação é executada.

Por que meu input controlado está somente leitura?

Definir value sem um manipulador onChange torna o input não editável - o React trava o valor no estado. Adicione onChange para atualizar o estado, ou mude para defaultValue para um input não controlado.

Por que mudar defaultValue não atualiza meu input?

defaultValue apenas define o valor inicial do DOM na montagem. Mudanças após a montagem não têm efeito. Use value controlado se o React precisar impulsionar as atualizações, ou adicione uma prop key para forçar a remontagem.

Como lidar com checkboxes e radio buttons?

Use checked / defaultChecked em vez de value / defaultValue:

<input
  type="checkbox"
  checked={isEnabled}
  onChange={e => setIsEnabled(e.target.checked)}
/>

Como obter um número de um input numérico?

e.target.value é sempre uma string, mesmo para <input type="number">. Analise explicitamente: Number(e.target.value) ou parseInt(e.target.value, 10).

O que é useFormStatus e onde posso usá-lo?

useFormStatus() retorna { pending } para mostrar o estado de carregamento durante uma ação de formulário. Ele deve ser chamado em um componente que seja um filho de um <form> - não no mesmo componente que renderiza o formulário.

Como lidar com vários campos de formulário sem useState separado para cada um?

Use um único objeto de estado e uma função de atualização genérica:

const [form, setForm] = useState({ name: "", email: "" });
function updateField(field: string, value: string) {
  setForm(prev => ({ ...prev, [field]: value }));
}

Quando devo usar uma biblioteca de formulários como React Hook Form em vez disso?

Mais de 3-5 campos com regras de validação
Validação interdependente complexa (campo B depende do campo A)
Formulários críticos de desempenho onde re-renderizações por pressionamento de tecla importam
Para formulários simples com 1-3 campos, inputs controlados simples ou ações de formulário são suficientes

Como implementar atualizações otimistas com formulários no React 19?

Use useOptimistic para mostrar imediatamente o resultado esperado enquanto a ação processa. Se a ação falhar, o React reverte automaticamente para o estado real.

Como tornar os formulários acessíveis?

Emparelhe cada input com um <label htmlFor="id"> correspondente ao id do input
Use required, aria-describedby para mensagens de erro e aria-invalid para campos inválidos
Certifique-se de que as mensagens de erro sejam anunciadas para leitores de tela

Relacionado

Eventos - manipulação geral de eventos em que os formulários se baseiam
Refs - acesso a valores de input não controlados
useState - alimentando inputs controlados
Componentes - compondo componentes de campo de formulário

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// Input controlado
const [email, setEmail] = useState("");
<input value={email} onChange={e => setEmail(e.target.value)} />
 
// Input não controlado com ref
const inputRef = useRef<HTMLInputElement>(null);
<input ref={inputRef} defaultValue="" />
// Leia depois: inputRef.current?.value
 
// Ação de formulário do React 19
async function createUser(formData: FormData) {
  const name = formData.get("name") as string;
  await saveToDatabase(name);
}
<form action={createUser}>
  <input name="name" required />
  <button type="submit">Criar</button>
</form>
 
// useActionState do React 19
const [state, formAction, isPending] = useActionState(submitFn, initialState);

Quando usar isso: Sempre que você coletar entrada do usuário - formulários de login, barras de pesquisa, páginas de configurações, assistentes de várias etapas.

Exemplo de Trabalho

"use client";
 
import { useState, useActionState } from "react";
 
// --- Formulário Controlado ---
 
export function ControlledSignup() {
  const [form, setForm] = useState({ name: "", email: "", role: "viewer" });
  const [submitted, setSubmitted] = useState(false);
 
  function updateField(field: string, value: string) {
    setForm(prev => ({ ...prev, [field]: value }));
  }
 
  function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    setSubmitted(true);
  }
 
  if (submitted) {
    return (
      <div className="rounded bg-green-50 p-4 text-green-800">
        Bem-vindo(a), {form.name}! Enviamos uma confirmação para {form.email}.
      </div>
    );
  }
 
  return (
    <form onSubmit={handleSubmit} className="max-w-sm space-y-3 rounded border p-4">
      <div>
        <label htmlFor="name" className="block text-sm font-medium">Nome</label>
        <input
          id="name"
          value={form.name}
          onChange={e => updateField("name", e.target.value)}
          required
          className="w-full rounded border px-3 py-1"
        />
      </div>
      <div>
        <label htmlFor="email" className="block text-sm font-medium">Email</label>
        <input
          id="email"
          type="email"
          value={form.email}
          onChange={e => updateField("email", e.target.value)}
          required
          className="w-full rounded border px-3 py-1"
        />
      </div>
      <div>
        <label htmlFor="role" className="block text-sm font-medium">Função</label>
        <select
          id="role"
          value={form.role}
          onChange={e => updateField("role", e.target.value)}
          className="w-full rounded border px-3 py-1"
        >
          <option value="viewer">Visualizador</option>
          <option value="editor">Editor</option>
          <option value="admin">Admin</option>
        </select>
      </div>
      <button type="submit" className="rounded bg-blue-600 px-4 py-2 text-white">
        Inscrever-se
      </button>
    </form>
  );
}
 
// --- Ação de Formulário do React 19 com useActionState ---
 
interface FormState {
  message: string;
  error: boolean;
}
 
async function submitFeedback(
  prevState: FormState,
  formData: FormData
): Promise<FormState> {
  const feedback = formData.get("feedback") as string;
 
  // Simula atraso do servidor
  await new Promise(resolve => setTimeout(resolve, 1000));
 
  if (feedback.length < 10) {
    return { message: "O feedback deve ter pelo menos 10 caracteres.", error: true };
  }
 
  return { message: `Obrigado pelo seu feedback!`, error: false };
}
 
export function FeedbackForm() {
  const [state, formAction, isPending] = useActionState(submitFeedback, {
    message: "",
    error: false,
  });
 
  return (
    <form action={formAction} className="max-w-sm space-y-3 rounded border p-4">
      <label htmlFor="feedback" className="block text-sm font-medium">
        Seu Feedback
      </label>
      <textarea
        id="feedback"
        name="feedback"
        required
        rows={3}
        className="w-full rounded border px-3 py-1"
        placeholder="Diga-nos o que você pensa..."
      />
 
      {state.message && (
        <p className={state.error ? "text-sm text-red-600" : "text-sm text-green-600"}>
          {state.message}
        </p>
      )}
 
      <button
        type="submit"
        disabled={isPending}
        className="rounded bg-blue-600 px-4 py-2 text-white disabled:opacity-50"
      >
        {isPending ? "Enviando..." : "Enviar Feedback"}
      </button>
    </form>
  );
}

O que isso demonstra:

Formulário controlado com value + onChange para cada input
useActionState (React 19) gerenciando o estado de envio do formulário, indicador de pendência e validação
API FormData para ler valores do formulário sem estado controlado
Combinação acessível de label + htmlFor
Botão de envio desabilitado durante a ação assíncrona

Mergulho Profundo

Como Funciona

Componentes controlados mantêm os valores de entrada no estado do React - o componente é a fonte da verdade, e a entrada reflete value em cada renderização
Componentes não controlados deixam o DOM segurar o valor - você o lê sob demanda via ref ou FormData
Ações de formulário do React 19 permitem que você passe uma função async para <form action={fn}>. O React lida com o envio, fornece isPending e se integra com useActionState para gerenciar valores de retorno
useActionState(actionFn, initialState) retorna [state, wrappedAction, isPending] - ele chama actionFn(prevState, formData) no envio e atualiza o estado com o resultado

Controlado vs. Não Controlado vs. Ações

Abordagem	Fonte da Verdade	Melhor Para
Controlado (`value` + `onChange`)	Estado do React	Validação em tempo real, campos condicionais, entradas interdependentes complexas
Não Controlado (`defaultValue` + ref)	DOM	Formulários simples, integrações de terceiros, entradas sensíveis ao desempenho
Ações de Formulário (React 19)	FormData	Mutações do lado do servidor, melhoria progressiva, redução de estado do cliente

Parâmetros e Valores de Retorno

useActionState:

Parâmetro	Tipo	Descrição
`action`	`(prevState: T, formData: FormData) => T or Promise<T>`	Função chamada no envio do formulário
`initialState`	`T`	Estado inicial antes do primeiro envio
`permalink?`	`string`	URL opcional para melhoria progressiva com SSR

Retorno	Tipo	Descrição
`state`	`T`	Estado atual (atualizado após a conclusão da ação)
`formAction`	`(formData: FormData) => void`	Ação encapsulada para passar para `<form action>`
`isPending`	`boolean`	`true` enquanto a ação estiver em execução

Variações

Não Controlado com FormData (sem necessidade de useState):

function SearchForm() {
  function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    const query = formData.get("query") as string;
    router.push(`/search?q=${encodeURIComponent(query)}`);
  }
 
  return (
    <form onSubmit={handleSubmit}>
      <input name="query" defaultValue="" />
      <button type="submit">Pesquisar</button>
    </form>
  );
}

useFormStatus para botões de envio aninhados:

import { useFormStatus } from "react-dom";
 
function SubmitButton() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? "Salvando..." : "Salvar"}
    </button>
  );
}
 
// Uso - SubmitButton deve ser um filho de um <form>
<form action={saveAction}>
  <input name="title" />
  <SubmitButton />
</form>

Atualizações otimistas com useOptimistic:

import { useOptimistic } from "react";
 
function MessageList({ messages, sendAction }: Props) {
  const [optimisticMessages, addOptimistic] = useOptimistic(
    messages,
    (state, newMessage: string) => [
      ...state,
      { id: "temp", text: newMessage, sending: true },
    ]
  );
 
  async function handleSubmit(formData: FormData) {
    const text = formData.get("message") as string;
    addOptimistic(text);
    await sendAction(formData);
  }
 
  return (
    <form action={handleSubmit}>
      <ul>
        {optimisticMessages.map(msg => (
          <li key={msg.id} style={{ opacity: msg.sending ? 0.5 : 1 }}>
            {msg.text}
          </li>
        ))}
      </ul>
      <input name="message" />
      <button type="submit">Enviar</button>
    </form>
  );
}

Notas de TypeScript

// Tipando onChange para diferentes tipos de input
function handleChange(e: React.ChangeEvent<HTMLInputElement>) { ... }
function handleSelectChange(e: React.ChangeEvent<HTMLSelectElement>) { ... }
function handleTextareaChange(e: React.ChangeEvent<HTMLTextAreaElement>) { ... }
 
// Tipando o estado da ação do formulário
interface ActionState {
  success: boolean;
  errors: Record<string, string>;
}
 
async function myAction(
  prev: ActionState,
  formData: FormData
): Promise<ActionState> {
  // validar e retornar novo estado
}

Armadilhas

Falta de value ou onChange - Definir value sem onChange torna o input somente leitura. O React avisa sobre isso. Correção: Adicione um manipulador onChange ou use defaultValue para inputs não controlados.
defaultValue não atualiza - Alterar defaultValue após a montagem não tem efeito, pois ele apenas define o valor inicial do DOM. Correção: Use value controlado se precisar que o React impulsione as atualizações, ou adicione uma key para remontar o input.
checked de Checkbox e Rádio - Estes usam checked / defaultChecked, não value / defaultValue. Correção: <input type="checkbox" checked={isOn} onChange={e => setIsOn(e.target.checked)} />.
Number inputs retornam strings - e.target.value é sempre uma string, mesmo para <input type="number">. Correção: Analise explicitamente: Number(e.target.value) ou parseInt(e.target.value, 10).
useFormStatus fora de um formulário - useFormStatus só funciona quando o componente é renderizado como um descendente de um <form>. Chamá-lo no mesmo componente que renderiza o <form> retorna dados desatualizados. Correção: Extraia o botão de envio para um componente filho.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
React Hook Form	Validação complexa, muitos campos, formulários críticos de desempenho	Formulários simples com 1-3 campos
Zod + Server Actions	Mutações de servidor validadas por esquema em Next.js	Formulários apenas do lado do cliente sem servidor
Formik	Projetos legados que já o utilizam	Novos projetos (React Hook Form é mais leve)
`<dialog>` nativo + `<form method="dialog">`	Diálogos de confirmação modais	Coleta de dados de vários campos

FAQs

Qual é a diferença entre inputs controlados e não controlados?

Controlados: O estado do React impulsiona o input via value + onChange - o React é a fonte da verdade
Não Controlados: O DOM segura o valor via defaultValue - leia sob demanda com uma ref ou FormData
Use controlados para validação em tempo real; não controlados para formulários simples ou entradas sensíveis ao desempenho

O que são ações de formulário do React 19?

O que é useActionState e como funciona?

Por que meu input controlado está somente leitura?

Por que mudar defaultValue não atualiza meu input?

Como lidar com checkboxes e radio buttons?

Use checked / defaultChecked em vez de value / defaultValue:

<input
  type="checkbox"
  checked={isEnabled}
  onChange={e => setIsEnabled(e.target.checked)}
/>

Como obter um número de um input numérico?

e.target.value é sempre uma string, mesmo para <input type="number">. Analise explicitamente: Number(e.target.value) ou parseInt(e.target.value, 10).

O que é useFormStatus e onde posso usá-lo?

Como lidar com vários campos de formulário sem useState separado para cada um?

Use um único objeto de estado e uma função de atualização genérica:

const [form, setForm] = useState({ name: "", email: "" });
function updateField(field: string, value: string) {
  setForm(prev => ({ ...prev, [field]: value }));
}

Quando devo usar uma biblioteca de formulários como React Hook Form em vez disso?

Mais de 3-5 campos com regras de validação
Validação interdependente complexa (campo B depende do campo A)
Formulários críticos de desempenho onde re-renderizações por pressionamento de tecla importam
Para formulários simples com 1-3 campos, inputs controlados simples ou ações de formulário são suficientes

Como implementar atualizações otimistas com formulários no React 19?

Use useOptimistic para mostrar imediatamente o resultado esperado enquanto a ação processa. Se a ação falhar, o React reverte automaticamente para o estado real.

Como tornar os formulários acessíveis?

Emparelhe cada input com um <label htmlFor="id"> correspondente ao id do input
Use required, aria-describedby para mensagens de erro e aria-invalid para campos inválidos
Certifique-se de que as mensagens de erro sejam anunciadas para leitores de tela

Relacionado

Eventos - manipulação geral de eventos em que os formulários se baseiam
Refs - acesso a valores de input não controlados
useState - alimentando inputs controlados
Componentes - compondo componentes de campo de formulário

Formulários

Buscar na documentação

Formulários