useActionState e useFormStatus

useActionState(action, initialState) è un hook di React 19 che avvolge una Server Action per monitorarne lo stato tra un invio e l'altro. Riceve la funzione action e un valore di stato iniziale e restituisce una tupla che è possibile utilizzare per gestire l'intera esperienza del modulo.

L'hook restituisce [state, formAction, isPending]. state contiene il valore restituito più recentemente dall'action, iniziando da null o dal valore iniziale specificato. formAction è l'action wrappata da passare al modulo. isPending vale true mentre l'action viene eseguita sul server.

Ogni volta che il modulo viene inviato, la Server Action viene eseguita e il suo valore restituito diventa il nuovo state. Al primo rendering, state è uguale a initialState. Questo rende semplice mostrare interfacce diverse a seconda che ci siano stati invii precedenti e dei risultati restituiti.

Se la Server Action restituisce { errors: { email: 'Invalid email' } }, è possibile visualizzare l'errore inline: {state.errors?.email && <p>{state.errors.email}</p>}. Poiché lo stato persiste tra i re-rendering, il messaggio di errore rimane visibile finché un invio completato correttamente non sostituisce lo stato.

Quando l'action restituisce { success: true }, il componente può visualizzare un messaggio di successo: {state?.success && <p>Form submitted!</p>}. In base al valore dello stato, è possibile nascondere condizionalmente il modulo o sostituirlo con il messaggio di successo.

useFormStatus() è un hook che legge lo stato di attesa dell'elemento <form> antenato più vicino. Restituisce un oggetto che include { pending: boolean }. Questo hook deve essere utilizzato all'interno di un componente figlio del modulo, non nel componente che esegue il rendering del modulo stesso.

La restrizione secondo cui useFormStatus deve essere utilizzato all'interno del modulo esiste perché l'hook legge il contesto del modulo dall'albero React sovrastante. Se venisse chiamato nello stesso componente che esegue il rendering del modulo, sarebbe un fratello del modulo, non un suo discendente, e non avrebbe accesso allo stato del modulo.

Il pattern standard consiste nell'estrarre il pulsante di invio in un componente separato: function SubmitButton() { const { pending } = useFormStatus(); return <button disabled={pending}>Submit</button>; }. Questo componente viene quindi inserito all'interno del modulo, ottenendo così accesso allo stato di attesa del modulo.

Impostare disabled={pending} sul pulsante di invio impedisce gli invii duplicati. Quando l'utente fa clic su Invia e la Server Action è in esecuzione, pending vale true, quindi il pulsante viene disabilitato e non può essere selezionato. Al completamento dell'action, pending torna a false e il pulsante viene nuovamente abilitato.

Il pattern completo per l'esperienza utente dei moduli combina entrambi gli hook: useActionState nel componente del modulo monitora il risultato dell'action e fornisce formAction, mentre useFormStatus all'interno di un componente figlio SubmitButton monitora lo stato di attesa. Insieme, consentono di visualizzare gli errori di validazione e offrono un pulsante di invio reattivo.

Per un'esperienza ancora più reattiva, useOptimistic si combina con useActionState. L'interfaccia viene aggiornata immediatamente con il risultato previsto prima che il server risponda, per poi essere riallineata quando arriva la risposta effettiva. Questo pattern è comune nei pulsanti Mi piace, nelle liste di attività e in altre interazioni che richiedono un feedback immediato.

Dove deve essere chiamato useFormStatus affinché funzioni correttamente?

useActionState(action, initialState) restituisce [state, formAction, isPending] per monitorare i risultati delle Server Actions. Lo stato contiene il valore restituito dall'action e consente di visualizzare inline gli errori e i messaggi di successo. useFormStatus() fornisce { pending } all'interno dei componenti figli del modulo, consentendo di creare pulsanti di invio reattivi. Insieme, i due hook permettono di realizzare un'esperienza completa e accessibile per i moduli.