Ações de Formulário - Conecte funções assíncronas a formulários com estado de pendência e erro integrados

Q: O que useActionState retorna e como usá-lo?

Ele retorna [state, wrappedAction, isPending] state é atualizado a cada vez que a ação é concluída, com base no que a ação retorna wrappedAction é passado para e isPending indica se a ação está em execução no momento

Q: De onde é importado useFormStatus e como ele difere do isPending de useActionState?

useFormStatus é importado de "react-dom", enquanto useActionState é de "react" useFormStatus deve ser chamado de um componente renderizado dentro de um (um descendente) O isPending de useActionState está disponível no mesmo componente que renderiza o formulário

Q: Posso ter múltiplos botões de envio com ações diferentes no mesmo formulário?

Sim. Use o atributo formAction em botões individuais:

Q: Armadilha: Por que useFormStatus sempre retorna pending: false no meu componente?

useFormStatus deve ser chamado de um descendente do elemento , não do mesmo componente que o renderiza Extraia o botão de envio para um componente filho separado que chama useFormStatus

Q: Como tipar o hook useActionState em TypeScript?

A assinatura da função de ação é (previousState: State, formData: FormData) => State | Promise.

Receita

"use client";
 
import { useActionState } from "react";
import { useFormStatus } from "react-dom";
 
async function subscribe(_prev: string, formData: FormData): Promise<string> {
  const email = formData.get("email") as string;
  const res = await fetch("/api/subscribe", {
    method: "POST",
    body: JSON.stringify({ email }),
  });
  if (!res.ok) return "Algo deu errado.";
  return "Inscrito!";
}
 
function SubmitButton() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? "Inscrevendo..." : "Inscrever-se"}
    </button>
  );
}
 
export default function NewsletterForm() {
  const [message, formAction, isPending] = useActionState(subscribe, "");
 
  return (
    <form action={formAction}>
      <input name="email" type="email" required placeholder="voce@exemplo.com" />
      <SubmitButton />
      {message && <p>{message}</p>}
    </form>
  );
}

Quando usar isso: Sempre que você tiver um formulário que envia dados -- cadastros, buscas, operações CRUD. As ações de formulário substituem o padrão manual onSubmit + preventDefault + useState.

Exemplo de Trabalho

// Um formulário de contato com validação, exibição de erros e aprimoramento progressivo
"use client";
 
import { useActionState } from "react";
import { useFormStatus } from "react-dom";
 
type FormState = {
  success: boolean;
  errors: Record<string, string>;
  message: string;
};
 
const initialState: FormState = {
  success: false,
  errors: {},
  message: "",
};
 
async function submitContact(_prev: FormState, formData: FormData): Promise<FormState> {
  const name = formData.get("name") as string;
  const email = formData.get("email") as string;
  const body = formData.get("body") as string;
 
  // Validação no lado do cliente
  const errors: Record<string, string> = {};
  if (!name || name.length < 2) errors.name = "O nome deve ter pelo menos 2 caracteres.";
  if (!email || !email.includes("@")) errors.email = "Por favor, insira um e-mail válido.";
  if (!body || body.length < 10) errors.body = "A mensagem deve ter pelo menos 10 caracteres.";
 
  if (Object.keys(errors).length > 0) {
    return { success: false, errors, message: "Por favor, corrija os erros abaixo." };
  }
 
  try {
    const res = await fetch("/api/contact", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ name, email, body }),
    });
 
    if (!res.ok) throw new Error("Erro do servidor");
 
    return { success: true, errors: {}, message: "Mensagem enviada! Entraremos em contato." };
  } catch {
    return { success: false, errors: {}, message: "Falha ao enviar. Por favor, tente novamente." };
  }
}
 
function FieldError({ error }: { error?: string }) {
  if (!error) return null;
  return <p className="text-red-500 text-sm mt-1">{error}</p>;
}
 
function SubmitButton() {
  const { pending } = useFormStatus();
  return (
    <button
      type="submit"
      disabled={pending}
      className="bg-blue-600 text-white px-4 py-2 rounded disabled:opacity-50"
    >
      {pending ? "Enviando..." : "Enviar Mensagem"}
    </button>
  );
}
 
