React 19 Actions — formularz bez onSubmit, useOptimistic i useActionState w praktyce

Czym są Actions

Action to funkcja wykonująca zmianę danych, często asynchroniczna. Funkcję przekazaną do action elementu <form> React uruchamia w Transition z obiektem FormData; po jej sukcesie resetuje niekontrolowane pola. Stan pending jest dostępny przez hooki, ale to Twój kod decyduje, czy np. wyłączyć przycisk submit.

Kliencka funkcja formularza nie jest tym samym co Server Function. Server Functions (często nazywane Server Actions w dokumentacji Next.js) wykonują kod na serwerze i wymagają wsparcia frameworka oraz dyrektywy 'use server'; klientskie Actions mogą wywołać zwykłe API.

Najprostszy formularz z Actions

function ContactForm() {
  async function sendMessage(formData: FormData) {
    const email = formData.get('email') as string
    const message = formData.get('message') as string
 
    const response = await fetch('/api/contact', {
      method: 'POST',
      body: JSON.stringify({ email, message }),
    })
 
    if (!response.ok) {
      throw new Error('Nie udało się wysłać formularza.')
    }
  }
 
  return (
    <form action={sendMessage}>
      <input name="email" type="email" required />
      <textarea name="message" required />
      <button type="submit">Wyślij</button>
    </form>
  )
}

Nie ma tu useState, preventDefault ani onSubmit. React wywoła akcję i po jej powodzeniu wyczyści niekontrolowane pola. Ten minimalny przykład nie wyłącza jednak przycisku w trakcie żądania; do tego służą isPending z useActionState albo pending z useFormStatus.

useActionState — jeden hook zamiast trzech stanów

W praktyce samo wpisanie akcji w form action nie wystarczy — trzeba obsłużyć błędy i sukces. Do tego służy useActionState.

import { useActionState } from 'react'
 
type FormState = {
  success?: boolean
  error?: string
}
 
async function contactAction(
  prevState: FormState,
  formData: FormData,
): Promise<FormState> {
  const email = formData.get('email') as string
  const message = formData.get('message') as string
 
  if (!email || !message) {
    return { error: 'Uzupełnij wszystkie pola.' }
  }
 
  try {
    const response = await fetch('/api/contact', {
      method: 'POST',
      body: JSON.stringify({ email, message }),
    })
 
    if (!response.ok) {
      return { error: 'Nie udało się wysłać wiadomości. Spróbuj ponownie.' }
    }
 
    return { success: true }
  } catch {
    return { error: 'Nie udało się wysłać wiadomości. Spróbuj ponownie.' }
  }
}
 
function ContactForm() {
  const [state, formAction, isPending] = useActionState(contactAction, {})
 
  if (state.success) {
    return <p>Wiadomość wysłana. Odezwę się wkrótce.</p>
  }
 
  return (
    <form action={formAction}>
      <input name="email" type="email" required />
      <textarea name="message" required />
      {state.error && <p className="error">{state.error}</p>}
      <button type="submit" disabled={isPending}>
        {isPending ? 'Wysyłanie...' : 'Wyślij'}
      </button>
    </form>
  )
}

Hook zwraca trzy rzeczy:

• state — ostatni wynik zwrócony przez akcję (przy pierwszym renderze to wartość inicjalna, tu {}),
• formAction — opakowany handler gotowy do wpisania w <form action={...}>,
• isPending — flaga true/false informująca, czy akcja jest w toku.

Dla porównania, ten sam formularz przed React 19 wymagał trzech osobnych wywołań useState (loading, error, success), ręcznego e.preventDefault() i obsługi błędów.

useFormStatus — stan pending w komponentach dzieci

Jeśli przycisk submit to osobny komponent, nie ma bezpośredniego dostępu do isPending z useActionState. useFormStatus rozwiązuje ten problem — odczytuje stan formularza-rodzica bez przekazywania propsów.

import { useFormStatus } from 'react-dom'
 
function SubmitButton({ children }: { children: React.ReactNode }) {
  const { pending } = useFormStatus()
 
  return (
    <button type="submit" disabled={pending}>
      {pending ? 'Wysyłanie...' : children}
    </button>
  )
}
 
function ContactForm() {
  return (
    <form action={sendMessage}>
      <input name="email" type="email" required />
      <textarea name="message" required />
      <SubmitButton>Wyślij wiadomość</SubmitButton>
    </form>
  )
}

Hook useFormStatus działa tylko wewnątrz komponentów renderowanych jako dzieci <form> i automatycznie szuka najbliższego formularza-przodka w drzewie React.

Poza pending zwraca też data (wysyłany FormData), method i action (referencja do funkcji akcji). Gdy do action lub formAction przekazujesz funkcję, React wysyła formularz metodą POST, niezależnie od atrybutu method.

