useActionState und useFormStatus

useActionState(action, initialState) ist ein React-19-Hook, der eine Server Action um Statusverfolgung über mehrere Übermittlungen hinweg erweitert. Er erhält die Action-Funktion und einen Anfangswert und gibt ein Tupel zurück, mit dem Sie den gesamten Ablauf des Formulars steuern können.

Der Hook gibt [state, formAction, isPending] zurück. state enthält den zuletzt von der Action zurückgegebenen Wert und beginnt mit null oder Ihrem Anfangswert. formAction ist die verpackte Action, die Sie an das Formular übergeben. isPending ist true, während die Action auf dem Server ausgeführt wird.

Bei jeder Formularübermittlung wird die Server Action ausgeführt und ihr Rückgabewert zum neuen state. Beim ersten Rendern entspricht state dem initialState. Dadurch können Sie auf einfache Weise unterschiedliche Benutzeroberflächen anzeigen, je nachdem, ob es bereits vorherige Übermittlungen gab und welche Ergebnisse sie geliefert haben.

Wenn die Server Action { errors: { email: 'Invalid email' } } zurückgibt, können Sie den Fehler direkt anzeigen: {state.errors?.email && <p>{state.errors.email}</p>}. Da der Status bei erneuten Render-Vorgängen erhalten bleibt, bleibt die Fehlermeldung sichtbar, bis eine erfolgreiche Übermittlung den Status ersetzt.

Wenn die Action { success: true } zurückgibt, kann die Komponente eine Erfolgsmeldung anzeigen: {state?.success && <p>Form submitted!</p>}. Abhängig vom Statuswert kann das Formular bedingt ausgeblendet oder durch die Erfolgsmeldung ersetzt werden.

useFormStatus() ist ein Hook, der den ausstehenden Status des nächstgelegenen übergeordneten <form>-Elements ausliest. Er gibt ein Objekt zurück, das unter anderem { pending: boolean } enthält. Dieser Hook muss innerhalb einer Komponente verwendet werden, die ein untergeordnetes Element des Formulars ist, nicht in der Komponente, die das Formular selbst rendert.

Die Einschränkung, dass useFormStatus innerhalb des Formulars verwendet werden muss, besteht, weil der Hook den Kontext des Formulars aus dem darüberliegenden React-Baum ausliest. Wenn er in derselben Komponente aufgerufen würde, die das Formular rendert, wäre er ein Geschwisterelement des Formulars und kein Nachfahre. Daher hätte er keinen Zugriff auf den Status des Formulars.

Das standardmäßige Muster besteht darin, die Submit-Schaltfläche in eine eigene Komponente auszulagern: function SubmitButton() { const { pending } = useFormStatus(); return <button disabled={pending}>Submit</button>; }. Diese Komponente wird anschließend innerhalb des Formulars platziert und erhält dadurch Zugriff auf den ausstehenden Status des Formulars.

Das Setzen von disabled={pending} auf der Submit-Schaltfläche verhindert doppelte Übermittlungen. Wenn der Benutzer auf „Submit“ klickt und die Server Action ausgeführt wird, ist pending gleich true; die Schaltfläche wird deaktiviert und kann nicht angeklickt werden. Nach Abschluss der Action wird pending wieder zu false und die Schaltfläche wird erneut aktiviert.

Das vollständige UX-Muster für Formulare kombiniert beide Hooks: useActionState in der Formularkomponente verfolgt das Ergebnis der Action und stellt formAction bereit, während useFormStatus innerhalb einer untergeordneten SubmitButton-Komponente den ausstehenden Status verfolgt. Zusammen ermöglichen sie die Anzeige validierter Fehler und eine reaktionsschnelle Submit-Schaltfläche.

Für ein noch reaktionsschnelleres Benutzererlebnis lässt sich useOptimistic mit useActionState kombinieren. Sie aktualisieren die Benutzeroberfläche sofort mit dem erwarteten Ergebnis, bevor der Server antwortet, und gleichen sie anschließend mit der tatsächlichen Antwort ab. Dieses Muster ist bei Like-Schaltflächen, Aufgabenlisten und anderen Interaktionen mit schnellem Feedback üblich.

Wo muss useFormStatus aufgerufen werden, damit es korrekt funktioniert?

useActionState(action, initialState) gibt [state, formAction, isPending] zurück, um die Ergebnisse von Server Actions zu verfolgen. Der Status enthält den Rückgabewert der Action und ermöglicht dadurch die direkte Anzeige von Fehlern und Erfolgsmeldungen. useFormStatus() stellt innerhalb untergeordneter Komponenten des Formulars { pending } bereit und ermöglicht so reaktionsschnelle Submit-Schaltflächen. Zusammen bilden beide Hooks die Grundlage für ein vollständiges und barrierefreies Formularerlebnis.