Hook useActionState

Q: Qual é a diferença entre useActionState e o useFormState descontinuado?

React 19 renomeou useFormState para useActionState e adicionou isPending como o terceiro valor de retorno. Importe useActionState de "react", não useFormState de "react-dom". A API é, de outra forma, a mesma: função de ação, estado inicial e permalink opcional.

Q: Como useActionState fornece aprimoramento progressivo?

O formAction retornado pelo hook é compatível com . Isso significa que o formulário pode ser enviado mesmo antes que o JavaScript seja hidratado na página. Com ações de servidor no Next.js, o formulário funciona sem nenhum JavaScript do lado do cliente.

Q: Armadilha: O que acontece se minha função de ação não retornar um valor?

O estado se torna undefined após a submissão, o que pode quebrar sua UI. Sempre retorne o novo objeto de estado da função de ação. TypeScript avisará se o tipo de retorno não corresponder ao tipo de estado.

Q: Como isPending funciona internamente?

A ação é executada dentro de uma transição do React, então isPending se torna true sem bloquear a UI. Após a resolução da ação, o React atualiza o estado e define isPending como false. Você não precisa gerenciar o estado de carregamento manualmente.

Q: Como lidar com múltiplos botões de envio com ações diferentes?

Cada botão pode ter seu próprio atributo formAction apontando para uma ação diferente.

Q: Quando devo usar useActionState vs useState + useTransition manualmente?

Use useActionState para submissões de formulário onde você deseja aprimoramento progressivo e estado pendente automático. Use useState + useTransition para lógica de envio personalizada não vinculada a . useActionState reduz o código repetitivo combinando estado, pendente e ação em um único hook.

Gerencie o estado do formulário impulsionado por uma função de ação, com estado pendente integrado e aprimoramento progressivo.

Receita

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

const [state, formAction, isPending] = useActionState(action, initialState);
 
// assinatura da ação
async function action(previousState: State, formData: FormData): Promise<State> {
  // processar dados do formulário, retornar novo estado
}
 
// Usar em um formulário
<form action={formAction}>
  <input name="email" />
  <button disabled={isPending}>Enviar</button>
  {state.error && <p>{state.error}</p>}
</form>

Quando usar isso: Você tem um formulário que envia dados (para uma ação de servidor ou função assíncrona) e deseja que o React gerencie o estado de envio, o indicador pendente e o resultado - com aprimoramento progressivo (funciona sem JavaScript).

Exemplo de Trabalho

"use client";
 
import { useActionState } from "react";
 
interface FormState {
  message: string;
  error: string;
}
 
async function submitFeedback(
  prevState: FormState,
  formData: FormData
): Promise<FormState> {
  const feedback = formData.get("feedback") as string;
 
  if (!feedback || feedback.trim().length < 10) {
    return { message: "", error: "O feedback deve ter pelo menos 10 caracteres." };
  }
 
  // Simular atraso do servidor
  await new Promise((resolve) => setTimeout(resolve, 1000));
 
  return { message: `Obrigado pelo seu feedback!`, error: "" };
}
 
const initialState: FormState = { message: "", error: "" };
 
export function FeedbackForm() {
  const [state, formAction, isPending] = useActionState(submitFeedback, initialState);
 
  return (
    <form action={formAction} className="space-y-3 max-w-sm">
      <label className="block">
        <span className="text-sm font-medium">Seu Feedback</span>
        <textarea
          name="feedback"
          rows={3}
          className="mt-1 block w-full border rounded px-3 py-2"
          required
        />
      </label>
 
      <button
        type="submit"
        disabled={isPending}
        className="px-4 py-2 bg-blue-600 text-white rounded disabled:opacity-50"
      >
        {isPending ? "Enviando..." : "Enviar"}
      </button>
 
      {state.error && <p className="text-sm text-red-600">{state.error}</p>}
      {state.message && <p className="text-sm text-green-600">{state.message}</p>}
    </form>
  );
}

O que isso demonstra:

useActionState gerencia todo o ciclo de vida do formulário: ocioso, pendente, sucesso e erro
A ação recebe o estado anterior e FormData, retornando o próximo estado
isPending desabilita o botão e exibe texto de carregamento durante o envio
O formulário funciona com aprimoramento progressivo - ele pode enviar mesmo antes que o JavaScript seja carregado

Mergulho Profundo

Como Funciona

