Formulários no React: inputs, checkbox, select e validação

Um formulário React guarda o valor de cada campo no estado: o input mostra value={state} e o atualiza com onChange. Quando o usuário envia, um handler de onSubmit chama e.preventDefault() para impedir o recarregamento da página e depois usa os valores que já estão no estado.

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>
    );
}

Digite um nome e aperte Enter ou clique no botão. Depois apague a linha e.preventDefault();: a prévia mostra os campos que o navegador teria enviado em um envio nativo, o que em uma página real também a recarregaria.

Um input cujo valor vem do estado se chama input controlado. A alternativa, deixar o DOM guardar o valor e lê-lo depois, é tratada em componentes controlados vs não controlados.

Inputs de texto e textarea

Todo campo de texto funciona do mesmo jeito: value vem do estado e onChange lê e.target.value. Um <textarea> segue o mesmo padrão. No HTML o texto dele vai entre as tags, mas no React você o passa como 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>
    );
}

Como é você que define o valor, dá para mudar o que o usuário digitou antes de aparecer: o campo de título transforma cada letra em maiúscula. O contador de caracteres atualiza a cada tecla porque body é estado e cada mudança renderiza de novo.

Select

Um <select> recebe value no próprio elemento select, não selected em uma option. e.target.value é o value da opção escolhida.

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>
    );
}

Para um select múltiplo, adicione multiple e passe um array como value. Leia as escolhas com Array.from(e.target.selectedOptions, (o) => o.value).

Checkbox e botões de rádio

Um checkbox é controlado com checked, não value, e o handler dele lê e.target.checked, que é true ou false. Botões de rádio de um mesmo grupo compartilham um name; cada um fica marcado quando o estado é igual ao valor dele.

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>
    );
}

Ler e.target.value em um checkbox é um erro comum: em um checkbox sem atributo value ele retorna a string "on" esteja a caixa marcada ou não.

Um objeto de estado para vários campos

Um formulário com dez campos não precisa de dez chamadas de useState e dez handlers. Mantenha um objeto, dê a cada input um name que corresponda a uma chave e escreva um único handler que use o nome como chave calculada: [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>
    );
}

O handler confere o tipo do input para que o checkbox guarde um booleano e os outros guardem texto. Adicione um campo acrescentando uma chave ao objeto inicial e um input com o mesmo name; o handler não precisa mudar. O spread mantém todos os outros campos (veja atualizar arrays e objetos).

Enviando um formulário

Coloque a lógica de envio no onSubmit do formulário, não no onClick do botão. O onSubmit também dispara quando o usuário aperta Enter em um campo de texto, o que um handler de clique perderia. Um <button> dentro de um formulário é um botão de envio por padrão; dê type="button" aos outros botões para que não enviem.

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>
    );
}

Abra o console, digite uma senha e aperte Enter: o formulário registra o objeto inteiro. Clicar em "Clear" não registra nada, porque ele é type="button". Remova esse atributo e o Clear também passa a enviar.

Validação e exibição de erros

Uma validação simples é uma função que recebe os valores e retorna um objeto de mensagens. Execute-a no envio, guarde o resultado no estado e mostre cada mensagem abaixo do campo correspondente. Desabilite o botão de envio enquanto uma requisição estiver em andamento para que um clique duplo não envie o formulário duas vezes.

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>
    );
}

Clique em Save com os campos vazios para ver as duas mensagens e depois preencha-os. saveProfile faz o papel de uma requisição real: espera 800 milissegundos e resolve. O atributo noValidate desliga os balões de validação do próprio navegador para que só as suas mensagens apareçam; tire-o e adicione required a um input para comparar.

Os erros também podem ser calculados durante a renderização em vez de guardados, por exemplo const emailError = form.email && !form.email.includes('@'), que mostra a mensagem enquanto o usuário digita. Escolha o momento que combina com o formulário: no envio é mais tranquilo, durante a digitação dá um retorno mais rápido.

Form actions no React 19

O React 19 adiciona outra forma de lidar com um formulário. Passe uma função para a prop action do formulário. O React evita o recarregamento da página para você e chama a função com um objeto FormData que contém todos os campos que têm um name. Os campos nem precisam de estado: eles são não controlados, e o React os limpa depois que a action termina.

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>
    );
}

Digite o seu próprio comentário e publique. A lista mostra o seu texto, e o input volta para Nice docs: depois que a action resolve, o React reinicia os campos não controlados para o defaultValue deles. A action pode ser assíncrona, e enquanto ela roda o React trata a atualização como uma transição.

Para mostrar um estado pendente ou um erro vindo da action, envolva-a com useActionState, que retorna o resultado mais recente, uma action envolvida para o formulário e um indicador isPending. Um botão bem dentro do formulário também pode ler o estado pendente com useFormStatus de react-dom:

import { useFormStatus } from 'react-dom';

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

O useFormStatus não é carregado nos editores daqui, então aparece só neste bloco estático. Ele precisa ser chamado em um componente renderizado dentro do <form>, não no componente que renderiza o formulário.

Estado controlado com onSubmit e form actions com FormData funcionam no React 19. Campos controlados combinam com formulários que reagem enquanto você digita (validação ao vivo, um contador de caracteres, campos que dependem uns dos outros). Actions combinam com formulários em que você só precisa dos valores quando o usuário envia.