useActionState i useFormStatus

useActionState(action, initialState) to hook React 19, który opakowuje Server Action, aby śledzić jej stan pomiędzy kolejnymi przesłaniami. Przyjmuje funkcję akcji i wartość stanu początkowego, a następnie zwraca krotkę, za pomocą której można sterować całym działaniem formularza.

Hook zwraca [state, formAction, isPending]. state przechowuje ostatnią wartość zwróconą przez akcję, początkowo równą null lub podanej wartości początkowej. formAction to opakowana akcja, którą należy przekazać do formularza. isPending ma wartość true, gdy akcja jest wykonywana na serwerze.

Przy każdym przesłaniu formularza Server Action jest uruchamiana, a jej wartość zwracana staje się nowym state. Przy pierwszym renderowaniu state jest równe initialState. Ułatwia to wyświetlanie różnego interfejsu w zależności od tego, czy formularz był już wcześniej przesyłany, i jakie były wyniki tych przesłań.

Jeśli Server Action zwróci { errors: { email: 'Invalid email' } }, błąd można wyświetlić bezpośrednio przy polu: {state.errors?.email && <p>{state.errors.email}</p>}. Ponieważ stan zachowuje się pomiędzy ponownymi renderowaniami, komunikat o błędzie pozostaje widoczny do czasu, aż kolejne pomyślne przesłanie zastąpi ten stan.

Gdy akcja zwróci { success: true }, komponent może wyświetlić komunikat o sukcesie: {state?.success && <p>Form submitted!</p>}. Na podstawie wartości stanu formularz można warunkowo ukryć lub zastąpić komunikatem o sukcesie.

useFormStatus() to hook odczytujący stan oczekiwania najbliższego nadrzędnego elementu <form>. Zwraca obiekt zawierający między innymi { pending: boolean }. Tego hooka należy używać wewnątrz komponentu będącego dzieckiem formularza — nie w komponencie, który sam renderuje formularz.

Ograniczenie, zgodnie z którym useFormStatus musi być używany wewnątrz formularza, wynika z tego, że hook odczytuje kontekst formularza z nadrzędnej części drzewa Reacta. Gdyby wywołać go w tym samym komponencie, który renderuje formularz, byłby elementem równorzędnym formularza, a nie jego potomkiem, i nie miałby dostępu do jego stanu.

Standardowy wzorzec polega na wydzieleniu przycisku wysyłania do osobnego komponentu: function SubmitButton() { const { pending } = useFormStatus(); return <button disabled={pending}>Submit</button>; }. Następnie ten komponent umieszcza się wewnątrz formularza, dzięki czemu ma dostęp do jego stanu oczekiwania.

Ustawienie disabled={pending} na przycisku wysyłania zapobiega wielokrotnemu przesłaniu formularza. Gdy użytkownik kliknie przycisk wysyłania i Server Action będzie wykonywana, pending ma wartość true, więc przycisk zostaje wyłączony i nie można go kliknąć. Po zakończeniu akcji pending ponownie ma wartość false, a przycisk zostaje włączony.

Kompletny wzorzec obsługi formularza łączy oba hooki: useActionState w komponencie formularza śledzi wynik akcji i udostępnia formAction, natomiast useFormStatus wewnątrz podrzędnego komponentu SubmitButton śledzi stan oczekiwania. Razem zapewniają wyświetlanie błędów walidacji i szybko reagujący przycisk wysyłania.

Aby interfejs reagował jeszcze szybciej, można połączyć useOptimistic z useActionState. Interfejs jest natychmiast aktualizowany oczekiwanym wynikiem, zanim serwer odpowie, a następnie synchronizowany po nadejściu rzeczywistej odpowiedzi. Ten wzorzec jest często stosowany w przypadku przycisków polubienia, list zadań i innych interakcji wymagających szybkiej informacji zwrotnej.

Gdzie należy wywołać useFormStatus, aby działał poprawnie?

useActionState(action, initialState) zwraca [state, formAction, isPending] do śledzenia wyników Server Action. Stan przechowuje wartość zwróconą przez akcję, umożliwiając wyświetlanie błędów i komunikatów o sukcesie bezpośrednio w interfejsie. useFormStatus() udostępnia { pending } wewnątrz komponentów będących dziećmi formularza, umożliwiając tworzenie szybko reagujących przycisków wysyłania. Oba hooki razem tworzą kompletny i dostępny formularz.