useActionState et useFormStatus

useActionState(action, initialState) est un crochet React 19 qui enveloppe une action serveur pour suivre son état au fil des soumissions. Il reçoit la fonction d’action et une valeur d’état initiale, puis renvoie un tuple que vous pouvez utiliser pour gérer toute l’expérience du formulaire.

Le crochet renvoie [state, formAction, isPending]. L’state contient la valeur de retour la plus récente de l’action, en commençant par null ou par votre valeur initiale. formAction est l’action enveloppée à transmettre au formulaire. isPending vaut true pendant l’exécution de l’action sur le serveur.

À chaque soumission du formulaire, l’action serveur s’exécute et sa valeur de retour devient le nouvel state. Lors du premier affichage, state est égal à initialState. Il devient ainsi simple d’afficher une interface différente selon qu’il y a eu ou non des soumissions précédentes et selon leur résultat.

Si l’action serveur renvoie { errors: { email: 'Invalid email' } }, vous pouvez afficher l’erreur directement dans la page : {state.errors?.email && <p>{state.errors.email}</p>}. Comme l’état persiste entre les nouveaux affichages, le message d’erreur reste visible jusqu’à ce qu’une soumission réussie remplace l’état.

Lorsque l’action renvoie { success: true }, le composant peut afficher un message de réussite : {state?.success && <p>Form submitted!</p>}. Selon la valeur de l’état, le formulaire peut être masqué ou remplacé conditionnellement par le message de réussite.

useFormStatus() est un crochet qui lit l’état d’attente de l’élément <form> ancêtre le plus proche. Il renvoie un objet comprenant notamment { pending: boolean }. Ce crochet doit être utilisé dans un composant enfant du formulaire, et non dans le composant qui affiche lui-même le formulaire.

La restriction selon laquelle useFormStatus doit être utilisé à l’intérieur du formulaire existe parce que le crochet lit le contexte du formulaire dans l’arbre React situé au-dessus de lui. S’il était appelé dans le même composant que celui qui affiche le formulaire, il serait un élément frère du formulaire et non un élément descendant, et n’aurait pas accès à l’état du formulaire.

Le modèle standard consiste à extraire le bouton de soumission dans son propre composant : function SubmitButton() { const { pending } = useFormStatus(); return <button disabled={pending}>Submit</button>; }. Ce composant est ensuite placé à l’intérieur du formulaire, ce qui lui donne accès à l’état d’attente du formulaire.

Définir disabled={pending} sur le bouton de soumission empêche les soumissions en double. Lorsque l’utilisateur clique sur le bouton et que l’action serveur s’exécute, pending vaut true : le bouton est désactivé et impossible à cliquer. Lorsque l’action se termine, pending revient à false et le bouton est de nouveau activé.

Le modèle complet d’expérience utilisateur du formulaire combine les deux crochets : useActionState dans le composant du formulaire suit le résultat de l’action et fournit formAction, tandis que useFormStatus, dans un composant enfant SubmitButton, suit l’état d’attente. Ensemble, ils permettent d’afficher les erreurs de validation et fournissent un bouton de soumission réactif.

Pour une expérience encore plus réactive, useOptimistic s’associe à useActionState. Vous mettez immédiatement l’interface à jour avec le résultat attendu avant la réponse du serveur, puis vous la réconciliez lorsque la réponse réelle arrive. Ce modèle est courant pour les boutons d’appréciation, les listes de tâches et les autres interactions fournissant un retour rapide.

Où useFormStatus doit-il être appelé pour fonctionner correctement ?

useActionState(action, initialState) renvoie [state, formAction, isPending] pour suivre les résultats des actions serveur. L’état contient la valeur de retour de l’action, ce qui permet d’afficher directement les erreurs et les réussites. useFormStatus() fournit { pending } dans les composants enfants du formulaire, ce qui permet de créer des boutons de soumission réactifs. Ces deux crochets réunis créent une expérience complète et accessible pour les formulaires.