Formularze w React: pola, checkboxy, select i walidacja

Formularz w React trzyma wartość każdego pola w stanie: pole pokazuje value={state} i aktualizuje ją przez onChange. Gdy użytkownik wysyła formularz, handler onSubmit wywołuje e.preventDefault(), żeby zatrzymać przeładowanie strony, a potem używa wartości, które już są w stanie.

import { useState } from 'react';

export default function App() {
    const [name, setName] = useState('');
    const [greeting, setGreeting] = useState('');

    function handleSubmit(e) {
        e.preventDefault();
        setGreeting(`Hello, ${name || 'stranger'}!`);
    }

    return (
        <form onSubmit={handleSubmit}>
            <label>
                Name{' '}
                <input name="name" value={name} onChange={(e) => setName(e.target.value)} />
            </label>{' '}
            <button type="submit">Say hello</button>
            <p>{greeting}</p>
        </form>
    );
}

Wpisz imię i naciśnij Enter albo kliknij przycisk. Potem usuń linię e.preventDefault();: podgląd pokaże pola, które przeglądarka wysłałaby przy natywnym wysłaniu, które na prawdziwej stronie dodatkowo by ją przeładowało.

Pole, którego wartość pochodzi ze stanu, nazywa się polem kontrolowanym. Alternatywę, czyli pozwolenie DOM na przechowywanie wartości i odczytanie jej później, omawia strona o komponentach kontrolowanych i niekontrolowanych.

Pola tekstowe i textarea

Każde pole tekstowe działa tak samo: value ze stanu, onChange odczytuje e.target.value. <textarea> stosuje ten sam wzorzec. W HTML jej tekst trafia między tagi, ale w React przekazujesz go jako value.

import { useState } from 'react';

export default function App() {
    const [title, setTitle] = useState('');
    const [body, setBody] = useState('');

    return (
        <div style={{ display: 'grid', gap: 8, maxWidth: 320 }}>
            <input
                value={title}
                onChange={(e) => setTitle(e.target.value.toUpperCase())}
                placeholder="Title (shouts)"
            />
            <textarea
                value={body}
                onChange={(e) => setBody(e.target.value)}
                rows={4}
                maxLength={140}
                placeholder="Up to 140 characters"
            />
            <small>{140 - body.length} characters left</small>
        </div>
    );
}

Ponieważ sam ustawiasz wartość, możesz zmienić to, co wpisał użytkownik, zanim się pokaże: pole tytułu zamienia każdą literę na wielką. Licznik znaków aktualizuje się przy każdym naciśnięciu klawisza, bo body jest stanem, a każda zmiana renderuje ponownie.

Select

<select> przyjmuje value na samym elemencie select, a nie selected na opcji. e.target.value to value wybranej opcji.

import { useState } from 'react';

export default function App() {
    const [plan, setPlan] = useState('monthly');
    const prices = { monthly: '$12 a month', yearly: '$99 a year', free: '$0' };

    return (
        <div>
            <select value={plan} onChange={(e) => setPlan(e.target.value)}>
                <option value="free">Free</option>
                <option value="monthly">Monthly</option>
                <option value="yearly">Yearly</option>
            </select>
            <p>You pay {prices[plan]}.</p>
        </div>
    );
}

Przy wielokrotnym wyborze dodaj multiple i przekaż tablicę jako value. Wybrane opcje odczytasz przez Array.from(e.target.selectedOptions, (o) => o.value).

Pola wyboru i przyciski radio

Pole wyboru kontroluje się przez checked, a nie value, a jego handler odczytuje e.target.checked, czyli true albo false. Przyciski radio w grupie mają wspólne name; każdy jest zaznaczony, gdy stan równa się jego wartości.

import { useState } from 'react';

export default function App() {
    const [newsletter, setNewsletter] = useState(false);
    const [size, setSize] = useState('m');

    return (
        <div>
            <label>
                <input
                    type="checkbox"
                    checked={newsletter}
                    onChange={(e) => setNewsletter(e.target.checked)}
                />
                Send me the newsletter
            </label>

            <p>Shirt size:</p>
            {['s', 'm', 'l'].map((s) => (
                <label key={s} style={{ marginInlineEnd: 12 }}>
                    <input
                        type="radio"
                        name="size"
                        value={s}
                        checked={size === s}
                        onChange={(e) => setSize(e.target.value)}
                    />
                    {s.toUpperCase()}
                </label>
            ))}

            <p>
                Size {size.toUpperCase()}, newsletter {newsletter ? 'on' : 'off'}.
            </p>
        </div>
    );
}