useActionState envolve sua função de ação e retorna uma ação compatível com formulários, o estado atual e um sinalizador pendente.
Quando o formulário é enviado, o React chama sua ação com o estado anterior e o FormData.
A ação é executada dentro de uma transição, então isPending se torna true sem bloquear a UI.
Após a resolução da ação, o React atualiza o estado com o valor retornado e define isPending como false.
O formAction retornado é compatível com o padrão <form action={}>, permitindo o aprimoramento progressivo.
Se usado com ações de servidor no Next.js, o formulário funciona antes que o JavaScript seja hidratado.

Parâmetros e Valores de Retorno

Parâmetro	Tipo	Descrição
`action`	`(prevState: S, formData: FormData) => S` ou `Promise<S>`	Função chamada na submissão do formulário
`initialState`	`S`	Estado inicial antes de qualquer submissão
`permalink`	`string` (opcional)	URL para aprimoramento progressivo (componentes de servidor)

Retorno	Tipo	Descrição
`state`	`S`	Estado atual (atualizado após cada ação ser concluída)
`formAction`	`(formData: FormData) => void`	Ação para passar para `<form action={}>` ou `<button formAction={}>`
`isPending`	`boolean`	`true` enquanto a ação estiver em execução

Variações

Com ação de servidor (Next.js App Router):

// app/actions.ts
"use server";
 
export async function createUser(prevState: FormState, formData: FormData) {
  const name = formData.get("name") as string;
  const user = await db.users.create({ data: { name } });
  return { success: true, error: "" };
}
 
// app/page.tsx
"use client";
import { useActionState } from "react";
import { createUser } from "./actions";
 
export function CreateUserForm() {
  const [state, formAction, isPending] = useActionState(createUser, {
    success: false,
    error: "",
  });
  return <form action={formAction}>...</form>;
}

Múltiplos botões de envio com formAction:

<form>
  <input name="item" />
  <button formAction={saveAction}>Salvar Rascunho</button>
  <button formAction={publishAction}>Publicar</button>
</form>

Ação assíncrona apenas do cliente:

async function loginAction(prev: LoginState, formData: FormData) {
  const res = await fetch("/api/login", {
    method: "POST",
    body: formData,
  });
  if (!res.ok) return { error: "Credenciais inválidas" };
  return { error: "" };
}

Notas TypeScript

// Digite o estado explicitamente para clareza
interface ActionState {
  success: boolean;
  error: string;
  data?: UserData;
}
 
// A ação deve corresponder ao tipo de estado
async function myAction(
  prevState: ActionState,
  formData: FormData
): Promise<ActionState> {
  // ...
  return { success: true, error: "" };
}
 
const [state, formAction, isPending] = useActionState(myAction, {
  success: false,
  error: "",
});
// state: ActionState

Armadilhas

Confusão com useFormState (descontinuado) - React 19 renomeou useFormState para useActionState e adicionou isPending como o terceiro valor de retorno. Correção: Use useActionState de "react", não useFormState de "react-dom".
A ação deve retornar o estado - Se sua ação não retornar um valor, o estado se tornará undefined após a submissão. Correção: Sempre retorne o novo estado da sua função de ação.
O estado é redefinido a cada submissão - O estado anterior é passado como o primeiro argumento; você deve mesclá-lo se quiser preservar os campos. Correção: Espalhe o estado anterior: return { ...prevState, error: "" }.
Usando fora de um formulário - useActionState é projetado para <form action={}>. Chamar formAction manualmente com FormData construído funciona, mas perde o aprimoramento progressivo. Correção: Prefira <form action={formAction}> para melhor compatibilidade.
Serialização de ação de servidor - O estado passado entre servidor e cliente deve ser serializável (sem funções, Dates, Maps). Correção: Use objetos simples com valores primitivos.

Alternativas

Alternativa	Use Quando	Não Use Quando
`useState` + `useTransition`	Lógica de envio personalizada não vinculada a `<form action={}>`	Você deseja aprimoramento progressivo
`useReducer`	Transições de estado complexas no lado do cliente sem submissão de formulário	Mudanças de estado são impulsionadas por ações de formulário
React Hook Form	Validação complexa, erros em nível de campo, formulários dinâmicos	Formulários simples com ações de servidor
Ação de servidor sem hook	Mutação de disparar e esquecer, nenhuma atualização de estado do cliente necessária	Você precisa exibir o resultado na UI

Por que usar useActionState em vez de fetch manual? useActionState fornece estado pendente, tratamento de erros e aprimoramento progressivo em um único hook - sem necessidade de conectar useState + useTransition + try/catch manualmente.

FAQs

Qual é a diferença entre useActionState e o useFormState descontinuado?