export default function ContactForm() {
  const [state, formAction, isPending] = useActionState(submitContact, initialState);
 
  return (
    <form action={formAction} className="space-y-4 max-w-md">
      <div>
        <label htmlFor="name">Nome</label>
        <input id="name" name="name" className="border w-full p-2 rounded" />
        <FieldError error={state.errors.name} />
      </div>
 
      <div>
        <label htmlFor="email">E-mail</label>
        <input id="email" name="email" type="email" className="border w-full p-2 rounded" />
        <FieldError error={state.errors.email} />
      </div>
 
      <div>
        <label htmlFor="body">Mensagem</label>
        <textarea id="body" name="body" rows={4} className="border w-full p-2 rounded" />
        <FieldError error={state.errors.body} />
      </div>
 
      <SubmitButton />
 
      {state.message && (
        <p className={state.success ? "text-green-600" : "text-red-600"}>
          {state.message}
        </p>
      )}
    </form>
  );
}

O que isso demonstra:

useActionState gerenciando o estado do formulário entre envios (erros, mensagem de sucesso)
useFormStatus em um componente filho para mostrar o estado de pendência no botão de envio
Exibição de erros em nível de campo a partir do valor de retorno da ação
Aprimoramento progressivo -- o formulário funciona sem JavaScript se combinado com uma ação de servidor

Mergulho Profundo

Como Funciona

<form action={fn}> -- O React 19 estende o atributo nativo action para aceitar funções assíncronas. Quando o formulário é enviado, o React chama fn(formData) e gerencia o ciclo de vida de pendência.
useActionState(action, initialState, permalink?) -- Encapsula uma função de ação e retorna [state, wrappedAction, isPending]. Cada vez que o formulário é enviado, action(prevState, formData) é chamado e o valor retornado se torna o novo state. O parâmetro opcional permalink permite o aprimoramento progressivo para ações de servidor.
useFormStatus() -- Deve ser chamado de um componente renderizado dentro de um <form>. Retorna { pending, data, method, action } refletindo o estado de envio do formulário pai mais próximo.
Aprimoramento progressivo -- Ao usar ações de servidor com useActionState, os formulários podem funcionar antes que o JavaScript seja carregado. O argumento permalink especifica para onde redirecionar após a conclusão da ação do servidor no caso sem JS.
isPending de useActionState reflete se a ação está atualmente em execução. Isso está disponível no mesmo componente que chama useActionState, ao contrário de useFormStatus, que só funciona em descendentes.

Variações

Múltiplos botões de envio com ações diferentes:

"use client";
 
import { useActionState } from "react";
 
export default function ItemForm() {
  const [saveResult, saveAction] = useActionState(saveItem, null);
  const [deleteResult, deleteAction] = useActionState(deleteItem, null);
 
  return (
    <form>
      <input name="name" />
      <button formAction={saveAction}>Salvar</button>
      <button formAction={deleteAction}>Excluir</button>
    </form>
  );
}

Usando useFormStatus para um indicador de carregamento global:

"use client";
 
import { useFormStatus } from "react-dom";
 
export function FormProgress() {
  const { pending, data } = useFormStatus();
 
  if (!pending) return null;
 
  return (
    <div className="fixed top-0 left-0 w-full h-1 bg-blue-500 animate-pulse" />
  );
}
 
// Use dentro de qualquer formulário
<form action={myAction}>
  <FormProgress />
  {/* ... campos ... */}
</form>

Redefinir formulário após o sucesso:

"use client";
 
import { useActionState, useRef, useEffect } from "react";
 
export default function ResetableForm() {
  const [state, formAction, isPending] = useActionState(submitData, { success: false });
  const formRef = useRef<HTMLFormElement>(null);
 
  useEffect(() => {
    if (state.success) {
      formRef.current?.reset();
    }
  }, [state]);
 
  return (
    <form ref={formRef} action={formAction}>
      <input name="item" required />
      <button type="submit" disabled={isPending}>Adicionar</button>
    </form>
  );
}

