29 août 2025Français

Maîtrisez le hook useFormStatus de React pour une gestion fluide des soumissions de formulaire, le suivi de la progression et une expérience utilisateur améliorée. Apprenez à créer des formulaires robustes et conviviaux.

React useFormStatus : Guide complet sur l'état de soumission des formulaires et le suivi de la progression

Les formulaires sont l'épine dorsale d'innombrables applications web, servant d'interface principale pour l'interaction de l'utilisateur. Cependant, la gestion des soumissions de formulaires, le traitement des erreurs et la fourniture de retours aux utilisateurs peuvent être une tâche complexe. Le hook useFormStatus de React simplifie ce processus, offrant un moyen rationalisé de suivre l'état de soumission du formulaire et de fournir une expérience utilisateur plus intuitive.

Qu'est-ce que `useFormStatus` ?

Introduit dans React 18, useFormStatus est un hook conçu pour fournir des informations sur l'état de soumission d'un élément <form>. Il vous permet de déterminer si un formulaire est en cours de soumission, a été soumis avec succès ou a rencontré une erreur lors de la soumission. Ces informations peuvent être utilisées pour mettre à jour l'interface utilisateur, désactiver des boutons, afficher des indicateurs de chargement ou fournir des messages d'erreur à l'utilisateur.

Principaux avantages de l'utilisation de `useFormStatus` :

Gestion simplifiée de l'état du formulaire : Élimine le besoin de gérer manuellement l'état pour la soumission du formulaire, réduisant ainsi le code répétitif.
Expérience utilisateur améliorée : Fournit un retour en temps réel aux utilisateurs lors de la soumission du formulaire, améliorant ainsi l'ergonomie.
Accessibilité renforcée : Permet des interactions de formulaire accessibles en désactivant les éléments du formulaire pendant la soumission et en fournissant des messages d'erreur clairs.
Performance optimisée : Suit efficacement l'état de soumission du formulaire, évitant les rendus inutiles.

Comment fonctionne `useFormStatus`

Le hook useFormStatus est utilisé dans un composant React qui rend un élément <form>. Le hook renvoie un objet contenant les propriétés suivantes :

pending : Une valeur booléenne indiquant si le formulaire est en cours de soumission.
data : Les données renvoyées par la fonction d'action du formulaire (en cas de succès).
method : La méthode HTTP utilisée pour la soumission du formulaire (par ex., "POST", "GET").
action : La fonction qui a été appelée lors de la soumission du formulaire.
error : Un objet d'erreur si la soumission du formulaire a échoué.

Pour utiliser useFormStatus, vous devez d'abord définir une fonction action pour votre formulaire. Cette fonction sera appelée lors de la soumission du formulaire. Au sein de la fonction action, vous pouvez effectuer tout traitement de données, validation ou appels API nécessaires. La fonction action doit renvoyer une valeur qui sera disponible dans la propriété data du hook useFormStatus. Si l'action lève une erreur, cette erreur sera disponible dans la propriété error.

Exemples pratiques de `useFormStatus`

Exemple 1 : Suivi de base de la soumission d'un formulaire

Cet exemple montre comment utiliser useFormStatus pour suivre l'état de soumission d'un simple formulaire de contact. Cet exemple fonctionne dans un React Server Component (RSC), qui nécessite un framework comme Next.js ou Remix.


// app/contact/page.tsx (Next.js)
'use client';

import { useFormStatus } from 'react-dom';

async function submitForm(formData: FormData) {
  "use server";
  // Simulate an API call
  await new Promise((resolve) => setTimeout(resolve, 2000));

  const name = formData.get('name') as string;
  const email = formData.get('email') as string;
  const message = formData.get('message') as string;

  if (!name || !email || !message) {
    throw new Error('Please fill in all fields.');
  }

  console.log('Form Data:', { name, email, message });
  return { message: 'Form submitted successfully!' };
}

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

  return (
    
      Name:
      


      Email:
      


      Message:
      


      

      {data && {data.message}}
      {error && Error: {error.message}}
    
  );
}

Dans cet exemple, l'état pending est utilisé pour désactiver les champs du formulaire et le bouton de soumission pendant que le formulaire est en cours d'envoi. Il modifie également dynamiquement le texte du bouton en « Envoi en cours... » pour fournir un retour visuel à l'utilisateur. En cas de succès, les data de l'action submitForm sont affichées. Si une erreur se produit pendant la soumission, le message d'error est affiché à l'utilisateur.

Exemple 2 : Affichage d'un indicateur de chargement

Cet exemple montre comment afficher un indicateur de chargement pendant la soumission du formulaire. C'est particulièrement utile pour les formulaires qui impliquent des appels API longs ou des traitements de données complexes.