React 19 renomeou useFormState para useActionState e adicionou isPending como o terceiro valor de retorno.
Importe useActionState de "react", não useFormState de "react-dom".
A API é, de outra forma, a mesma: função de ação, estado inicial e permalink opcional.

Como useActionState fornece aprimoramento progressivo?

O formAction retornado pelo hook é compatível com <form action={}>.
Isso significa que o formulário pode ser enviado mesmo antes que o JavaScript seja hidratado na página.
Com ações de servidor no Next.js, o formulário funciona sem nenhum JavaScript do lado do cliente.

Por que a função de ação recebe previousState como seu primeiro argumento?

Permite atualizações incrementais de estado, semelhante a um padrão de reducer.
Você pode mesclar o estado anterior com novos dados: return { ...prevState, error: "" }.
Sem isso, você perderia os campos de estado existentes a cada submissão.

Armadilha: O que acontece se minha função de ação não retornar um valor?

O estado se torna undefined após a submissão, o que pode quebrar sua UI.
Sempre retorne o novo objeto de estado da função de ação.
TypeScript avisará se o tipo de retorno não corresponder ao tipo de estado.

Posso usar useActionState para formulários apenas do cliente sem ações de servidor?

async function loginAction(prev: LoginState, formData: FormData) {
  const res = await fetch("/api/login", {
    method: "POST",
    body: formData,
  });
  if (!res.ok) return { error: "Credenciais inválidas" };
  return { error: "" };
}
 
const [state, formAction, isPending] = useActionState(loginAction, { error: "" });

Sim. A ação pode ser qualquer função assíncrona, não apenas uma ação de servidor.

Como isPending funciona internamente?

A ação é executada dentro de uma transição do React, então isPending se torna true sem bloquear a UI.
Após a resolução da ação, o React atualiza o estado e define isPending como false.
Você não precisa gerenciar o estado de carregamento manualmente.

Como eu digito a ação e o estado com TypeScript?

interface ActionState {
  success: boolean;
  error: string;
}
 
async function myAction(
  prevState: ActionState,
  formData: FormData
): Promise<ActionState> {
  return { success: true, error: "" };
}
 
const [state, formAction, isPending] = useActionState(myAction, {
  success: false,
  error: "",
});
// state: ActionState

Armadilha: Posso passar valores não serializáveis (funções, Dates, Maps) no estado?

Não. Ao usar ações de servidor, o estado é serializado entre servidor e cliente.
Apenas objetos simples com valores primitivos (strings, números, booleanos, arrays) são seguros.
Funções, objetos Date, Map e Set falharão durante a serialização.

Como lidar com múltiplos botões de envio com ações diferentes?

<form>
  <input name="item" />
  <button formAction={saveDraftAction}>Salvar Rascunho</button>
  <button formAction={publishAction}>Publicar</button>
</form>

Cada botão pode ter seu próprio atributo formAction apontando para uma ação diferente.

Quando devo usar useActionState vs useState + useTransition manualmente?

Use useActionState para submissões de formulário onde você deseja aprimoramento progressivo e estado pendente automático.
Use useState + useTransition para lógica de envio personalizada não vinculada a <form action={}>.
useActionState reduz o código repetitivo combinando estado, pendente e ação em um único hook.

Relacionado

useOptimistic - exibe o estado otimista enquanto a ação está pendente
useTransition - useActionState usa transições internamente
use - primitivo do React 19 para consumir promises
useReducer - padrão semelhante, mas para máquinas de estado do lado do cliente

Receita

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

const [state, formAction, isPending] = useActionState(action, initialState);
 
// assinatura da ação
async function action(previousState: State, formData: FormData): Promise<State> {
  // processar dados do formulário, retornar novo estado
}
 
// Usar em um formulário
<form action={formAction}>
  <input name="email" />
  <button disabled={isPending}>Enviar</button>
  {state.error && <p>{state.error}</p>}
</form>

Exemplo de Trabalho

"use client";
 
import { useActionState } from "react";
 
interface FormState {
  message: string;
  error: string;
}
 
async function submitFeedback(
  prevState: FormState,
  formData: FormData
): Promise<FormState> {
  const feedback = formData.get("feedback") as string;
 
  if (!feedback || feedback.trim().length < 10) {
    return { message: "", error: "O feedback deve ter pelo menos 10 caracteres." };
  }
 
  // Simular atraso do servidor
  await new Promise((resolve) => setTimeout(resolve, 1000));
 
  return { message: `Obrigado pelo seu feedback!`, error: "" };
}
 
const initialState: FormState = { message: "", error: "" };
 