Notas de TypeScript

useActionState é genérico: useActionState<State>(fn: (prev: State, formData: FormData) => Promise<State>, initial: State).
useFormStatus retorna { pending: boolean; data: FormData | null; method: string; action: string | ((formData: FormData) => void) | null }.
A assinatura da função de ação é (previousState: State, formData: FormData) => State | Promise<State>.
O parâmetro permalink em useActionState é tipado como string | undefined.

Armadilhas

useFormStatus deve estar dentro de um descendente de <form> -- Chamá-lo no mesmo componente que renderiza a tag <form> sempre retorna { pending: false }. Correção: Extraia o botão de envio para um componente filho.
O valor de retorno da ação substitui o estado inteiramente -- Diferente de um reducer, o valor de retorno é todo o novo estado, não uma atualização parcial. Correção: Use o spread do estado anterior se quiser mesclar: return { ...prev, error: "..." }.
O formulário não é redefinido automaticamente -- Diferente de envios de formulário nativos, as ações de formulário do React não redefinem o formulário em caso de sucesso. Correção: Use um useRef no formulário e chame formRef.current?.reset() em um efeito.
Local de importação de useActionState -- É importado de "react", não de "react-dom". O antigo useFormState estava em "react-dom" e agora está obsoleto. Correção: import { useActionState } from "react".
Entradas não controladas após a ação -- Se sua ação retornar erros, mas você usar entradas não controladas, os valores do usuário são preservados no DOM. Se você usar entradas controladas, precisará restaurá-las a partir do estado. Correção: Prefira entradas não controladas com ações de formulário ou sincronize o estado a partir de formData.
Múltiplos formulários na mesma página -- Cada chamada de useActionState é independente. O envio de um formulário não afeta outro. Correção: Este é o comportamento esperado, mas esteja ciente de que useFormStatus reflete apenas o formulário ancestral mais próximo.

Alternativas

Abordagem	Quando escolher
Ações de Formulário + `useActionState`	Formulários padrão do React 19 com estado de pendência integrado
`react-hook-form`	Validação complexa no lado do cliente, arrays de campos, comportamento de observação
Formik	Projetos legados que já usam Formik
`onSubmit` manual + `fetch`	Controle total sobre o ciclo de vida da requisição, cabeçalhos personalizados
Apenas ação de servidor (sem estado do cliente)	Mutações simples que redirecionam após a conclusão
Conform	Aprimoramento progressivo com integração Zod para ações de servidor

FAQs

Qual é a diferença entre passar uma função para a ação do formulário e usar onSubmit?

<form action={fn}> permite que o React gerencie o estado de pendência, tratamento de erros e atualizações otimistas automaticamente
O padrão tradicional onSubmit + preventDefault + useState requer gerenciamento manual de estado
As ações de formulário também permitem o aprimoramento progressivo quando combinadas com ações de servidor

O que useActionState retorna e como usá-lo?

Ele retorna [state, wrappedAction, isPending]
state é atualizado a cada vez que a ação é concluída, com base no que a ação retorna
wrappedAction é passado para <form action={}> e isPending indica se a ação está em execução no momento

De onde é importado useFormStatus e como ele difere do isPending de useActionState?

useFormStatus é importado de "react-dom", enquanto useActionState é de "react"
useFormStatus deve ser chamado de um componente renderizado dentro de um <form> (um descendente)
O isPending de useActionState está disponível no mesmo componente que renderiza o formulário

Como exibir erros de validação em nível de campo com ações de formulário?

Retorne um objeto de erros da ação e renderize-o por campo:

async function submit(_prev: State, formData: FormData) {
  const errors: Record<string, string> = {};
  if (!formData.get("name")) errors.name = "Obrigatório";
  if (Object.keys(errors).length) return { errors };
  // ... salvar dados
  return { errors: {} };
}

Como redefinir um formulário após um envio bem-sucedido?

const formRef = useRef<HTMLFormElement>(null);
const [state, formAction] = useActionState(submit, initial);
 
