Pourquoi cette combinaison ?
Faire un formulaire en React "à la main" avec useState devient vite complexe : gérer chaque champ, les erreurs, la soumission, les états loading… Cette stack divise chaque responsabilité clairement.
{"// Un champ = 3 lignes de state"} const [nom, setNom] = useState(''); const [nomErr, setNomErr] = useState(''); const [email, setEmail] = useState(''); const [emailErr, setEmailErr]= useState(''); {"// × 5 champs = 10 useState !"} {"// + logique de validation manuelle"} {"// + gestion des re-renders"} {"// = ~150 lignes pour un formulaire"}
{"// Zod : définir les règles une fois"} const schema = z.object({ nom: z.string().min(2), email: z.string().email(), }); {"// RHF : brancher automatiquement"} const { register, handleSubmit, formState: { errors } } = useForm({ resolver: zodResolver(schema) }); {"// = ~40 lignes, tout géré"}
Installer et configurer la stack
Trois packages à installer dans un projet React existant (créé avec Vite ou Create React App).
@mui/material → composants MUI (TextField, Button…) @emotion/react → dépendance CSS-in-JS de MUI @emotion/styled → dépendance CSS-in-JS de MUI @mui/icons-material → icônes Material (optionnel mais utile) react-hook-form → gestion des formulaires zod → validation par schéma @hookform/resolvers → pont entre RHF et Zod
import React from 'react'; import ReactDOM from 'react-dom/client'; import { ThemeProvider, CssBaseline } from '@mui/material'; import { createTheme } from '@mui/material/styles'; import App from './App'; {"// Thème par défaut — personnalisable"} const theme = createTheme({ palette: { primary: { main: '#1565C0' }, }, typography: { fontFamily: 'Space Grotesk, sans-serif', }, }); ReactDOM.createRoot(document.getElementById('root')).render( <ThemeProvider theme={theme}> <CssBaseline /> {"← reset CSS global de MUI"} <App /> </ThemeProvider> );
Définir les règles avec Zod
Zod permet de décrire la forme et les contraintes des données avec un schéma JavaScript. Ce schéma devient la source de vérité unique pour la validation — côté formulaire et côté API.
import { z } from 'zod'; {"// Chaîne de caractères"} z.string() z.string().min(2, 'Minimum 2 caractères') z.string().max(50) z.string().email('Email invalide') z.string().url('URL invalide') z.string().regex(/^\d{9}$/, 'Format: 9 chiffres') z.string().nonempty('Champ obligatoire') {"// Nombre"} z.number().min(0, 'Note >= 0') z.number().max(20, 'Note <= 20') z.number().int('Nombre entier requis') z.number().positive('Doit être positif') {"// Enum (valeurs prédéfinies)"} z.enum(['info', 'reseaux', 'cyber']) {"// Optionnel"} z.string().optional() {"// peut être undefined"} z.string().nullable() {"// peut être null"}
import { z } from 'zod'; export const schemaEtudiant = z.object({ nom: z.string() .min(2, 'Le nom doit avoir au moins 2 caractères') .max(50, 'Le nom ne peut pas dépasser 50 caractères'), email: z.string() .email('Adresse email invalide') .nonempty('L\'email est obligatoire'), filiere: z.enum(['info', 'reseaux', 'cyber'], { errorMap: () => ({ message: 'Veuillez choisir une filière' }) }), note: z.number({ invalid_type_error: 'La note doit être un nombre' }) .min(0, 'La note minimum est 0') .max(20, 'La note maximum est 20'), boursier: z.boolean().default(false), telephone: z.string() .regex(/^\+?[\d\s\-]{8,15}$/, 'Numéro invalide') .optional(), {"← champ facultatif"} });
const schemaMotDePasse = z.object({ motDePasse: z.string().min(8, '8 caractères minimum'), confirmerMotDePasse: z.string(), }).refine( (data) => data.motDePasse === data.confirmerMotDePasse, { message: 'Les mots de passe ne correspondent pas', path: ['confirmerMotDePasse'], {"← sur quel champ afficher l'erreur"} } );
Gérer les champs avec useForm
React Hook Form fournit un hook useForm() qui gère tout : enregistrement des champs, récupération des valeurs, déclenchement de la validation, état du formulaire (loading, erreurs…).
import { useForm } from 'react-hook-form'; import { zodResolver } from '@hookform/resolvers/zod'; import { schemaEtudiant } from './schema-etudiant'; const { register, {"← enregistre un champ (name, onChange, onBlur, ref)"} handleSubmit, {"← wrapper pour la soumission"} formState: { errors, {"← objet { nomChamp: { message: '...' } }"} isSubmitting, {"← true pendant la soumission"} isValid, {"← true si pas d'erreurs"} isDirty, {"← true si l'utilisateur a modifié quelque chose"} }, reset, {"← remet le formulaire à zéro"} watch, {"← observer la valeur d'un champ en temps réel"} setValue, {"← modifier la valeur d'un champ programmatiquement"} } = useForm({ resolver: zodResolver(schemaEtudiant), {"← brancher Zod"} defaultValues: { {"← valeurs initiales"} nom: '', email: '', filiere: '', note: 0, boursier: false, }, mode: 'onBlur', {"← valider quand l'utilisateur quitte le champ"} });
function FormulaireBasique() { const { register, handleSubmit, formState: { errors } } = useForm({ resolver: zodResolver(schemaEtudiant), }); function onSubmit(data) { {"// data est l'objet validé — types corrects garantis par Zod"} console.log(data); {"// { nom: 'Fatou', email: '...', note: 17, ... }"} } return ( <form onSubmit={handleSubmit(onSubmit)}> {"// register() injecte name, onChange, onBlur, ref"} <input {...register('nom')} placeholder="Nom" /> {errors.nom && <p>{errors.nom.message}</p>} <input {...register('email')} placeholder="Email" /> {errors.email && <p>{errors.email.message}</p>} <button type="submit">Envoyer</button> </form> ); }
import { Controller } from 'react-hook-form'; import { TextField } from '@mui/material'; {"// Controller est un wrapper RHF pour les composants UI tiers"} <Controller name="nom" control={control} {"← vient de useForm()"} render={({ field, fieldState }) => ( <TextField {...field} {"← injecte value, onChange, onBlur, ref"} label="Nom complet" error={!!fieldState.error} helperText={fieldState.error?.message} fullWidth /> )} />
Les composants de formulaire MUI
MUI fournit des composants prêts à l'emploi pour chaque type de champ. Chacun accepte des props spécifiques pour afficher les erreurs et messages d'aide.
import { TextField } from '@mui/material'; {"// Champ texte simple"} <TextField label="Nom complet" {"← label flottant"} placeholder="Ex: Fatou Diallo" variant="outlined" {"← outlined | filled | standard"} fullWidth {"← prend toute la largeur"} error={!!errors.nom} {"← true = bordure rouge"} helperText={errors.nom?.message} {"← message sous le champ"} /> {"// Champ email"} <TextField label="Email" type="email" fullWidth /> {"// Champ nombre"} <TextField label="Note" type="number" inputProps={{ min: 0, max: 20 }} fullWidth /> {"// Textarea multilignes"} <TextField label="Commentaire" multiline rows={4} fullWidth />
import { FormControl, InputLabel, Select, MenuItem, FormHelperText } from '@mui/material'; <FormControl fullWidth error={!!errors.filiere}> <InputLabel>Filière</InputLabel> <Select label="Filière" defaultValue="" {...register('filiere')} > <MenuItem value=""><em>-- Choisir --</em></MenuItem> <MenuItem value="info">Informatique</MenuItem> <MenuItem value="reseaux">Réseaux</MenuItem> <MenuItem value="cyber">Cybersécurité</MenuItem> </Select> <FormHelperText>{errors.filiere?.message}</FormHelperText> </FormControl>
import { Checkbox, FormControlLabel, Switch } from '@mui/material'; import { Controller } from 'react-hook-form'; {"// Checkbox avec Controller"} <Controller name="boursier" control={control} render={({ field }) => ( <FormControlLabel label="Étudiant boursier" control={ <Checkbox checked={field.value} {"← value → checked"} onChange={field.onChange} /> } /> )} /> {"// Switch (même structure que Checkbox)"} <FormControlLabel label="Notifications activées" control={<Switch {...field} checked={field.value} />} />
Formulaire complet MUI + RHF + Zod
Voici le formulaire d'inscription étudiant complet. C'est le modèle de référence à suivre pour tous vos formulaires.
import { z } from 'zod'; export const schemaEtudiant = z.object({ nom: z.string().min(2, 'Minimum 2 caractères'), email: z.string().email('Email invalide'), filiere: z.enum(['info', 'reseaux', 'cyber'], { errorMap: () => ({ message: 'Filière requise' }) }), note: z.number().min(0).max(20), boursier: z.boolean().default(false), }); {"// Type TypeScript inféré automatiquement (bonus)"} {"// export type EtudiantForm = z.infer;"}
import { useForm, Controller } from 'react-hook-form'; import { zodResolver } from '@hookform/resolvers/zod'; import { Box, TextField, FormControl, InputLabel, Select, MenuItem, FormHelperText, FormControlLabel, Checkbox, Button, Alert, CircularProgress, Stack } from '@mui/material'; import { schemaEtudiant } from './schemas/etudiant.schema'; function FormulaireEtudiant({ onSuccess }) { const { register, control, handleSubmit, reset, formState: { errors, isSubmitting, isSubmitSuccessful } } = useForm({ resolver: zodResolver(schemaEtudiant), defaultValues: { nom: '', email: '', filiere: '', note: 0, boursier: false }, mode: 'onBlur', }); async function onSubmit(data) { await new Promise(res => setTimeout(res, 1500)); {"← simuler API"} console.log('Données validées :', data); onSuccess?.(data); reset(); } return ( <Box component="form" onSubmit={handleSubmit(onSubmit)} noValidate > <Stack spacing={3}> {"/* Champ Nom — register() suffit */"} <TextField label="Nom complet" fullWidth error={!!errors.nom} helperText={errors.nom?.message} {...register('nom')} /> {"/* Champ Email */"} <TextField label="Email" type="email" fullWidth error={!!errors.email} helperText={errors.email?.message} {...register('email')} /> {"/* Select Filière */"} <FormControl fullWidth error={!!errors.filiere}> <InputLabel>Filière</InputLabel> <Select label="Filière" defaultValue="" {...register('filiere')}> <MenuItem value="info">Informatique</MenuItem> <MenuItem value="reseaux">Réseaux</MenuItem> <MenuItem value="cyber">Cybersécurité</MenuItem> </Select> <FormHelperText>{errors.filiere?.message}</FormHelperText> </FormControl> {"/* Champ Note */"} <TextField label="Note /20" type="number" fullWidth inputProps={{ min: 0, max: 20 }} error={!!errors.note} helperText={errors.note?.message} {...register('note', { valueAsNumber: true })} /> {"/* Checkbox Boursier — Controller obligatoire */"} <Controller name="boursier" control={control} render={({ field }) => ( <FormControlLabel label="Étudiant boursier" control={<Checkbox checked={field.value} onChange={field.onChange} />} /> )} /> {"/* Message succès */"} {isSubmitSuccessful && ( <Alert severity="success"> Inscription enregistrée avec succès ! </Alert> )} {"/* Bouton avec état loading */"} <Button type="submit" variant="contained" size="large" disabled={isSubmitting} startIcon={isSubmitting && <CircularProgress size={18} />} > {isSubmitting ? 'Envoi...' : 'S\'inscrire'} </Button> </Stack> </Box> ); }
valueAsNumber: true dans register() fait la conversion automatiquement.Patterns avancés courants
Quelques patterns qu'on retrouve dans presque tous les projets professionnels.
const { watch, register } = useForm(...); {"// Observer la valeur d'un champ"} const filiere = watch('filiere'); return ( <div> {"/* Select filière */"} <Select {...register('filiere')}>...</Select> {"/* Champ qui apparaît seulement si filiere = 'cyber' */"} {filiere === 'cyber' && ( <TextField label="Certification sécurité (optionnel)" {...register('certification')} fullWidth /> )} </div> );
function FormulaireEdition({ etudiantId }) { const { reset, ...rest } = useForm({ resolver: zodResolver(schema) }); {"// Charger les données depuis l'API, puis pré-remplir"} useEffect(() => { async function charger() { const etudiant = await fetchEtudiant(etudiantId); {"// reset() remplit tous les champs d'un coup"} reset({ nom: etudiant.nom, email: etudiant.email, filiere: etudiant.filiere, note: etudiant.note, boursier: etudiant.boursier, }); } charger(); }, [etudiantId, reset]); return <form>...</form>; }
const { setError, handleSubmit } = useForm(...); async function onSubmit(data) { try { await inscrireEtudiant(data); } catch (err) { {"// L'API retourne : { field: 'email', message: 'Email déjà utilisé' }"} if (err.field) { setError(err.field, { type: 'server', message: err.message, }); } else { {"// Erreur globale (pas liée à un champ)"} setError('root', { message: 'Une erreur est survenue. Réessayez.' }); } } } {"// Dans le JSX — afficher l'erreur root"} {errors.root && <Alert severity="error">{errors.root.message}</Alert>}
| Composant | Utiliser | Pourquoi |
|---|---|---|
| input HTML natif | register() | Supporte ref natif |
| MUI TextField | register() | Supporte ref via inputRef |
| MUI Select | register() | Supporte ref natif |
| MUI Checkbox | Controller | Besoin de checked, pas value |
| MUI Switch | Controller | Besoin de checked, pas value |
| MUI DatePicker | Controller | Composant contrôlé sans ref |
| React Select | Controller | API différente (onChange reçoit l'objet option) |
Quiz & Travaux pratiques
4 questions pour valider votre compréhension, puis 3 exercices progressifs du plus simple au plus complet.
zodResolver dans useForm({ resolver: zodResolver(schema) }) ?Controller pour une Checkbox MUI et pas register() ?type="number" est bien reçu comme nombre par Zod (et non comme string) ?schemaConnexion avec email (email valide, requis) et motDePasse (string, minimum 6 caractères). Construisez le formulaire avec 2 TextField MUI (le second en type="password"), validé par React Hook Form. Affichez les erreurs sous chaque champ. Au submit, affichez un Alert MUI de succès avec l'email saisi. Désactivez le bouton pendant la soumission.
nom, email, motDePasse (min 8, au moins un chiffre via regex), confirmerMotDePasse. Utilisez .refine() pour vérifier que les deux mots de passe correspondent — l'erreur doit apparaître sur le champ confirmerMotDePasse. Ajoutez un Select MUI pour le rôle (étudiant / enseignant / admin) et une Checkbox "Accepter les conditions" (obligatoire — validée avec z.literal(true)). Affichez un résumé des données validées sous le formulaire après soumission.
useEffect (setTimeout 1s). Utilisez reset() pour pré-remplir le formulaire une fois les données chargées. Affichez un CircularProgress pendant le chargement. Ajoutez un champ certification (TextField) qui s'affiche uniquement si la filière choisie est "cyber" — utilisez watch('filiere'). Gérez une erreur serveur simulée : si le nom soumis contient "admin", utilisez setError('nom', ...) pour afficher "Ce nom n'est pas autorisé". Sinon, succès.