Odczyt e.target.value na polu wyboru to częsty błąd: dla pola bez atrybutu value zwraca tekst "on" niezależnie od tego, czy pole jest zaznaczone.

Jeden obiekt stanu dla wielu pól

Formularz z dziesięcioma polami nie potrzebuje dziesięciu wywołań useState i dziesięciu handlerów. Trzymaj jeden obiekt, nadaj każdemu polu name odpowiadające kluczowi i napisz jeden handler, który używa nazwy jako wyliczanego klucza: [e.target.name].

import { useState } from 'react';

export default function App() {
    const [form, setForm] = useState({
        email: '',
        country: 'NO',
        terms: false,
    });

    function handleChange(e) {
        const { name, type, value, checked } = e.target;
        setForm({ ...form, [name]: type === 'checkbox' ? checked : value });
    }

    return (
        <div style={{ display: 'grid', gap: 8, maxWidth: 280 }}>
            <input name="email" value={form.email} onChange={handleChange} placeholder="Email" />
            <select name="country" value={form.country} onChange={handleChange}>
                <option value="NO">Norway</option>
                <option value="JP">Japan</option>
                <option value="BR">Brazil</option>
            </select>
            <label>
                <input name="terms" type="checkbox" checked={form.terms} onChange={handleChange} />
                I accept the terms
            </label>
            <pre>{JSON.stringify(form, null, 2)}</pre>
        </div>
    );
}

Handler sprawdza typ pola, żeby pole wyboru zapisywało wartość logiczną, a pozostałe tekst. Nowe pole dodajesz, dodając klucz do obiektu początkowego i pole z tym samym name; handler nie wymaga zmian. Spread zachowuje każde inne pole (zobacz aktualizowanie tablic i obiektów).

Wysyłanie formularza

Logikę wysyłania umieść w onSubmit formularza, a nie w onClick przycisku. onSubmit uruchamia się też, gdy użytkownik naciśnie Enter w polu tekstowym, czego handler kliknięcia by nie wychwycił. <button> wewnątrz formularza jest domyślnie przyciskiem wysyłania; innym przyciskom nadaj type="button", żeby nie wysyłały formularza.

import { useState } from 'react';

export default function App() {
    const [form, setForm] = useState({ user: 'ada', password: '' });

    function handleChange(e) {
        setForm({ ...form, [e.target.name]: e.target.value });
    }

    function handleSubmit(e) {
        e.preventDefault();
        console.log('submitting', form);
    }

    return (
        <form onSubmit={handleSubmit}>
            <input name="user" value={form.user} onChange={handleChange} />{' '}
            <input name="password" type="password" value={form.password} onChange={handleChange} />{' '}
            <button type="button" onClick={() => setForm({ user: '', password: '' })}>
                Clear
            </button>{' '}
            <button type="submit">Log in</button>
        </form>
    );
}

Otwórz konsolę, wpisz hasło i naciśnij Enter: formularz wypisze cały obiekt. Kliknięcie "Clear" niczego nie wypisuje, bo ma type="button". Usuń ten atrybut, a Clear też zacznie wysyłać formularz.

Walidacja i pokazywanie błędów

Prosta walidacja to funkcja, która przyjmuje wartości i zwraca obiekt z komunikatami. Uruchom ją przy wysyłaniu, zapisz wynik w stanie i pokaż każdy komunikat pod jego polem. Wyłącz przycisk wysyłania na czas trwania żądania, żeby podwójne kliknięcie nie wysłało formularza dwa razy.

import { useState } from 'react';

function validate({ email, age }) {
    const errors = {};
    if (!email.includes('@')) errors.email = 'Enter a valid email.';
    if (!age || Number(age) < 13) errors.age = 'You must be 13 or older.';
    return errors;
}

function saveProfile(data) {
    return new Promise((resolve) => setTimeout(() => resolve(data), 800));
}