useEffect(() => {
  if (state.success) formRef.current?.reset();
}, [state]);
 
<form ref={formRef} action={formAction}>...</form>

As ações de formulário do React não redefinem o formulário automaticamente, ao contrário dos envios de formulário nativos.

Posso ter múltiplos botões de envio com ações diferentes no mesmo formulário?

Sim. Use o atributo formAction em botões individuais:

<form>
  <input name="name" />
  <button formAction={saveAction}>Salvar</button>
  <button formAction={deleteAction}>Excluir</button>
</form>

O que é o parâmetro permalink em useActionState?

É um URL de string opcional que permite o aprimoramento progressivo para ações de servidor
Quando o JavaScript ainda não foi carregado, o formulário é enviado para este URL e a ação do servidor é executada
Após a conclusão, o navegador redireciona para o permalink

Armadilha: Por que useFormStatus sempre retorna pending: false no meu componente?

useFormStatus deve ser chamado de um descendente do elemento <form>, não do mesmo componente que o renderiza
Extraia o botão de envio para um componente filho separado que chama useFormStatus

Armadilha: O valor de retorno da ação substitui o estado inteiramente em vez de mesclar. Como lidar com atualizações parciais?

Diferente de um reducer, o valor de retorno é o estado novo inteiro, não uma atualização parcial
Use o spread do estado anterior se quiser mesclar: return { ...prev, error: "..." }
Projete a forma do seu estado para ser totalmente retornada de cada caminho de ação

Como tipar o hook useActionState em TypeScript?

useActionState<State>(
  fn: (prev: State, formData: FormData) => Promise<State>,
  initial: State
): [State, (formData: FormData) => void, boolean]

A assinatura da função de ação é (previousState: State, formData: FormData) => State | Promise<State>.

Como useFormStatus é tipado em TypeScript?

Retorna { pending: boolean; data: FormData | null; method: string; action: string | ((formData: FormData) => void) | null }
data é o FormData que está sendo enviado (ou null quando não está pendente)
method reflete o método HTTP do formulário

Devo usar entradas controladas ou não controladas com ações de formulário?

Prefira entradas não controladas com ações de formulário -- os valores do usuário são preservados no DOM entre os envios
Se estiver usando entradas controladas, você deve restaurar seus valores a partir do estado quando a ação retornar erros
Entradas não controladas reduzem o código repetitivo e funcionam naturalmente com FormData

Relacionado

Ações de Servidor -- Funções de servidor que as ações de formulário podem invocar
useOptimistic -- Adicionando atualizações otimistas a envios de formulário
Visão Geral -- Lista completa de recursos do React 19

Receita

"use client";
 
import { useActionState } from "react";
import { useFormStatus } from "react-dom";
 
async function subscribe(_prev: string, formData: FormData): Promise<string> {
  const email = formData.get("email") as string;
  const res = await fetch("/api/subscribe", {
    method: "POST",
    body: JSON.stringify({ email }),
  });
  if (!res.ok) return "Algo deu errado.";
  return "Inscrito!";
}
 
function SubmitButton() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? "Inscrevendo..." : "Inscrever-se"}
    </button>
  );
}
 
export default function NewsletterForm() {
  const [message, formAction, isPending] = useActionState(subscribe, "");
 
  return (
    <form action={formAction}>
      <input name="email" type="email" required placeholder="voce@exemplo.com" />
      <SubmitButton />
      {message && <p>{message}</p>}
    </form>
  );
}

Exemplo de Trabalho

// Um formulário de contato com validação, exibição de erros e aprimoramento progressivo
"use client";
 
import { useActionState } from "react";
import { useFormStatus } from "react-dom";
 
type FormState = {
  success: boolean;
  errors: Record<string, string>;
  message: string;
};
 
const initialState: FormState = {
  success: false,
  errors: {},
  message: "",
};
 
