API de Referência
Hooks

useFormStatus - This feature is available in the latest Canary

Canary

O Hook useFormStatus está atualmente disponível apenas nos canais Canary e experimentais do React. Saiba mais sobre os canais de lançamento do React aqui.

O useFormStatus é um Hook que fornece informações de status da última submissão de formulário.

const { pending, data, method, action } = useFormStatus();

Referência

useFormStatus()

O Hook useFormStatus fornece informações de status da última submissão de formulário.

import { useFormStatus } from "react-dom";
import action from './actions';

function Submit() {
  const status = useFormStatus();
  return <button disabled={status.pending}>Submeter</button>
}

export default function App() {
  return (
    <form action={action}>
      <Submit />
    </form>
  );
}

Para obter informações de status, o componente Submit deve ser renderizado dentro de um <form>. O Hook retorna informações como a propriedade pending, que indica se o formulário está em processo de submissão.

No exemplo acima, o Submit usa essas informações para desabilitar os cliques no <button> enquanto o formulário está sendo submetido.

Veja mais exemplos abaixo.

Parâmetros

O useFormStatus não aceita nenhum parâmetro.

Retornos

Um objeto status com as seguintes propriedades:

  • pending: Um booleano. Se true, isso significa que o <form> pai está pendente de submissão. Caso contrário, false.

  • data: Um objeto que implementa a interface FormData que contém os dados que o <form> pai está submetendo. Se não houver uma submissão ativa ou nenhum <form> pai, será null.

  • method: Um valor string que pode ser 'get' ou 'post'. Isso representa se o <form> pai está submetendo com o método HTTP que pode ser GET ou POST. Por padrão, um <form> usará o método GET e isso pode ser especificado pela propriedade method.

  • action: Uma referência à função passada pela propriedade action no <form> pai. Se não houver um <form> pai, a propriedade será null. Se houver um valor de URI fornecido para a propriedade action, ou nenhuma propriedade action especificada, status.action será null.

Ressalvas

  • O Hook useFormStatus deve ser chamado de um componente que é renderizado dentro de um <form>.
  • O useFormStatus só retornará informações de status para um <form> pai. Ele não retornará informações de status para qualquer <form> renderizado no mesmo componente ou nos componentes filhos.

Uso

Exibir um estado pendente durante a submissão do formulário

Para exibir um estado pendente enquanto um formulário está sendo submetido, você pode chamar o Hook useFormStatus em um componente renderizado em um <form> e ler a propriedade pending retornada.

Aqui, usamos a propriedade pending para indicar que o formulário está sendo submetido.

import { useFormStatus } from "react-dom";
import { submitForm } from "./actions.js";

function Submit() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? "Submetendo..." : "Submeter"}
    </button>
  );
}

function Form({ action }) {
  return (
    <form action={action}>
      <Submit />
    </form>
  );
}

export default function App() {
  return <Form action={submitForm} />;
}

Pitfall

useFormStatus não retornará informações de status para um <form> renderizado no mesmo componente.

O Hook useFormStatus apenas retorna informações de status para um <form> pai e não para qualquer <form> renderizado no mesmo componente que chama o Hook, ou componentes filhos.

function Form() {
  // 🚩 `pending` nunca será true
  // useFormStatus não rastreia o formulário renderizado neste componente
  const { pending } = useFormStatus();
  return <form action={submit}></form>;
}

Em vez disso, chame o useFormStatus de dentro de um componente que está localizado dentro do <form>.

function Submit() {
  // ✅ `pending` será derivado do formulário que envolve o componente Submit
  const { pending } = useFormStatus(); 
  return <button disabled={pending}>...</button>;
}

function Form() {
  // Este é o <form> que o useFormStatus rastreia
  return (
    <form action={submit}>
      <Submit />
    </form>
  );
}

Ler os dados do formulário que estão sendo submetidos

Você pode usar a propriedade data das informações de status retornadas pelo useFormStatus para exibir quais dados estão sendo submetidos pelo usuário.

Aqui, temos um formulário onde os usuários podem solicitar um nome de usuário. Podemos usar o useFormStatus para exibir uma mensagem de status temporária confirmando qual nome de usuário eles solicitaram.

import {useState, useMemo, useRef} from 'react';
import {useFormStatus} from 'react-dom';

export default function UsernameForm() {
  const {pending, data} = useFormStatus();

  return (
    <div>
      <h3>Solicitar um Nome de Usuário: </h3>
      <input type="text" name="username" disabled={pending}/>
      <button type="submit" disabled={pending}>
        Submeter
      </button>
      <br />
      <p>{data ? `Solicitando ${data?.get("username")}...`: ''}</p>
    </div>
  );
}

Solução de Problemas

status.pending nunca é true

O useFormStatus apenas retornará informações de status para um <form> pai.

Se o componente que chama o useFormStatus não estiver aninhado em um <form>, status.pending sempre retornará false. Verifique se o useFormStatus é chamado em um componente que é filho de um elemento <form>.

O useFormStatus não rastreará o status de um <form> renderizado no mesmo componente. Veja Pitfall para mais detalhes.

PreviousHooks
NextComponents