export function FeedbackForm() {
  const [state, formAction, isPending] = useActionState(submitFeedback, initialState);
 
  return (
    <form action={formAction} className="space-y-3 max-w-sm">
      <label className="block">
        <span className="text-sm font-medium">Seu Feedback</span>
        <textarea
          name="feedback"
          rows={3}
          className="mt-1 block w-full border rounded px-3 py-2"
          required
        />
      </label>
 
      <button
        type="submit"
        disabled={isPending}
        className="px-4 py-2 bg-blue-600 text-white rounded disabled:opacity-50"
      >
        {isPending ? "Enviando..." : "Enviar"}
      </button>
 
      {state.error && <p className="text-sm text-red-600">{state.error}</p>}
      {state.message && <p className="text-sm text-green-600">{state.message}</p>}
    </form>
  );
}

O que isso demonstra:

useActionState gerencia todo o ciclo de vida do formulário: ocioso, pendente, sucesso e erro
A ação recebe o estado anterior e FormData, retornando o próximo estado
isPending desabilita o botão e exibe texto de carregamento durante o envio
O formulário funciona com aprimoramento progressivo - ele pode enviar mesmo antes que o JavaScript seja carregado

Mergulho Profundo

Como Funciona

useActionState envolve sua função de ação e retorna uma ação compatível com formulários, o estado atual e um sinalizador pendente.
Quando o formulário é enviado, o React chama sua ação com o estado anterior e o FormData.
A ação é executada dentro de uma transição, então isPending se torna true sem bloquear a UI.
Após a resolução da ação, o React atualiza o estado com o valor retornado e define isPending como false.
O formAction retornado é compatível com o padrão <form action={}>, permitindo o aprimoramento progressivo.
Se usado com ações de servidor no Next.js, o formulário funciona antes que o JavaScript seja hidratado.

Parâmetros e Valores de Retorno

Parâmetro	Tipo	Descrição
`action`	`(prevState: S, formData: FormData) => S` ou `Promise<S>`	Função chamada na submissão do formulário
`initialState`	`S`	Estado inicial antes de qualquer submissão
`permalink`	`string` (opcional)	URL para aprimoramento progressivo (componentes de servidor)

Retorno	Tipo	Descrição
`state`	`S`	Estado atual (atualizado após cada ação ser concluída)
`formAction`	`(formData: FormData) => void`	Ação para passar para `<form action={}>` ou `<button formAction={}>`
`isPending`	`boolean`	`true` enquanto a ação estiver em execução

Variações

Com ação de servidor (Next.js App Router):

// app/actions.ts
"use server";
 
export async function createUser(prevState: FormState, formData: FormData) {
  const name = formData.get("name") as string;
  const user = await db.users.create({ data: { name } });
  return { success: true, error: "" };
}
 
// app/page.tsx
"use client";
import { useActionState } from "react";
import { createUser } from "./actions";
 
export function CreateUserForm() {
  const [state, formAction, isPending] = useActionState(createUser, {
    success: false,
    error: "",
  });
  return <form action={formAction}>...</form>;
}

Múltiplos botões de envio com formAction:

<form>
  <input name="item" />
  <button formAction={saveAction}>Salvar Rascunho</button>
  <button formAction={publishAction}>Publicar</button>
</form>

Ação assíncrona apenas do cliente:

async function loginAction(prev: LoginState, formData: FormData) {
  const res = await fetch("/api/login", {
    method: "POST",
    body: formData,
  });
  if (!res.ok) return { error: "Credenciais inválidas" };
  return { error: "" };
}

Notas TypeScript

// Digite o estado explicitamente para clareza
interface ActionState {
  success: boolean;
  error: string;
  data?: UserData;
}
 
// A ação deve corresponder ao tipo de estado
async function myAction(
  prevState: ActionState,
  formData: FormData
): Promise<ActionState> {
  // ...
  return { success: true, error: "" };
}
 
const [state, formAction, isPending] = useActionState(myAction, {
  success: false,
  error: "",
});
// state: ActionState

Armadilhas

Confusão com useFormState (descontinuado) - React 19 renomeou useFormState para useActionState e adicionou isPending como o terceiro valor de retorno. Correção: Use useActionState de "react", não useFormState de "react-dom".
A ação deve retornar o estado - Se sua ação não retornar um valor, o estado se tornará undefined após a submissão. Correção: Sempre retorne o novo estado da sua função de ação.
O estado é redefinido a cada submissão - O estado anterior é passado como o primeiro argumento; você deve mesclá-lo se quiser preservar os campos. Correção: Espalhe o estado anterior: return { ...prevState, error: "" }.
Usando fora de um formulário - useActionState é projetado para <form action={}>. Chamar formAction manualmente com FormData construído funciona, mas perde o aprimoramento progressivo. Correção: Prefira <form action={formAction}> para melhor compatibilidade.
Serialização de ação de servidor - O estado passado entre servidor e cliente deve ser serializável (sem funções, Dates, Maps). Correção: Use objetos simples com valores primitivos.