async function submitContact(_prev: FormState, formData: FormData): Promise<FormState> {
  const name = formData.get("name") as string;
  const email = formData.get("email") as string;
  const body = formData.get("body") as string;
 
  // Validação no lado do cliente
  const errors: Record<string, string> = {};
  if (!name || name.length < 2) errors.name = "O nome deve ter pelo menos 2 caracteres.";
  if (!email || !email.includes("@")) errors.email = "Por favor, insira um e-mail válido.";
  if (!body || body.length < 10) errors.body = "A mensagem deve ter pelo menos 10 caracteres.";
 
  if (Object.keys(errors).length > 0) {
    return { success: false, errors, message: "Por favor, corrija os erros abaixo." };
  }
 
  try {
    const res = await fetch("/api/contact", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ name, email, body }),
    });
 
    if (!res.ok) throw new Error("Erro do servidor");
 
    return { success: true, errors: {}, message: "Mensagem enviada! Entraremos em contato." };
  } catch {
    return { success: false, errors: {}, message: "Falha ao enviar. Por favor, tente novamente." };
  }
}
 
function FieldError({ error }: { error?: string }) {
  if (!error) return null;
  return <p className="text-red-500 text-sm mt-1">{error}</p>;
}
 
function SubmitButton() {
  const { pending } = useFormStatus();
  return (
    <button
      type="submit"
      disabled={pending}
      className="bg-blue-600 text-white px-4 py-2 rounded disabled:opacity-50"
    >
      {pending ? "Enviando..." : "Enviar Mensagem"}
    </button>
  );
}
 
export default function ContactForm() {
  const [state, formAction, isPending] = useActionState(submitContact, initialState);
 
  return (
    <form action={formAction} className="space-y-4 max-w-md">
      <div>
        <label htmlFor="name">Nome</label>
        <input id="name" name="name" className="border w-full p-2 rounded" />
        <FieldError error={state.errors.name} />
      </div>
 
      <div>
        <label htmlFor="email">E-mail</label>
        <input id="email" name="email" type="email" className="border w-full p-2 rounded" />
        <FieldError error={state.errors.email} />
      </div>
 
      <div>
        <label htmlFor="body">Mensagem</label>
        <textarea id="body" name="body" rows={4} className="border w-full p-2 rounded" />
        <FieldError error={state.errors.body} />
      </div>
 
      <SubmitButton />
 
      {state.message && (
        <p className={state.success ? "text-green-600" : "text-red-600"}>
          {state.message}
        </p>
      )}
    </form>
  );
}

O que isso demonstra:

useActionState gerenciando o estado do formulário entre envios (erros, mensagem de sucesso)
useFormStatus em um componente filho para mostrar o estado de pendência no botão de envio
Exibição de erros em nível de campo a partir do valor de retorno da ação
Aprimoramento progressivo -- o formulário funciona sem JavaScript se combinado com uma ação de servidor

Mergulho Profundo

Como Funciona

<form action={fn}> -- O React 19 estende o atributo nativo action para aceitar funções assíncronas. Quando o formulário é enviado, o React chama fn(formData) e gerencia o ciclo de vida de pendência.
useActionState(action, initialState, permalink?) -- Encapsula uma função de ação e retorna [state, wrappedAction, isPending]. Cada vez que o formulário é enviado, action(prevState, formData) é chamado e o valor retornado se torna o novo state. O parâmetro opcional permalink permite o aprimoramento progressivo para ações de servidor.
useFormStatus() -- Deve ser chamado de um componente renderizado dentro de um <form>. Retorna { pending, data, method, action } refletindo o estado de envio do formulário pai mais próximo.
Aprimoramento progressivo -- Ao usar ações de servidor com useActionState, os formulários podem funcionar antes que o JavaScript seja carregado. O argumento permalink especifica para onde redirecionar após a conclusão da ação do servidor no caso sem JS.
isPending de useActionState reflete se a ação está atualmente em execução. Isso está disponível no mesmo componente que chama useActionState, ao contrário de useFormStatus, que só funciona em descendentes.

Variações

Múltiplos botões de envio com ações diferentes:

"use client";
 
import { useActionState } from "react";
 
