Référence de l’API
Hooks

useFormStatus - Cette fonctionnalité est disponible dans le dernier Canary

Canary (fonctionnalité expérimentale)

Le Hook useFormStatus n’est actuellement disponible que sur les canaux de livraison Canary et Expérimental de React. Apprenez-en davantage sur les canaux de livraison React.

useFormStatus est un Hook qui vous fournit des informations d’état sur le dernier envoi de formulaire parent.

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

Référence

useFormStatus()

Le Hook useFormStatus vous fournit des informations d’état sur le dernier envoi de formulaire parent.

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

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

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

Pour récupérer les informations d’état, le composant Submit doit être utilisé au sein d’un <form>. Le Hook renvoie des informations telles que la propriété pending, qui vous indique si le formulaire est en cours d’envoi.

Dans l’exemple ci-dessus, Submit utilise cette information pour désactiver l’interactivité du <button> pendant l’envoi du formulaire.

Voir plus d’exemples ci-dessous.

Paramètres

useFormStatus ne prend aucun paramètre.

Valeur renvoyée

Un objet status doté des propriétés suivantes :

  • pending : un booléen. Vaut true si le <form> parent est en cours d’envoi, sinon false.

  • data : un objet qui implémente l’interface FormData, contenant les données que le <form> parent est en train d’envoyer. Si aucun envoi n’est en cours, ou s’il n’y a pas de <form> parent, cette propriété vaut null.

  • method : une chaîne de caractères valant soit 'get', soit 'post', selon que le <form> parent est en train de faire un envoi avec une méthode HTTP GET ou POST. Par défaut, un <form> utilisera la méthode GET, mais ça peut être spécifié par l’attribut method.

  • action : une référence vers la fonction passée à la prop action du <form> parent. S’il n’y a pas de <form> parent, cette propriété vaut null. Si la prop action a reçu une valeur URI, ou si aucune prop action n’est spécifiée, cette propriété vaut null.

Limitations

  • Le Hook useFormStatus doit être appelé dans un composant dont le rendu a lieu au sein d’un <form>.
  • useFormStatus ne renverra que les informations d’état du <form> parent. Il ne renverra pas les informations de statut d’un <form> placé dans le rendu du composant courant ou de ses composants enfants.

Utilisation

Afficher un état d’attente pendant l’envoi du formulaire

Pour afficher un état d’attente pendant que le formulaire est en cours d’envoi, vous pouvez utilisez le Hook useFormStatus dans un composant au sein du <form> et lire la propriété pending qu’il renvoie.

Nous utilisons ci-dessous la propriété pending pour indiquer que le formulaire est en cours d’envoi.

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

function Submit() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? "Envoi en cours..." : "Envoyer"}
    </button>
  );
}

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

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

Piège

useFormStatus ne renverra pas d’information d’état pour un <form> situé dans le même composant.

Le Hook useFormStatus ne renvoie que les informations d’état du <form> parent, et non celles d’un <form> placé dans le rendu du composant appelant le Hook ou dans ses composants enfants.

function Form() {
  // 🚩 `pending` ne sera jamais `true`
  // useFormStatus ne surveille pas le formulaire situé dans le
  // rendu de ce composant
  const { pending } = useFormStatus();
  return <form action={submit}></form>;
}

Appelez plutôt useFormStatus depuis un composant imbriqué dans <form>.

function Submit() {
  // ✅ `pending` se basera sur le formulaire qui enrobe
  // le composant Submit
  const { pending } = useFormStatus();
  return <button disabled={pending}>...</button>;
}

function Form() {
  // Voici le <form> surveillé par `useFormStatus`
  return (
    <form action={submit}>
      <Submit />
    </form>
  );
}

Lire les données en cours d’envoi

Vous pouvez utiliser la propriété data des informations d’état renvoyées par useFormStatus pour afficher les données que l’utilisateur est en train d’envoyer.

Dans l’exemple ci-dessous, nous avons un formulaire permettant à l’utilisateur de réserver un identifiant. Nous pouvons y utiliser useFormStatus pour afficher un message temporaire confirmant l’identifiant demandé.

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

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

  return (
    <div>
      <h3>Réserver l’identifiant : </h3><br />
      <input type="text" name="username" disabled={pending} />
      <button type="submit" disabled={pending}>
        Envoyer
      </button>
      <br />
      <p>{data ? `Récupération de ${data?.get('username')}...` : ''}</p>
    </div>
  );
}

Dépannage

status.pending ne vaut jamais true

useFormStatus ne renvoie d’informations d’état que pour un <form> parent.

Si le composant qui appelle useFormStatus n’est pas imbriqué dans un <form>, status.pending vaudra toujours false. Vérifiez que useFormStatus est appelé depuis un composant qui figure à l’intérieur d’un élément <form>.

useFormStatus ne surveillera pas l’état d’un <form> situé dans le rendu du même composant. Consultez le Piège pour en savoir plus.

PrécédentHooks
SuivantComposants