// Similar component structure as Example 1
export default function ContactForm() {
  const { pending, data, error } = useFormStatus();

  return (
    
      {/* ... form inputs ... */}

      

      {pending && Loading...} {/* Show loading indicator */}

      {data && {data.message}}
      {error && Error: {error.message}}
    
  );
}

Dans cet exemple, un simple message « Chargement... » est affiché lorsque l'état pending est vrai. Vous pouvez remplacer cela par un indicateur de chargement plus sophistiqué, comme un spinner ou une barre de progression.

Exemple 3 : Gestion des erreurs de validation de formulaire

Cet exemple montre comment gérer les erreurs de validation de formulaire avec useFormStatus. La fonction action effectue la validation et lève une erreur si des règles de validation sont enfreintes.


// Similar component structure as Example 1
async function submitForm(formData: FormData) {
  "use server";
  const name = formData.get('name') as string;
  const email = formData.get('email') as string;
  const message = formData.get('message') as string;

  if (!name) {
    throw new Error('Name is required.');
  }
  if (!email) {
    throw new Error('Email is required.');
  }
  if (!message) {
    throw new Error('Message is required.');
  }

  // Simulate an API call
  await new Promise((resolve) => setTimeout(resolve, 2000));

  console.log('Form Data:', { name, email, message });
  return { message: 'Form submitted successfully!' };
}

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

  return (
    
      {/* ... form inputs ... */}

      

      {error && Error: {error.message}} {/* Display error message */}
    
  );
}

Dans cet exemple, la fonction action vérifie si les champs nom, e-mail et message sont vides. Si l'un de ces champs est vide, elle lève une erreur avec un message correspondant. La propriété error du hook useFormStatus est ensuite utilisée pour afficher le message d'erreur à l'utilisateur.

Cas d'utilisation avancés et considérations

Intégration avec des bibliothèques de formulaires tierces

Bien que useFormStatus fournisse une solution native pour suivre l'état de soumission des formulaires, il peut également être intégré avec des bibliothèques de formulaires tierces telles que Formik ou React Hook Form. Ces bibliothèques offrent des fonctionnalités plus avancées comme la validation de formulaires, la gestion des champs et la gestion de l'état. En combinant useFormStatus avec ces bibliothèques, vous pouvez créer des formulaires hautement personnalisables et robustes.

Pour l'intégrer avec Formik ou React Hook Form, vous pouvez utiliser leurs gestionnaires de soumission de formulaire respectifs et utiliser useFormStatus pour suivre l'état de soumission global. Vous devrez probablement toujours créer une Server Action, mais la gestion de l'état du formulaire côté client serait gérée par la bibliothèque choisie.

Gestion des opérations asynchrones

De nombreux formulaires impliquent des opérations asynchrones telles que des appels API ou des requêtes de base de données. Lorsque vous traitez des opérations asynchrones, il est important de s'assurer que la soumission du formulaire est gérée correctement et que l'utilisateur reçoit un retour approprié. Le hook useFormStatus simplifie ce processus en fournissant un état pending qui peut être utilisé pour indiquer que le formulaire attend la fin d'une opération asynchrone.

Il est également crucial d'implémenter une gestion d'erreurs robuste pour gérer gracieusement toute erreur qui pourrait survenir lors des opérations asynchrones. La propriété error du hook useFormStatus peut être utilisée pour afficher des messages d'erreur à l'utilisateur.

Considérations sur l'accessibilité

L'accessibilité est un aspect essentiel du développement web, et les formulaires ne font pas exception. Lors de la création de formulaires, il est important de s'assurer qu'ils sont accessibles aux utilisateurs handicapés. Le hook useFormStatus peut être utilisé pour améliorer l'accessibilité des formulaires en :

Désactivant les éléments du formulaire pendant la soumission : Cela empêche les utilisateurs de soumettre accidentellement le formulaire plusieurs fois.
Fournissant des messages d'erreur clairs : Les messages d'erreur doivent être concis, informatifs et faciles à comprendre. Ils doivent également être associés aux champs de formulaire correspondants à l'aide des attributs ARIA.
Utilisant les attributs ARIA : Les attributs ARIA peuvent être utilisés pour fournir des informations supplémentaires sur le formulaire et ses éléments aux technologies d'assistance. Par exemple, l'attribut aria-describedby peut être utilisé pour associer des messages d'erreur aux champs du formulaire.

Optimisation des performances

Bien que useFormStatus soit généralement efficace, il est important de prendre en compte les implications sur les performances lors de la création de formulaires complexes. Évitez d'effectuer des calculs coûteux ou des appels API dans le composant qui utilise useFormStatus. Déléguez plutôt ces tâches à la fonction action.

De plus, soyez attentif aux rendus inutiles. Utilisez les techniques de mémoïsation de React (par ex., React.memo, useMemo, useCallback) pour empêcher les composants de se rendre à nouveau à moins que leurs props n'aient changé.