export default function ItemForm() {
  const [saveResult, saveAction] = useActionState(saveItem, null);
  const [deleteResult, deleteAction] = useActionState(deleteItem, null);
 
  return (
    <form>
      <input name="name" />
      <button formAction={saveAction}>Salvar</button>
      <button formAction={deleteAction}>Excluir</button>
    </form>
  );
}

Usando useFormStatus para um indicador de carregamento global:

"use client";
 
import { useFormStatus } from "react-dom";
 
export function FormProgress() {
  const { pending, data } = useFormStatus();
 
  if (!pending) return null;
 
  return (
    <div className="fixed top-0 left-0 w-full h-1 bg-blue-500 animate-pulse" />
  );
}
 
// Use dentro de qualquer formulário
<form action={myAction}>
  <FormProgress />
  {/* ... campos ... */}
</form>

Redefinir formulário após o sucesso:

"use client";
 
import { useActionState, useRef, useEffect } from "react";
 
export default function ResetableForm() {
  const [state, formAction, isPending] = useActionState(submitData, { success: false });
  const formRef = useRef<HTMLFormElement>(null);
 
  useEffect(() => {
    if (state.success) {
      formRef.current?.reset();
    }
  }, [state]);
 
  return (
    <form ref={formRef} action={formAction}>
      <input name="item" required />
      <button type="submit" disabled={isPending}>Adicionar</button>
    </form>
  );
}

Notas de TypeScript

useActionState é genérico: useActionState<State>(fn: (prev: State, formData: FormData) => Promise<State>, initial: State).
useFormStatus retorna { pending: boolean; data: FormData | null; method: string; action: string | ((formData: FormData) => void) | null }.
A assinatura da função de ação é (previousState: State, formData: FormData) => State | Promise<State>.
O parâmetro permalink em useActionState é tipado como string | undefined.

Armadilhas

useFormStatus deve estar dentro de um descendente de <form> -- Chamá-lo no mesmo componente que renderiza a tag <form> sempre retorna { pending: false }. Correção: Extraia o botão de envio para um componente filho.
O valor de retorno da ação substitui o estado inteiramente -- Diferente de um reducer, o valor de retorno é todo o novo estado, não uma atualização parcial. Correção: Use o spread do estado anterior se quiser mesclar: return { ...prev, error: "..." }.
O formulário não é redefinido automaticamente -- Diferente de envios de formulário nativos, as ações de formulário do React não redefinem o formulário em caso de sucesso. Correção: Use um useRef no formulário e chame formRef.current?.reset() em um efeito.
Local de importação de useActionState -- É importado de "react", não de "react-dom". O antigo useFormState estava em "react-dom" e agora está obsoleto. Correção: import { useActionState } from "react".
Entradas não controladas após a ação -- Se sua ação retornar erros, mas você usar entradas não controladas, os valores do usuário são preservados no DOM. Se você usar entradas controladas, precisará restaurá-las a partir do estado. Correção: Prefira entradas não controladas com ações de formulário ou sincronize o estado a partir de formData.
Múltiplos formulários na mesma página -- Cada chamada de useActionState é independente. O envio de um formulário não afeta outro. Correção: Este é o comportamento esperado, mas esteja ciente de que useFormStatus reflete apenas o formulário ancestral mais próximo.

Alternativas

Abordagem	Quando escolher
Ações de Formulário + `useActionState`	Formulários padrão do React 19 com estado de pendência integrado
`react-hook-form`	Validação complexa no lado do cliente, arrays de campos, comportamento de observação
Formik	Projetos legados que já usam Formik
`onSubmit` manual + `fetch`	Controle total sobre o ciclo de vida da requisição, cabeçalhos personalizados
Apenas ação de servidor (sem estado do cliente)	Mutações simples que redirecionam após a conclusão
Conform	Aprimoramento progressivo com integração Zod para ações de servidor

FAQs

Qual é a diferença entre passar uma função para a ação do formulário e usar onSubmit?

<form action={fn}> permite que o React gerencie o estado de pendência, tratamento de erros e atualizações otimistas automaticamente
O padrão tradicional onSubmit + preventDefault + useState requer gerenciamento manual de estado
As ações de formulário também permitem o aprimoramento progressivo quando combinadas com ações de servidor