Alternativas

Alternativa	Use Quando	Não Use Quando
`useState` + `useTransition`	Lógica de envio personalizada não vinculada a `<form action={}>`	Você deseja aprimoramento progressivo
`useReducer`	Transições de estado complexas no lado do cliente sem submissão de formulário	Mudanças de estado são impulsionadas por ações de formulário
React Hook Form	Validação complexa, erros em nível de campo, formulários dinâmicos	Formulários simples com ações de servidor
Ação de servidor sem hook	Mutação de disparar e esquecer, nenhuma atualização de estado do cliente necessária	Você precisa exibir o resultado na UI

FAQs

Qual é a diferença entre useActionState e o useFormState descontinuado?

React 19 renomeou useFormState para useActionState e adicionou isPending como o terceiro valor de retorno.
Importe useActionState de "react", não useFormState de "react-dom".
A API é, de outra forma, a mesma: função de ação, estado inicial e permalink opcional.

Como useActionState fornece aprimoramento progressivo?

O formAction retornado pelo hook é compatível com <form action={}>.
Isso significa que o formulário pode ser enviado mesmo antes que o JavaScript seja hidratado na página.
Com ações de servidor no Next.js, o formulário funciona sem nenhum JavaScript do lado do cliente.

Por que a função de ação recebe previousState como seu primeiro argumento?

Permite atualizações incrementais de estado, semelhante a um padrão de reducer.
Você pode mesclar o estado anterior com novos dados: return { ...prevState, error: "" }.
Sem isso, você perderia os campos de estado existentes a cada submissão.

Armadilha: O que acontece se minha função de ação não retornar um valor?

O estado se torna undefined após a submissão, o que pode quebrar sua UI.
Sempre retorne o novo objeto de estado da função de ação.
TypeScript avisará se o tipo de retorno não corresponder ao tipo de estado.

Posso usar useActionState para formulários apenas do cliente sem ações de servidor?

async function loginAction(prev: LoginState, formData: FormData) {
  const res = await fetch("/api/login", {
    method: "POST",
    body: formData,
  });
  if (!res.ok) return { error: "Credenciais inválidas" };
  return { error: "" };
}
 
const [state, formAction, isPending] = useActionState(loginAction, { error: "" });

Sim. A ação pode ser qualquer função assíncrona, não apenas uma ação de servidor.

Como isPending funciona internamente?

A ação é executada dentro de uma transição do React, então isPending se torna true sem bloquear a UI.
Após a resolução da ação, o React atualiza o estado e define isPending como false.
Você não precisa gerenciar o estado de carregamento manualmente.

Como eu digito a ação e o estado com TypeScript?

interface ActionState {
  success: boolean;
  error: string;
}
 
async function myAction(
  prevState: ActionState,
  formData: FormData
): Promise<ActionState> {
  return { success: true, error: "" };
}
 
const [state, formAction, isPending] = useActionState(myAction, {
  success: false,
  error: "",
});
// state: ActionState

Armadilha: Posso passar valores não serializáveis (funções, Dates, Maps) no estado?

Não. Ao usar ações de servidor, o estado é serializado entre servidor e cliente.
Apenas objetos simples com valores primitivos (strings, números, booleanos, arrays) são seguros.
Funções, objetos Date, Map e Set falharão durante a serialização.

Como lidar com múltiplos botões de envio com ações diferentes?

<form>
  <input name="item" />
  <button formAction={saveDraftAction}>Salvar Rascunho</button>
  <button formAction={publishAction}>Publicar</button>
</form>

Cada botão pode ter seu próprio atributo formAction apontando para uma ação diferente.

Quando devo usar useActionState vs useState + useTransition manualmente?

Use useActionState para submissões de formulário onde você deseja aprimoramento progressivo e estado pendente automático.
Use useState + useTransition para lógica de envio personalizada não vinculada a <form action={}>.
useActionState reduz o código repetitivo combinando estado, pendente e ação em um único hook.

Relacionado

useOptimistic - exibe o estado otimista enquanto a ação está pendente
useTransition - useActionState usa transições internamente
use - primitivo do React 19 para consumir promises
useReducer - padrão semelhante, mas para máquinas de estado do lado do cliente

Hook useActionState

Buscar na documentação

Hook useActionState