useOptimistic — natychmiastowy feedback bez czekania na serwer

Optimistic UIOptimistic UI to wzorzec, w którym interfejs natychmiast pokazuje wynik akcji użytkownika, zakładając jej powodzenie, i wycofuje zmianę dopiero jeśli serwer zwróci błąd. pokazuje zmianę w interfejsie w chwili kliknięcia, jeszcze zanim serwer odpowie. Optymistyczny stan istnieje w trakcie akcji; po jej zakończeniu widok wynika ze stanu bazowego przekazanego do useOptimistic.

Klasyczny przykład to lista komentarzy:

import { useOptimistic, useState } from 'react'
 
type Comment = { id: string; text: string; pending?: boolean }
 
async function addComment(formData: FormData): Promise<Comment> {
  const text = formData.get('text') as string
  const response = await fetch('/api/comments', {
    method: 'POST',
    body: JSON.stringify({ text }),
  })
 
  if (!response.ok) {
    throw new Error('Nie udało się dodać komentarza.')
  }
 
  return response.json()
}
 
function Comments({ initialComments }: { initialComments: Comment[] }) {
  const [comments, setComments] = useState(initialComments)
  const [optimisticComments, addOptimistic] = useOptimistic(
    comments,
    (currentComments, newComment: Comment) => [...currentComments, newComment],
  )
 
  async function handleAction(formData: FormData) {
    const text = formData.get('text') as string
    addOptimistic({ id: crypto.randomUUID(), text, pending: true })
 
    const savedComment = await addComment(formData)
    setComments((current) => [...current, savedComment])
  }
 
  return (
    <>
      <ul>
        {optimisticComments.map((comment) => (
          <li key={comment.id}>
            {comment.text} {comment.pending && '(wysyłanie...)'}
          </li>
        ))}
      </ul>
      <form action={handleAction}>
        <input name="text" required />
        <button type="submit">Dodaj komentarz</button>
      </form>
    </>
  )
}

Użytkownik klika "Dodaj komentarz" → addOptimistic natychmiast dopisuje komentarz oczekujący → w tle idzie żądanie do API. Po sukcesie setComments aktualizuje potwierdzony stan bazowy danymi z serwera. Z kolei, jeśli akcja rzuci błąd i stan bazowy się nie zmieni, to po zakończeniu akcji tymczasowy wpis znika; na produkcji warto dodać do tego komunikat błędu lub Error Boundary.

Takie rozwiązanie zmniejsza odczuwalny czas oczekiwania, ponieważ użytkownik natychmiast widzi wpis oczekujący na potwierdzenie.

useTransition dla akcji poza formularzem

Nie każda akcja jest wyzwalana przez <form>. Przycisk "Lubię to" czy usuwanie elementu z listy to typowe przykłady akcji bez formularza. Tu sięgasz po useTransition.

import { useState, useTransition } from 'react'
 
function LikeButton({
  postId,
  initialLikes,
}: {
  postId: string
  initialLikes: number
}) {
  const [likes, setLikes] = useState(initialLikes)
  const [isPending, startTransition] = useTransition()
 
  const handleLike = () => {
    startTransition(async () => {
      setLikes((prev) => prev + 1)
      try {
        const response = await fetch(`/api/posts/${postId}/like`, {
          method: 'POST',
        })
        if (!response.ok) {
          throw new Error('Nie udało się zapisać polubienia.')
        }
      } catch {
        setLikes((prev) => prev - 1)
      }
    })
  }
 
  return (
    <button onClick={handleLike} disabled={isPending}>
      ❤️ {likes}
    </button>
  )
}

W React 19 asynchroniczna funkcja uruchamiana w startTransition jest określana jako Action. useTransition zapewnia tu isPending, ale nie dodaje semantyki formularza: nie przekazuje FormData, nie resetuje pól i nie zapewnia Progressive Enhancement.

Walidacja z Zod i useActionState

Zod dobrze współpracuje z useActionState, bo pozwala zwrócić błędy pól w stanie formularza. Poniższy przykład waliduje dane przed wysłaniem do API; ten sam schemat należy zastosować również w endpointcie lub Server Function, bo walidacja klienta nie chroni serwera.

import { z } from 'zod'
 
const ContactSchema = z.object({
  email: z.string().email('Podaj prawidłowy adres e-mail.'),
  message: z.string().min(10, 'Wiadomość musi mieć co najmniej 10 znaków.'),
})
 