O que useActionState retorna e como usá-lo?

Ele retorna [state, wrappedAction, isPending]
state é atualizado a cada vez que a ação é concluída, com base no que a ação retorna
wrappedAction é passado para <form action={}> e isPending indica se a ação está em execução no momento

De onde é importado useFormStatus e como ele difere do isPending de useActionState?

useFormStatus é importado de "react-dom", enquanto useActionState é de "react"
useFormStatus deve ser chamado de um componente renderizado dentro de um <form> (um descendente)
O isPending de useActionState está disponível no mesmo componente que renderiza o formulário

Como exibir erros de validação em nível de campo com ações de formulário?

Retorne um objeto de erros da ação e renderize-o por campo:

async function submit(_prev: State, formData: FormData) {
  const errors: Record<string, string> = {};
  if (!formData.get("name")) errors.name = "Obrigatório";
  if (Object.keys(errors).length) return { errors };
  // ... salvar dados
  return { errors: {} };
}

Como redefinir um formulário após um envio bem-sucedido?

const formRef = useRef<HTMLFormElement>(null);
const [state, formAction] = useActionState(submit, initial);
 
useEffect(() => {
  if (state.success) formRef.current?.reset();
}, [state]);
 
<form ref={formRef} action={formAction}>...</form>

As ações de formulário do React não redefinem o formulário automaticamente, ao contrário dos envios de formulário nativos.

Posso ter múltiplos botões de envio com ações diferentes no mesmo formulário?

Sim. Use o atributo formAction em botões individuais:

<form>
  <input name="name" />
  <button formAction={saveAction}>Salvar</button>
  <button formAction={deleteAction}>Excluir</button>
</form>

O que é o parâmetro permalink em useActionState?

É um URL de string opcional que permite o aprimoramento progressivo para ações de servidor
Quando o JavaScript ainda não foi carregado, o formulário é enviado para este URL e a ação do servidor é executada
Após a conclusão, o navegador redireciona para o permalink

Armadilha: Por que useFormStatus sempre retorna pending: false no meu componente?

useFormStatus deve ser chamado de um descendente do elemento <form>, não do mesmo componente que o renderiza
Extraia o botão de envio para um componente filho separado que chama useFormStatus

Armadilha: O valor de retorno da ação substitui o estado inteiramente em vez de mesclar. Como lidar com atualizações parciais?

Diferente de um reducer, o valor de retorno é o estado novo inteiro, não uma atualização parcial
Use o spread do estado anterior se quiser mesclar: return { ...prev, error: "..." }
Projete a forma do seu estado para ser totalmente retornada de cada caminho de ação

Como tipar o hook useActionState em TypeScript?

useActionState<State>(
  fn: (prev: State, formData: FormData) => Promise<State>,
  initial: State
): [State, (formData: FormData) => void, boolean]

A assinatura da função de ação é (previousState: State, formData: FormData) => State | Promise<State>.

Como useFormStatus é tipado em TypeScript?

Retorna { pending: boolean; data: FormData | null; method: string; action: string | ((formData: FormData) => void) | null }
data é o FormData que está sendo enviado (ou null quando não está pendente)
method reflete o método HTTP do formulário

Devo usar entradas controladas ou não controladas com ações de formulário?

Prefira entradas não controladas com ações de formulário -- os valores do usuário são preservados no DOM entre os envios
Se estiver usando entradas controladas, você deve restaurar seus valores a partir do estado quando a ação retornar erros
Entradas não controladas reduzem o código repetitivo e funcionam naturalmente com FormData

Relacionado

Ações de Servidor -- Funções de servidor que as ações de formulário podem invocar
useOptimistic -- Adicionando atualizações otimistas a envios de formulário
Visão Geral -- Lista completa de recursos do React 19

Ações de Formulário - Conecte funções assíncronas a formulários com estado de pendência e erro integrados

Buscar na documentação

Ações de Formulário - Conecte funções assíncronas a formulários com estado de pendência e erro integrados