Formularios en React: inputs, checkbox, select y validación

Un formulario de React guarda el valor de cada campo en el estado: el input muestra value={state} y lo actualiza con onChange. Cuando el usuario envía, un manejador onSubmit llama a e.preventDefault() para evitar la recarga de la página y luego usa los valores que ya están en el 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>
    );
}

Escribe un nombre y pulsa Enter o haz clic en el botón. Luego borra la línea e.preventDefault();: la vista previa muestra los campos que el navegador habría enviado en un envío nativo, que en una página real también la recargaría.

Un input cuyo valor viene del estado se llama input controlado. La alternativa, dejar que el DOM guarde el valor y leerlo después, se explica en componentes controlados vs no controlados.

Inputs de texto y textarea

Todos los campos de texto funcionan igual: value desde el estado, onChange lee e.target.value. Un <textarea> sigue el mismo patrón. En HTML su texto va entre las etiquetas, pero en React lo pasas 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 tú defines el valor, puedes cambiar lo que escribió el usuario antes de que se muestre: el campo de título convierte cada letra en mayúscula. El contador de caracteres se actualiza en cada pulsación porque body es estado y cada cambio vuelve a renderizar.

Select

Un <select> recibe value en el propio elemento select, no selected en una opción. e.target.value es el value de la opción elegida.

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 un select múltiple, agrega multiple y pasa un array como value. Lee las opciones elegidas con Array.from(e.target.selectedOptions, (o) => o.value).

Casillas y botones de radio

Una casilla se controla con checked, no con value, y su manejador lee e.target.checked, que es true o false. Los botones de radio de un grupo comparten un name; cada uno está marcado cuando el estado es igual a su valor.

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

Leer e.target.value en una casilla es un error común: en una casilla sin atributo value devuelve la cadena "on" esté marcada o no.

Un objeto de estado para muchos campos

Un formulario con diez campos no necesita diez llamadas a useState y diez manejadores. Guarda un objeto, dale a cada input un name que coincida con una clave y escribe un solo manejador que use el nombre como clave 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>
    );
}

El manejador revisa el tipo de input para que la casilla guarde un booleano y los demás guarden texto. Agrega un campo agregando una clave al objeto inicial y un input con el mismo name; el manejador no necesita cambios. La propagación conserva todos los demás campos (consulta actualizar arrays y objetos).

Enviar un formulario

Pon la lógica de envío en el onSubmit del formulario, no en el onClick del botón. onSubmit también se dispara cuando el usuario pulsa Enter en un campo de texto, algo que un manejador de clic no captaría. Un <button> dentro de un formulario es un botón de envío por defecto; dale type="button" a los demás botones para que no envíen.

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

Abre la consola, escribe una contraseña y pulsa Enter: el formulario registra el objeto completo. Hacer clic en "Clear" no registra nada, porque es type="button". Quita ese atributo y Clear también empieza a enviar.

Validación y mostrar errores

Una validación simple es una función que recibe los valores y devuelve un objeto de mensajes. Ejecútala al enviar, guarda el resultado en el estado y muestra cada mensaje bajo su campo. Deshabilita el botón de envío mientras una petición está en curso para que un doble clic no envíe el formulario dos veces.

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

Haz clic en Save con los campos vacíos para ver ambos mensajes, y luego rellénalos. saveProfile sustituye a una petición real: espera 800 milisegundos y se resuelve. El atributo noValidate desactiva las burbujas de validación propias del navegador para que solo se vean tus mensajes; quítalo y agrega required a un input para comparar.

Los errores también se pueden calcular durante el renderizado en lugar de guardarse, por ejemplo const emailError = form.email && !form.email.includes('@'), que muestra el mensaje mientras el usuario escribe. Elige el momento que mejor le vaya al formulario: al enviar es más tranquilo, mientras se escribe da una respuesta más rápida.

Acciones de formulario en React 19

React 19 agrega otra forma de manejar un formulario. Pasa una función a la prop action del formulario. React evita la recarga de la página por ti y llama a la función con un objeto FormData que contiene cada campo que tiene un name. Los campos no necesitan estado en absoluto: son no controlados, y React los vacía cuando termina la acción.

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

Escribe tu propio comentario y publícalo. La lista muestra tu texto, y el input vuelve a Nice docs: cuando la acción se resuelve, React reinicia los campos no controlados a su defaultValue. La acción puede ser async, y mientras se ejecuta React trata la actualización como una transición.

Para mostrar un estado pendiente o un error de la acción, envuélvela con useActionState, que devuelve el último resultado, una acción envuelta para el formulario y un indicador isPending. Un botón muy dentro del formulario también puede leer el estado pendiente con useFormStatus de react-dom:

import { useFormStatus } from 'react-dom';

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

useFormStatus no se carga en los editores de aquí, así que aparece solo en este bloque estático. Debe llamarse desde un componente renderizado dentro del <form>, no en el componente que renderiza el formulario.

El estado controlado con onSubmit y las acciones de formulario con FormData funcionan ambos en React 19. Los campos controlados sirven para formularios que reaccionan mientras escribes (validación en vivo, un contador de caracteres, campos que dependen entre sí). Las acciones sirven para formularios donde solo necesitas los valores cuando el usuario envía.