Formulaires React : input, checkbox, select et validation

Un formulaire React garde la valeur de chaque champ dans l'état : le champ affiche value={state} et le met à jour avec onChange. Quand l'utilisateur envoie le formulaire, un gestionnaire onSubmit appelle e.preventDefault() pour empêcher le rechargement de la page, puis utilise les valeurs déjà présentes dans l'état.

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

Tapez un nom et appuyez sur Entrée ou cliquez sur le bouton. Supprimez ensuite la ligne e.preventDefault(); : l'aperçu montre les champs que le navigateur aurait envoyés lors d'un envoi natif, qui dans une vraie page la rechargerait aussi.

Un champ dont la valeur vient de l'état s'appelle un champ contrôlé. L'alternative, laisser le DOM garder la valeur et la lire plus tard, est traitée dans composants contrôlés et non contrôlés.

Champs texte et textarea

Chaque champ texte fonctionne de la même manière : value vient de l'état, onChange lit e.target.value. Un <textarea> suit le même pattern. En HTML, son texte se place entre les balises, mais en React vous le passez avec 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>
    );
}

Comme vous définissez la valeur vous-même, vous pouvez modifier ce que l'utilisateur a tapé avant que cela s'affiche : le champ titre met chaque lettre en majuscule. Le compteur de caractères se met à jour à chaque frappe, car body est un état et chaque modification provoque un nouveau rendu.

Select

Un <select> prend value sur l'élément select lui-même, pas selected sur une option. e.target.value est la value de l'option choisie.

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

Pour un select multiple, ajoutez multiple et passez un tableau dans value. Lisez les choix avec Array.from(e.target.selectedOptions, (o) => o.value).

Cases à cocher et boutons radio

Une case à cocher se contrôle avec checked, pas value, et son gestionnaire lit e.target.checked, qui vaut true ou false. Les boutons radio d'un groupe partagent un name ; chacun est coché quand l'état est égal à sa valeur.

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

Lire e.target.value sur une case à cocher est une erreur courante : pour une case sans attribut value, cela renvoie la chaîne "on", que la case soit cochée ou non.

Un seul objet d'état pour plusieurs champs

Un formulaire de dix champs n'a pas besoin de dix appels à useState et de dix gestionnaires. Gardez un seul objet, donnez à chaque champ un name qui correspond à une clé, et écrivez un seul gestionnaire qui utilise le nom comme clé calculée : [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>
    );
}

Le gestionnaire vérifie le type du champ pour que la case à cocher stocke un booléen et les autres du texte. Ajoutez un champ en ajoutant une clé à l'objet de départ et un input avec le même name ; le gestionnaire n'a pas besoin de changer. Le spread conserve tous les autres champs (voir mettre à jour tableaux et objets).

Envoyer un formulaire

Placez la logique d'envoi sur le onSubmit du formulaire, pas sur le onClick du bouton. onSubmit se déclenche aussi quand l'utilisateur appuie sur Entrée dans un champ texte, ce qu'un gestionnaire de clic manquerait. Un <button> dans un formulaire est par défaut un bouton d'envoi ; donnez aux autres boutons type="button" pour qu'ils n'envoient pas le formulaire.

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

Ouvrez la console, tapez un mot de passe et appuyez sur Entrée : le formulaire affiche l'objet entier. Cliquer sur "Clear" n'affiche rien, car il est type="button". Retirez cet attribut et Clear se met aussi à envoyer le formulaire.

Validation et affichage des erreurs

Une validation simple est une fonction qui prend les valeurs et renvoie un objet de messages. Exécutez-la à l'envoi, stockez le résultat dans l'état et affichez chaque message sous son champ. Désactivez le bouton d'envoi pendant qu'une requête est en cours pour qu'un double clic n'envoie pas le formulaire deux fois.

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

Cliquez sur Save avec les champs vides pour voir les deux messages, puis remplissez-les. saveProfile remplace une vraie requête : elle attend 800 millisecondes puis se résout. L'attribut noValidate désactive les bulles de validation du navigateur pour que seuls vos messages s'affichent ; retirez-le et ajoutez required à un champ pour comparer.

Les erreurs peuvent aussi être calculées pendant le rendu au lieu d'être stockées, par exemple const emailError = form.email && !form.email.includes('@'), ce qui affiche le message pendant la saisie. Choisissez le moment qui convient au formulaire : à l'envoi, c'est plus calme ; pendant la saisie, le retour est plus rapide.

Actions de formulaire dans React 19

React 19 ajoute une autre façon de gérer un formulaire. Passez une fonction à la prop action du formulaire. React empêche le rechargement de la page pour vous et appelle la fonction avec un objet FormData contenant chaque champ qui a un name. Les champs n'ont besoin d'aucun état : ils sont non contrôlés, et React les vide une fois l'action terminée.

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

Tapez votre propre commentaire et publiez-le. La liste affiche votre texte, et le champ revient à Nice docs : une fois l'action résolue, React remet les champs non contrôlés à leur defaultValue. L'action peut être asynchrone, et pendant son exécution React traite la mise à jour comme une transition.

Pour afficher un état d'attente ou une erreur de l'action, enveloppez-la avec useActionState, qui renvoie le dernier résultat, une action enveloppée pour le formulaire et un indicateur isPending. Un bouton placé profondément dans le formulaire peut aussi lire l'état d'attente avec useFormStatus de react-dom :

import { useFormStatus } from 'react-dom';

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

useFormStatus n'est pas chargé dans les éditeurs de cette page, il n'apparaît donc que dans ce bloc statique. Il doit être appelé depuis un composant rendu à l'intérieur du <form>, pas dans le composant qui affiche le formulaire.

L'état contrôlé avec onSubmit et les actions de formulaire avec FormData fonctionnent tous deux dans React 19. Les champs contrôlés conviennent aux formulaires qui réagissent pendant la saisie (validation en direct, compteur de caractères, champs qui dépendent les uns des autres). Les actions conviennent aux formulaires dont vous n'avez besoin des valeurs qu'au moment de l'envoi.