export default function App() {
    const [form, setForm] = useState({ email: '', age: '' });
    const [errors, setErrors] = useState({});
    const [status, setStatus] = useState('idle');

    async function handleSubmit(e) {
        e.preventDefault();
        const found = validate(form);
        setErrors(found);
        if (Object.keys(found).length > 0) return;
        setStatus('saving');
        await saveProfile(form);
        setStatus('saved');
    }

    const change = (e) => setForm({ ...form, [e.target.name]: e.target.value });
    const error = { color: 'crimson', margin: '4px 0 8px', fontSize: 13 };

    return (
        <form onSubmit={handleSubmit} noValidate>
            <input name="email" value={form.email} onChange={change} placeholder="Email" />
            {errors.email && <p style={error}>{errors.email}</p>}
            <input name="age" type="number" value={form.age} onChange={change} placeholder="Age" />
            {errors.age && <p style={error}>{errors.age}</p>}
            <div style={{ marginTop: 8 }}>
                <button disabled={status === 'saving'}>
                    {status === 'saving' ? 'Saving...' : 'Save'}
                </button>
                {status === 'saved' && ' Saved.'}
            </div>
        </form>
    );
}

Kliknij Save przy pustych polach, żeby zobaczyć oba komunikaty, a potem je wypełnij. saveProfile zastępuje prawdziwe żądanie: czeka 800 milisekund i się rozwiązuje. Atrybut noValidate wyłącza własne dymki walidacji przeglądarki, żeby pokazywały się tylko twoje komunikaty; usuń go i dodaj required do pola, żeby porównać.

Błędy można też wyliczać podczas renderowania zamiast je przechowywać, na przykład const emailError = form.email && !form.email.includes('@'), co pokazuje komunikat w trakcie pisania. Wybierz moment, który pasuje do formularza: przy wysyłaniu jest spokojniej, a w trakcie pisania informacja zwrotna przychodzi szybciej.

Akcje formularzy w React 19

React 19 dodaje kolejny sposób obsługi formularza. Przekaż funkcję do propsa action formularza. React sam zablokuje przeładowanie strony i wywoła funkcję z obiektem FormData, który zawiera każde pole mające name. Pola w ogóle nie potrzebują stanu: są niekontrolowane, a React czyści je po zakończeniu akcji.

import { useState } from 'react';

function addComment(text) {
    return new Promise((resolve) => setTimeout(() => resolve(text), 500));
}

export default function App() {
    const [comments, setComments] = useState([]);

    async function postComment(formData) {
        const text = formData.get('comment');
        console.log('action received', text);
        const saved = await addComment(text);
        setComments((list) => [...list, saved]);
    }

    return (
        <form action={postComment}>
            <input name="comment" defaultValue="Nice docs" />{' '}
            <button type="submit">Post</button>
            <ul>
                {comments.map((c, i) => (
                    <li key={i}>{c}</li>
                ))}
            </ul>
        </form>
    );
}

Wpisz własny komentarz i opublikuj go. Lista pokazuje twój tekst, a pole wraca do Nice docs: po rozwiązaniu akcji React resetuje niekontrolowane pola do ich defaultValue. Akcja może być asynchroniczna, a w trakcie jej działania React traktuje aktualizację jako przejście (transition).

Żeby pokazać stan oczekiwania albo błąd z akcji, owiń ją w useActionState, który zwraca najnowszy wynik, opakowaną akcję dla formularza i flagę isPending. Przycisk głęboko w formularzu może też odczytać stan oczekiwania przez useFormStatus z react-dom:

import { useFormStatus } from 'react-dom';

function SubmitButton() {
    const { pending } = useFormStatus();
    return <button disabled={pending}>{pending ? 'Posting...' : 'Post'}</button>;
}

useFormStatus nie jest załadowany w tutejszych edytorach, więc pojawia się tylko w tym statycznym bloku. Trzeba go wywołać z komponentu wyrenderowanego wewnątrz <form>, a nie w komponencie, który renderuje formularz.

W React 19 działają oba podejścia: kontrolowany stan z onSubmit i akcje formularzy z FormData. Pola kontrolowane pasują do formularzy, które reagują w trakcie pisania (walidacja na żywo, licznik znaków, pola zależne od siebie). Akcje pasują do formularzy, w których wartości potrzebujesz dopiero przy wysłaniu.