type ContactFormState = {
  errors?: {
    email?: string[]
    message?: string[]
    _form?: string[]
  }
  success?: boolean
}
 
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: parsed.error.flatten().fieldErrors }
  }
 
  try {
    const response = await fetch('/api/contact', {
      method: 'POST',
      body: JSON.stringify(parsed.data),
    })
 
    if (!response.ok) {
      return {
        errors: { _form: ['Błąd serwera. Spróbuj ponownie za chwilę.'] },
      }
    }
 
    return { success: true }
  } catch {
    return { errors: { _form: ['Błąd serwera. Spróbuj ponownie za chwilę.'] } }
  }
}
 
function ContactForm() {
  const [state, formAction, isPending] = useActionState(contactAction, {})
 
  if (state.success) {
    return <p>Wiadomość wysłana.</p>
  }
 
  return (
    <form action={formAction}>
      <div>
        <label htmlFor="email">E-mail</label>
        <input id="email" name="email" type="email" />
        {state.errors?.email?.map((err) => (
          <p key={err} className="error">
            {err}
          </p>
        ))}
      </div>
 
      <div>
        <label htmlFor="message">Wiadomość</label>
        <textarea id="message" name="message" />
        {state.errors?.message?.map((err) => (
          <p key={err} className="error">
            {err}
          </p>
        ))}
      </div>
 
      {state.errors?._form?.map((err) => (
        <p key={err} className="error">
          {err}
        </p>
      ))}
 
      <button type="submit" disabled={isPending}>
        {isPending ? 'Wysyłanie...' : 'Wyślij'}
      </button>
    </form>
  )
}

z.safeParse nie rzuca wyjątków — zwraca obiekt z polem success i, w przypadku błędu, error. Błędy walidacji lądują w stanie formularza, a nie w Error Boundary. W Next.js walidację umieść w Server Function; przy klasycznym API powtórz ją w endpointcie.

Więcej o łączeniu walidacji z React Hook Form i Zodem opisuję w artykule React Hook Form + Zod w Next.js.

Progressive Enhancement

Progressive EnhancementProgressive Enhancement — podejście do budowania funkcji tak, aby działały poprawnie nawet bez JavaScriptu w przeglądarce. dla funkcji przekazywanych do action działa z Server Functions oznaczonymi 'use server'. W takim przypadku framework umożliwia przesłanie danych formularza do serwera bez potrzeby załadowania JavaScriptu. Formularz może działać przed hydracją albo przy wyłączonym JS, o ile przeglądarka ma połączenie z serwerem.

Kliencka funkcja w action w aplikacji CSR (np. Vite) nie wykona się bez JavaScriptu. Jeśli zależy Ci na PE z React Server Functions, potrzebujesz Next.js z App Routerem lub innego frameworka wspierającego tę integrację.

Typowe pułapki

Kilka rzeczy, które regularnie powodują problemy przy pierwszym kontakcie z Actions:

• useActionState dostaje poprzedni stan jako pierwszy argument — sygnatura funkcji akcji to (prevState, formData), nie (formData). Pominięcie prevState skutkuje błędem typowania albo nieprawidłowym zachowaniem przy kolejnych wywołaniach.
• useOptimistic działa tylko wewnątrz akcji lub startTransition — próba wywołania addOptimistic poza tymi kontekstami rzuca ostrzeżenie w trybie dev.
• Nie rzucaj wyjątków z akcji do walidacji — błąd zamiast throw new Error(...) powinien wychodzić jako zwrócony obiekt { error: '...' }. Wyjątki trafiają do Error Boundary i rozbijają drzewo komponentów.
• Upload plików to osobny problem — Actions nie mają API do śledzenia postępu przesyłania. Do uploaderów z procentowym paskiem postępu użyj np. XMLHttpRequest albo biblioteki oferującej upload progress.

Kiedy nie używać Actions

Actions działają świetnie przy operacjach CRUD zorientowanych na serwer. Są niewłaściwym wyborem w trzech sytuacjach:

• Duże formularze wieloetapowe z dziesiątkami pól, walidacją na żywo i logiką warunkową między sekcjami. Tu React Hook Form z Zodem daje precyzyjniejszą kontrolę nad stanem po stronie klienta.
• Podgląd na żywo (np. edytor Markdown z preview obok) — każda zmiana w polu nie powinna wyzwalać akcji serwera. Klasyczny useState z debouncingiem jest tu właściwym narzędziem.
• Przesyłanie plików z paskiem postępu — brak natywnego API do odczytu procentowego postępu przesyłania.

Migracja z onSubmit

Jeśli masz istniejący projekt z formularzami opartymi na onSubmit + useState, warto zacząć migrację od najprostszych przypadków:

1. Nowe formularze — od razu pisz z Actions.
2. Formularze z React Hook Form — zostaw je bez zmian, chyba że chcesz uprościć konkretny komponent.
3. Proste formularze z onSubmit + useState — to najlepsi kandydaci do migracji, bo zwykle pozwalają usunąć ręczną obsługę stanu pending i submitu.