Meilleures pratiques pour l'utilisation de `useFormStatus`

Gardez vos fonctions action concises et ciblées : La fonction action devrait principalement gérer le traitement des données, la validation et les appels API. Évitez d'effectuer des mises à jour complexes de l'interface utilisateur ou d'autres effets de bord dans la fonction action.
Fournissez un retour clair et informatif aux utilisateurs : Utilisez les propriétés pending, data, et error du hook useFormStatus pour fournir un retour en temps réel aux utilisateurs pendant la soumission du formulaire.
Implémentez une gestion d'erreurs robuste : Gérez gracieusement toute erreur qui pourrait survenir lors de la soumission du formulaire et fournissez des messages d'erreur informatifs à l'utilisateur.
Tenez compte de l'accessibilité : Assurez-vous que vos formulaires sont accessibles aux utilisateurs handicapés en suivant les meilleures pratiques en matière d'accessibilité.
Optimisez les performances : Évitez les rendus inutiles et les calculs coûteux dans le composant qui utilise useFormStatus.

Applications réelles et exemples du monde entier

Le hook useFormStatus peut être appliqué à divers scénarios basés sur des formulaires dans différents secteurs et zones géographiques. Voici quelques exemples :

E-commerce (Monde entier) : Une boutique en ligne peut utiliser useFormStatus pour suivre la soumission des formulaires de commande. L'état pending peut être utilisé pour désactiver le bouton "Passer la commande" pendant le traitement de la commande, et l'état error pour afficher des messages d'erreur si la commande échoue (par ex., en raison de problèmes de paiement ou de pénuries de stock).
Santé (Europe) : Un fournisseur de soins de santé peut utiliser useFormStatus pour suivre la soumission des formulaires d'inscription des patients. L'état pending peut être utilisé pour afficher un indicateur de chargement pendant le traitement des informations du patient, et l'état data pour afficher un message de confirmation après une inscription réussie. La conformité avec le RGPD (Règlement Général sur la Protection des Données) est primordiale, et les messages d'erreur liés aux violations de la confidentialité des données doivent être traités avec soin.
Éducation (Asie) : Une plateforme d'apprentissage en ligne peut utiliser useFormStatus pour suivre la soumission des devoirs. L'état pending peut être utilisé pour désactiver le bouton "Soumettre" pendant le téléchargement du devoir, et l'état error pour afficher des messages d'erreur si le téléchargement échoue (par ex., en raison de limitations de taille de fichier ou de problèmes de réseau). Différents pays peuvent avoir des normes académiques et des exigences de soumission différentes, que le formulaire doit prendre en compte.
Services financiers (Amérique du Nord) : Une banque peut utiliser useFormStatus pour suivre la soumission des formulaires de demande de prêt. L'état pending peut être utilisé pour afficher un indicateur de chargement pendant le traitement de la demande, et l'état data pour afficher le statut d'approbation du prêt. La conformité avec les réglementations financières (par ex., KYC - Know Your Customer) est cruciale, et les messages d'erreur liés aux problèmes de conformité doivent être clairs et spécifiques.
Services gouvernementaux (Amérique du Sud) : Une agence gouvernementale peut utiliser useFormStatus pour suivre la soumission des formulaires de retour des citoyens. L'état pending peut être utilisé pour désactiver le bouton "Soumettre" pendant le traitement du retour, et l'état data pour afficher un message de confirmation après une soumission réussie. L'accessibilité est essentielle, car les citoyens peuvent avoir des niveaux variés de littératie numérique et d'accès à la technologie. Le formulaire doit être disponible en plusieurs langues.

Dépannage des problèmes courants

useFormStatus ne se met pas à jour : Assurez-vous d'utiliser React 18 ou une version ultérieure et que votre formulaire a une action correctement définie. Vérifiez que votre Server Action est correctement définie à l'aide de la directive "use server".
Les messages d'erreur ne s'affichent pas : Vérifiez que votre fonction action lève correctement les erreurs et que vous affichez le error.message dans votre composant. Inspectez la console pour toute erreur lors de la soumission du formulaire.
Le formulaire est soumis plusieurs fois : Assurez-vous que votre bouton de soumission est désactivé en utilisant l'état pending pour éviter les doubles-clics accidentels.

Conclusion

Le hook useFormStatus de React offre un moyen puissant et pratique de suivre l'état de soumission des formulaires et d'offrir une meilleure expérience utilisateur. En simplifiant la gestion de l'état des formulaires, en améliorant l'accessibilité et en optimisant les performances, useFormStatus permet aux développeurs de créer des formulaires robustes et conviviaux. En comprenant ses capacités et les meilleures pratiques, vous pouvez tirer parti de useFormStatus pour créer des interactions de formulaire fluides et engageantes dans vos applications React.