Szybka odpowiedź: jak zbudować wielokrokowy formularz w Next.js?
Podziel formularz na 3–4 kroki i trzymaj wspólny stan w React Context.
Każdy krok waliduj osobnym schematem Zod, z polami niekontrolowanymi zbieranymi przez FormData.
Stan zapisuj w sessionStorage, żeby odświeżenie go nie skasowało.
Pełną walidację powtarzasz na serwerze w Server Action, a wysyłkę obsługujesz przez useActionState i useFormStatus.
Po zmianie kroku przenieś fokus na jego nagłówek dla czytników ekranu.
Dlaczego formularz multi-step w Next.js zamiast jednego formularza?
Typowe zastosowania: formularz wyceny projektu, onboarding nowego użytkownika, checkout (adres → dostawa → płatność), rejestracja z weryfikacją.
Trzy elementy, które trzeba domknąć: gdzie trzymać , jak walidować każdy krok osobno i jak bezpiecznie wysłać całość na serwer. Po kolei. (Jeśli chcesz, by krok był zapisany w URL-u jako ?step=2 — z deep linkingiem i działającym „wstecz" przeglądarki — wzorzec synchronizacji stanu z searchParams opisałem w artykule o URL state w Next.js.)
Diagram
Przepływ danych: każdy krok waliduje swój wycinek schematu i dopisuje dane do Contextu, a Server Action powtarza pełną walidację na serwerze.
Architektura formularza multi-step: Context i walidacja Zod per krok
Code
// types/quote-form.tsimport { z } from 'zod'// Schema per krokexport const step1Schema = z.object({ name: z.string().min(2, 'Minimum 2 znaki'), email: z.email('Podaj poprawny email'), // Zod 4; na Zod 3 było z.string().email() company: z.string().optional(),})export const step2Schema = z.object({ projectType: z.enum(['website', 'ecommerce', 'webapp', 'other']), budget: z.enum(['small', 'medium', 'large', 'enterprise']), deadline: z.string().min(1, 'Wybierz termin'),})export const step3Schema = z.object({ description: z.string().min(20, 'Opisz projekt — minimum 20 znaków'), features: z.array(z.string()).min(1, 'Wybierz minimum 1 funkcjonalność'), referenceUrls: z.string().optional(),})// Pełna schema — do finalnej walidacji.// Zod 4: łączymy schematy przez .extend() z ich .shape (.merge() jest wycofane).export const fullSchema = step1Schema .extend(step2Schema.shape) .extend(step3Schema.shape)export type QuoteFormData = z.infer<typeof fullSchema>export type Step1Data = z.infer<typeof step1Schema>export type Step2Data = z.infer<typeof step2Schema>export type Step3Data = z.infer<typeof step3Schema>
React Context i stan formularza między krokami
to tu naturalny wybór: kroki są
rodzeństwem renderowanym warunkowo, a stan musi być dla nich wspólny. Provider
przechowuje dane, numer aktywnego kroku i funkcje nawigacji.
Powyższy Provider trzyma dane w pamięci, więc przypadkowe odświeżenie (F5) kasuje wypełnione kroki — najczęstsza i najbardziej frustrująca wpadka multi-step formularzy. Rozwiązaniem jest cienka warstwa persistencji: inicjalizuj stan z sessionStorage, a przy każdej zmianie zapisuj go z powrotem (rozszerzamy QuoteFormProvider z poprzedniej sekcji o useEffect).
Zapisujemy dane i numer kroku razem — sam persist danych to połowa roboty, bo po odświeżeniu użytkownik z wypełnionymi trzema krokami wylądowałby z powrotem na pierwszym i musiałby przeklikać się przez całość, żeby wrócić tam, gdzie był.
Wybór sessionStorage (nie localStorage) jest celowy: dane żyją do zamknięcia karty, a nie w nieskończoność — przy formularzach z danymi osobowymi to bezpieczniejszy domyślny wybór. Pamiętaj, by wyczyścić storage po udanej wysyłce, żeby kolejny użytkownik tego samego urządzenia nie zobaczył cudzych danych.
Jedno zastrzeżenie hydratacyjne: skoro pierwszy render na serwerze nie zna zawartości sessionStorage, komponent formularza renderuj wyłącznie po stronie klienta (to i tak Client Component osadzony w serwerowej stronie), a jeśli prerenderujesz stronę statycznie — zadbaj, żeby odczyt storage nie różnicował pierwszego renderu, bo skończy się to .
Trzy detale w tym kodzie robią różnicę dla czytników ekranu: htmlFor/id wiąże etykietę z polem (klik w etykietę fokusuje pole, a czytnik wie, co ogłosić), aria-invalid oznacza pole z błędem, a aria-describedby sprawia, że komunikat błędu jest odczytywany razem z polem — nie jest tylko czerwonym tekstem gdzieś obok.
Dostępność: fokus musi podążać za krokiem
Multi-step formularz ma problem, którego nie ma zwykły formularz: po kliknięciu „Dalej" wizualnie zmienia się wszystko, a dla czytnika ekranu — nic. Fokus zostaje na przycisku, który właśnie zniknął z kontekstu, i użytkownik nie wie, że jest w nowym kroku. Rozwiązanie to przeniesienie fokusu na nagłówek świeżo zamontowanego kroku:
Code
// components/quote-form/step-heading.tsx'use client'import { useEffect, useRef } from 'react'export function StepHeading({ children }: { children: React.ReactNode }) { const ref = useRef<HTMLHeadingElement>(null) // Krok montuje się na nowo przy każdej zmianie — fokus ląduje na nagłówku, // czytnik ekranu ogłasza tytuł kroku useEffect(() => { ref.current?.focus() }, []) return ( <h2 ref={ref} tabIndex={-1} className="text-xl font-semibold outline-none"> {children} </h2> )}
Zamień <h2> w każdym kroku na <StepHeading> i nawigacja klawiaturą zaczyna mieć sens: Tab z nagłówka prowadzi do pierwszego pola nowego kroku. W progress barze dodaj do aktywnego elementu aria-current="step" — czytniki ogłoszą wtedy „krok 2 z 4, Projekt" zamiast anonimowej listy przycisków. Zauważ też, że disabled na przyszłych krokach w progress barze już chroni przed przeskakiwaniem walidacji — stan interfejsu i stan formularza mówią jednym głosem.
Podsumowanie i wysyłka formularza przez Server Action
Ostatni krok pokazuje zebrane dane i wysyła je przez . Walidację fullSchema powtarzamy tu po stronie serwera — to ostatnia i jedyna wiążąca linia obrony, niezależnie od tego, co przeszło na kliencie. Tę serwerową walidację i jej efekty uboczne warto pokryć testami, bo to ona realnie chroni dane. Poniżej pokazuję wersję z ręcznym useState, a dalej ten sam krok przepisany na React 19 Actions z useActionState, który upraszcza obsługę stanu wysyłki i błędów.
A sama akcja wygląda tak — zwróć uwagę, że walidacja na kliencie w Step4Summary niczego tu nie zmienia, serwer waliduje od zera:
Code
// actions/quote.ts'use server'import { fullSchema } from '@/types/quote-form'import { saveQuoteRequest } from '@/data/quotes'import { sendNotificationEmail } from '@/lib/email'export async function submitQuoteForm(input: unknown) { // `unknown`, nie `QuoteFormData` — typ z klienta to deklaracja, // nie gwarancja. Server Action to publiczny endpoint HTTP. const parsed = fullSchema.safeParse(input) if (!parsed.success) { return { success: false, error: 'Dane formularza są niepoprawne.' } } try { await saveQuoteRequest(parsed.data) await sendNotificationEmail(parsed.data) return { success: true } } catch { // Szczegóły zostają w logach serwera, nie w odpowiedzi return { success: false, error: 'Nie udało się wysłać. Spróbuj ponownie.' } }}
Dwa detale są tu nieprzypadkowe. Parametr ma typ unknown, mimo że klient wysyła zwalidowane QuoteFormData — bo Server Action można wywołać bezpośrednio, z dowolnym payloadem, i typ TypeScriptu na granicy sieci jest tylko życzeniem. I druga rzecz: catch zwraca ogólny komunikat, a szczegóły błędu zostają w logach — odpowiedź akcji trafia do przeglądarki, więc nie powinna zdradzać wnętrza systemu. Formularz publiczny warto też osłonić przed botami (honeypot, rate limiting per IP) — wzorce testowania takich akcji obejmują i te ścieżki.
Na koniec pomiar: multi-step ma naturalny lejek, więc wysyłaj event analityczny przy każdym przejściu kroku (np. quote_form_step_completed z numerem kroku w nextStep()). Po tygodniu zobaczysz, na którym kroku użytkownicy odpadają — to zwykle konkretne pole, które można uprościć albo przenieść dalej, a nie „formularz jest za długi" jako całość.
React 19 Actions: useActionState, useFormStatus i useOptimistic w formularzu
Ręczny stan wysyłki w Step4Summary działa, ale React 19 ma na to gotowy mechanizm. Action to funkcja wykonująca zmianę danych, często asynchroniczna. Funkcję przekazaną do action elementu <form> React uruchamia w Transition z obiektem , a po jej sukcesie resetuje niekontrolowane pola. Kliencka funkcja formularza nie jest tym samym co Server Function: Server Functions (w dokumentacji Next.js często nazywane Server Actions) wykonują kod na serwerze i wymagają dyrektywy 'use server', a klienckie Actions mogą wywołać zwykłe API.
useActionState zamiast trzech stanów
useActionState scala wynik akcji, opakowany handler i flagę oczekiwania w jednym hooku. Ten sam krok podsumowania wygląda wtedy tak:
Hook zwraca trzy rzeczy: state, czyli ostatni wynik akcji (przy pierwszym renderze wartość początkową, tu null), formAction, czyli handler gotowy do wpisania w <form action={...}>, oraz isPending. Znikają osobne useState dla wysyłki, wyniku i błędu. Dane nadal pochodzą z Contextu, więc akcja nie czyta pól z FormData; formularz służy tu jako semantyczny kontener przycisku wysyłki.
Przycisk wysyłki jest osobnym komponentem, więc nie ma dostępu do isPending. Tę lukę wypełnia useFormStatus: odczytuje stan najbliższego formularza-przodka bez przekazywania propsów, ale działa wyłącznie w komponentach renderowanych wewnątrz <form>. Poza pending zwraca też data, method i action. Gdy do action przekazujesz funkcję, React wysyła formularz metodą POST niezależnie od atrybutu method.
Błędy pól z Server Action w useActionState
W krótkim, jednoetapowym formularzu (kontakt, newsletter) błędy pól możesz zwracać prosto z akcji. safeParse nie rzuca wyjątków, więc błędy walidacji trafiają do stanu formularza, a nie do Error Boundary:
Code
// app/kontakt/actions.ts'use server'import { z } from 'zod'const contactSchema = z.object({ email: z.email('Podaj prawidłowy adres e-mail.'), message: z.string().min(10, 'Wiadomość musi mieć co najmniej 10 znaków.'),})export type ContactFormState = { errors?: { email?: string[]; message?: string[]; _form?: string[] } success?: boolean}export async function contactAction( _prevState: ContactFormState, formData: FormData,): Promise<ContactFormState> { const parsed = contactSchema.safeParse({ email: formData.get('email'), message: formData.get('message'), }) if (!parsed.success) { return { errors: z.flattenError(parsed.error).fieldErrors } } try { await saveContactMessage(parsed.data) return { success: true } } catch { return { errors: { _form: ['Błąd serwera. Spróbuj ponownie za chwilę.'] } } }}
W komponencie wystarczy const [state, formAction, isPending] = useActionState(contactAction, {}) i wyświetlenie state.errors?.email pod polem, powiązane z nim przez aria-describedby. Błędy oczekiwane zwracaj jako stan, a nie jako throw, bo wyjątki trafiają do Error Boundary i rozbijają drzewo komponentów. Wyjątki zostaw dla awarii.
useOptimistic: kiedy ma sens, a kiedy nie
pokazuje zmianę w interfejsie w chwili kliknięcia, zanim serwer odpowie. Optymistyczny stan istnieje w trakcie akcji, a po jej zakończeniu widok wynika ze stanu bazowego przekazanego do useOptimistic. Klasyczny przykład to lista komentarzy:
useOptimistic nie ma osobnego mechanizmu „rollbacku przy błędzie”. Optymistyczny wpis znika, bo po zakończeniu akcji React renderuje stan bazowy, a ten zmieniasz tylko po sukcesie. Gdy akcja zawiedzie, interfejs wraca do poprzedniego widoku, a komunikat o błędzie dodajesz osobno. Sam addOptimistic działa tylko wewnątrz akcji lub startTransition; poza nimi React zgłasza ostrzeżenie w trybie deweloperskim. W Next.js akcja może zamiast setComments wywołać revalidatePath, a odświeżone dane z serwera zastąpią wpis tymczasowy.
Optimistic UI sprawdza się przy operacjach odwracalnych, z małym ryzykiem błędu: polubieniach, komentarzach czy przełącznikach. Nie stosuj go przy płatnościach, operacjach nieodwracalnych, danych wymagających walidacji serwerowej (unikalne slugi, dostępność terminu) ani długim przetwarzaniu. Zapytanie ofertowe z tego artykułu też do nich nie pasuje: użytkownik powinien zobaczyć realne potwierdzenie serwera, więc wystarczy pending z useFormStatus.
Progressive Enhancement i granice Actions
działa, gdy w action przekazujesz bezpośrednio Server Function oznaczoną 'use server'. Wtedy formularz można wysłać przed załadowaniem JavaScriptu albo przy wyłączonym JS, choć nadal potrzebne jest połączenie z serwerem. Kliencka funkcja w action bez JavaScriptu się nie wykona. Formularz wieloetapowy oparty na Contextcie i tak wymaga JavaScriptu do przechodzenia między krokami, więc tu korzyścią z Actions jest prostszy kod, a nie działanie bez JS.
Actions dobrze obsługują proste formularze zorientowane na serwer: kontakt, newsletter, edycję profilu. Są gorszym wyborem przy:
Dużych formularzach z walidacją na żywo, dziesiątkami pól i logiką
warunkową między sekcjami. Tu React Hook Form z Zodem daje precyzyjniejszą
kontrolę nad stanem po stronie klienta.
Podglądzie na żywo, gdzie zmiana pola nie powinna wywoływać akcji
serwera. Właściwym narzędziem jest wtedy useState z opóźnieniem
aktualizacji.
Przesyłaniu plików z paskiem postępu, bo Actions nie mają API do
odczytu postępu wysyłki.
Przy migracji istniejącego projektu nowe formularze pisz od razu z Actions, formularze oparte na React Hook Form zostaw bez zmian, a najlepszymi kandydatami do przepisania są proste formularze z onSubmit i kilkoma useState, bo zwykle pozwalają usunąć ręczną obsługę wysyłki.
useActionState nie jest zamiennikiem dla każdego useState. To narzędzie do
konkretnego wzorca: asynchroniczna akcja z wynikiem, stanem oczekiwania i
obsługą błędów.
— praktyka React 19
Elastyczne i wydajne narzędzia dla biznesu, które dotrzymają kroku Twojemu rozwojowi.
Jak zachować stan formularza po odświeżeniu strony?
Dodaj warstwę persist do Contextu, zapisuj dane i numer aktywnego kroku do sessionStorage przy każdej zmianie, a przy inicjalizacji wczytuj je z powrotem. Dzięki temu przypadkowe odświeżenie (F5) nie kasuje wypełnionych kroków ani nie cofa użytkownika na początek. Po udanym submicie wyczyść storage, żeby dane nie zostały na współdzielonym urządzeniu.
Jak zadbać o dostępność formularza wieloetapowego?
Cztery rzeczy robią największą różnicę: po zmianie kroku przenieś fokus na nagłówek nowego kroku (tabIndex={-1} + focus()), żeby czytnik ekranu ogłosił zmianę; każde pole powiąż z etykietą przez htmlFor/id; błędy wskaż przez aria-invalid i aria-describedby na polu; a progress bar zbuduj jako listę z aria-current="step" na aktywnym elemencie. Bez tego użytkownik czytnika po kliknięciu „Dalej" nie wie, że cokolwiek się zmieniło.
Ile kroków to za dużo?
3–5 kroków to optimum. Powyżej 5 użytkownik traci orientację. Jeśli formularz ma 30 pól, grupuj je logicznie (dane osobowe, projekt, preferencje), a nie mechanicznie (5 pól = 1 krok) — krok powinien odpowiadać jednemu spójnemu etapowi decyzji.
Czy URL powinien zmieniać się między krokami?
Opcjonalnie, np. /wycena?step=2. Daje to deep linking i działający przycisk „wstecz" w przeglądarce, ale dodaje złożoność — trzeba synchronizować searchParams ze stanem w Context. Dla krótkich formularzy zysk zwykle nie jest wart tej komplikacji.
Dlaczego niekontrolowane pola, a nie value + onChange?
Pola niekontrolowane z defaultValue nie wywołują re-renderu przy każdym wciśnięciu klawisza — wartości zbiera FormData dopiero przy submicie kroku. Dla długich formularzy to zauważalnie mniej pracy dla React. Kontrolowane pola wybieraj, gdy potrzebujesz live walidacji albo zależności między polami.
Czy walidacja po stronie klienta wystarczy?
Nie. Walidacja kliencka per krok to kwestia UX — natychmiastowy feedback. Zawsze powtórz pełną walidację (fullSchema.safeParse) w Server Action przed zapisem, bo żądanie można wysłać z pominięciem interfejsu. Klient nigdy nie jest źródłem prawdy o poprawności danych.
Czy w formularzu wieloetapowym warto użyć useActionState?
Tak, w kroku wysyłki. useActionState zastępuje osobne useState dla stanu wysyłki, wyniku i błędu, a useFormStatus pozwala przyciskowi odczytać stan oczekiwania bez przekazywania propsów. Stan między krokami nadal trzymasz w Context, a przy dużych formularzach z walidacją na żywo React Hook Form daje precyzyjniejszą kontrolę.
O autorze
Maciej Sala
Maciej Sala — konsultant technologiczny produktów cyfrowych i web developer z bogatym doświadczeniem w marketingu internetowym oraz SEO. Na co dzień pracuje z Reactem, Next.js i TypeScriptem, a ostatnio także z Astro i narzędziami do automatyzacji procesów AI. Sprawnie łączy perspektywę produktową z praktycznym podejściem do kodu. Przez kilka lat był związany z branżą gier wideo jako project manager i game designer. Absolwent historii na Uniwersytecie Jagiellońskim oraz studiów podyplomowych z marketingu internetowego na AGH w Krakowie. Po godzinach trenuje na siłowni, maluje figurki i rozwija własne projekty.
Klasyczny formularz bardzo szybko robi się ciężki przez takie elementy jak endpoint, odczytywanie ciała żądania, walidacja, statusy HTTP, fetch po stronie klienta i typy przepisane drugi raz. Na ratunek przybywają Astro Actions: wystarczy, że zdefiniujesz logikę funkcji serwerowej, dodasz schemat Zod i wywołasz ją z klienta bez ręcznego składania REST API.
Maciej Sala
Founder StriveLab
Next.js może obsługiwać interfejs, logikę biznesową i dostęp do bazy w jednym projekcie. Ten przewodnik pokazuje, jak połączyć komponenty serwerowe, Server Actions i Route Handlers z autoryzacją, cache i zadaniami w tle. Na przykładzie panelu zamówień przejdziemy od odczytu danych do zapisu i utrzymania na produkcji, wskazując momenty, w których warto wydzielić osobną usługę.
Maciej Sala
Founder StriveLab
Komponent działa lokalnie, ale po wdrożeniu na produkcję pojawia się niezgodność hydratacji ang. hydration mismatch , a prosta strona produktu pobiera kilkaset kilobajtów JavaScriptu. Zamiast natychmiast wyłączać SSR czy otaczać kod memoizacją, warto cofnąć się o krok. Problem rzadko leży w braku optymalizacji — częściej w braku decyzji, która część interfejsu realnie wymaga przeglądarki. React Server Components przesunęły granicę między serwerem a klientem. W App Routerze najpierw decydujemy, gdzie wykonać pracę, a dopiero potem dobieramy hooki i biblioteki.