Motifs ShadCN UI - Normes novembre 2025
Quand l'utiliser
- Construire de nouveaux composants d'interface
- Refactoriser des composants existants pour utiliser ShadCN
- Implémenter des formulaires avec validation
- Créer des modales, boîtes de dialogue et superpositions
- Assurer la conformité en matière d'accessibilité
Pourquoi ShadCN UI ?
- Copier-coller, pas npm - Pleine propriété du code des composants
- Primitives Radix UI - Accessibilité intégrée (conforme WCAG 2.1 AA)
- TailwindCSS en premier - Personnalisation totale, pas de CSS-in-JS
- TypeScript natif - Props et variantes typées en toute sécurité
- Compatible avec les composants serveur - Fonctionne avec Next.js 15 App Router
Principes fondamentaux
1. Motif d'installation des composants
# Installer les composants individuellement selon les besoins
npx shadcn@latest add button
npx shadcn@latest add dialog
npx shadcn@latest add form
npx shadcn@latest add input
npx shadcn@latest add label
Les composants sont copiés dans le répertoire src/components/ui/ – vous possédez le code.
2. Motifs d'utilisation des composants
Composant Button
import { Button } from "@/components/ui/button"
// ✅ À FAIRE : Utiliser des variantes sémantiques
<Button variant="default">Enregistrer</Button>
<Button variant="destructive">Supprimer</Button>
<Button variant="outline">Annuler</Button>
<Button variant="ghost">Passer</Button>
<Button variant="link">En savoir plus</Button>
// ✅ À FAIRE : Utiliser des variantes de taille
<Button size="default">Moyen</Button>
<Button size="sm">Petit</Button>
<Button size="lg">Grand</Button>
<Button size="icon"><Icon /></Button>
// ❌ À NE PAS FAIRE : Créer des boutons personnalisés sans utiliser le composant Button
<button className="px-4 py-2 bg-blue-500">Mauvais</button>
Composant Dialog/Modal
import {
Dialog,
DialogContent,
DialogDescription,
DialogHeader,
DialogTitle,
DialogTrigger,
} from "@/components/ui/dialog"
// ✅ À FAIRE : Utiliser une structure de boîte de dialogue appropriée (accessibilité)
<Dialog>
<DialogTrigger asChild>
<Button>Ouvrir les paramètres</Button>
</DialogTrigger>
<DialogContent>
<DialogHeader>
<DialogTitle>Paramètres</DialogTitle>
<DialogDescription>
Configurez ici les paramètres de votre application.
</DialogDescription>
</DialogHeader>
{/* Contenu de la boîte de dialogue */}
</DialogContent>
</Dialog>
// ❌ À NE PAS FAIRE : Ignorer DialogHeader ou DialogTitle (interrompt les lecteurs d'écran)
<DialogContent>
<h2>Paramètres</h2> {/* Erreur - utiliser DialogTitle */}
</DialogContent>
Composant Form (avec React Hook Form + Zod)
import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import * as z from "zod"
import {
Form,
FormControl,
FormDescription,
FormField,
FormItem,
FormLabel,
FormMessage,
} from "@/components/ui/form"
import { Input } from "@/components/ui/input"
import { Button } from "@/components/ui/button"
// ✅ À FAIRE : Définir d'abord le schéma Zod (validation)
const formSchema = z.object({
email: z.string().email("Adresse e-mail invalide"),
password: z.string().min(8, "Le mot de passe doit comporter au moins 8 caractères"),
})
function LoginForm() {
const form = useForm<z.infer<typeof formSchema>>({
resolver: zodResolver(formSchema),
defaultValues: {
email: "",
password: "",
},
})
async function onSubmit(values: z.infer<typeof formSchema>) {
// Données validées typées en toute sécurité
console.log(values)
}
return (
<Form {...form}>
<form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
<FormField
control={form.control}
name="email"
render={({ field }) => (
<FormItem>
<FormLabel>E-mail</FormLabel>
<FormControl>
<Input placeholder="[email protected]" {...field} />
</FormControl>
<FormDescription>
Nous ne partagerons jamais votre e-mail.
</FormDescription>
<FormMessage />
</FormItem>
)}
/>
<FormField
control={form.control}
name="password"
render={({ field }) => (
<FormItem>
<FormLabel>Mot de passe</FormLabel>
<FormControl>
<Input type="password" {...field} />
</FormControl>
<FormMessage />
</FormItem>
)}
/>
<Button type="submit">Se connecter</Button>
</form>
</Form>
)
}
// ❌ À NE PAS FAIRE : Utiliser des formulaires non contrôlés sans validation
<form>
<input name="email" /> {/* Aucune validation */}
</form>
3. Composants serveur vs client
// ✅ À FAIRE : Utiliser un composant serveur pour les boîtes de dialogue statiques
import { Dialog, DialogContent } from "@/components/ui/dialog"
export default function ServerDialog() {
// Pas besoin de 'use client'
return <Dialog>...</Dialog>
}
// ✅ À FAIRE : Utiliser un composant client lorsqu'un état est nécessaire
'use client'
import { useState } from 'react'
import { Dialog, DialogContent } from "@/components/ui/dialog"
export function ClientDialog() {
const [open, setOpen] = useState(false)
return (
<Dialog open={open} onOpenChange={setOpen}>
<DialogContent>...</DialogContent>
</Dialog>
)
}
4. Exigences d'accessibilité
Gestion du focus
// ✅ À FAIRE : Utiliser DialogTrigger avec asChild pour un focus approprié
<DialogTrigger asChild>
<Button>Ouvrir</Button>
</DialogTrigger>
// ❌ À NE PAS FAIRE : Déclencher manuellement sans gestion appropriée du focus
<Button onClick={() => setOpen(true)}>Ouvrir</Button>
Navigation au clavier
// ✅ ShadCN gère cela automatiquement :
// - ESC ferme les boîtes de dialogue
// - Tab navigue entre les éléments focusables
// - Entrée/Espace active les boutons
// - Les touches fléchées naviguent dans les menus
// ❌ À NE PAS FAIRE : Surcharger le comportement clavier par défaut sans bonne raison
Support des lecteurs d'écran
// ✅ À FAIRE : Toujours inclure DialogTitle (obligatoire pour ARIA)
<DialogHeader>
<DialogTitle>Supprimer le projet</DialogTitle>
<DialogDescription>
Cette action est irréversible.
</DialogDescription>
</DialogHeader>
// ❌ À NE PAS FAIRE : Utiliser des titres masqués visuellement de manière incorrecte
<DialogTitle className="sr-only">Supprimer</DialogTitle>
// Ne masquer que s'il existe une alternative visuelle claire
5. Composants courants à utiliser
| Composant | Cas d'utilisation | Props clés |
|---|---|---|
Button | Toutes les actions cliquables | variant, size, asChild |
Dialog | Modales, confirmations | open, onOpenChange |
Sheet | Panneaux latéraux, tiroirs | side, open, onOpenChange |
Popover | Infobulles, menus | open, onOpenChange |
Form | Tous les formulaires | form (de useForm) |
Input | Saisie de texte | type, placeholder |
Select | Listes déroulantes | value, onValueChange |
Checkbox | Saisie booléenne | checked, onCheckedChange |
RadioGroup | Choix unique | value, onValueChange |
Table | Tableaux de données | table (de TanStack Table) |
Card | Conteneurs de contenu | CardHeader, CardContent, CardFooter |
Toast | Notifications | title, description, variant |
Command | Palette de commandes | onSelect |
Tabs | Navigation par onglets | value, onValueChange |
6. Bonnes pratiques TailwindCSS
// ✅ À FAIRE : Utiliser les classes utilitaires Tailwind
<Button className="w-full mt-4">Envoyer</Button>
// ✅ À FAIRE : Utiliser l'aide cn() pour les classes conditionnelles
import { cn } from "@/lib/utils"
<Button className={cn(
"w-full",
isLoading && "opacity-50 cursor-not-allowed"
)}>
Envoyer
</Button>
// ❌ À NE PAS FAIRE : Utiliser des styles en ligne
<Button style={{ width: '100%', marginTop: '16px' }}>Envoyer</Button>
// ❌ À NE PAS FAIRE : Créer des fichiers CSS personnalisés pour les composants
// styles.css
.my-button { width: 100%; }
7. Prise en charge du mode sombre
// ✅ À FAIRE : Utiliser les classes de mode sombre Tailwind
<div className="bg-white dark:bg-gray-900 text-black dark:text-white">
Contenu
</div>
// ✅ Les composants ShadCN intègrent le mode sombre
<Button variant="default">
{/* Automatiquement stylé pour le mode sombre */}
</Button>
Erreurs courantes à détecter
❌ DialogTitle manquant (violation d'accessibilité)
// MAUVAIS
<DialogContent>
<h2>Paramètres</h2>
<p>Contenu</p>
</DialogContent>
// BON
<DialogContent>
<DialogHeader>
<DialogTitle>Paramètres</DialogTitle>
</DialogHeader>
<p>Contenu</p>
</DialogContent>
❌ Ne pas utiliser le composant Form pour les formulaires
// MAUVAIS - Pas de validation, mauvaise UX
<form>
<input name="email" />
<button type="submit">Envoyer</button>
</form>
// BON - Validation, messages d'erreur, accessibilité
<Form {...form}>
<form onSubmit={form.handleSubmit(onSubmit)}>
<FormField name="email" ... />
</form>
</Form>
❌ Coder en dur les couleurs au lieu d'utiliser des variantes
// MAUVAIS
<Button className="bg-red-500 hover:bg-red-600">Supprimer</Button>
// BON
<Button variant="destructive">Supprimer</Button>
❌ Ne pas utiliser asChild pour les déclencheurs
// MAUVAIS - Crée des boutons imbriqués inutiles
<DialogTrigger>
<Button>Ouvrir</Button>
</DialogTrigger>
// Affiche : <button><button>Ouvrir</button></button> (HTML invalide)
// BON - Fusionne les props en un seul bouton
<DialogTrigger asChild>
<Button>Ouvrir</Button>
</DialogTrigger>
// Affiche : <button>Ouvrir</button>
Tester les composants ShadCN
import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { Dialog, DialogTrigger, DialogContent } from '@/components/ui/dialog'
describe('Dialog', () => {
it('devrait s'ouvrir lorsqu'on clique sur le déclencheur', async () => {
const user = userEvent.setup()
render(
<Dialog>
<DialogTrigger asChild>
<button>Ouvrir</button>
</DialogTrigger>
<DialogContent>
<div>Contenu de la boîte de dialogue</div>
</DialogContent>
</Dialog>
)
// Le contenu de la boîte de dialogue ne doit pas être visible initialement
expect(screen.queryByText('Contenu de la boîte de dialogue')).not.toBeInTheDocument()
// Cliquer sur le déclencheur
await user.click(screen.getByText('Ouvrir'))
// Le contenu de la boîte de dialogue doit maintenant être visible
expect(screen.getByText('Contenu de la boîte de dialogue')).toBeInTheDocument()
})
it('devrait se fermer avec la touche ESC', async () => {
const user = userEvent.setup()
render(
<Dialog defaultOpen>
<DialogContent>Contenu de la boîte de dialogue</DialogContent>
</Dialog>
)
expect(screen.getByText('Contenu de la boîte de dialogue')).toBeInTheDocument()
await user.keyboard('{Escape}')
expect(screen.queryByText('Contenu de la boîte de dialogue')).not.toBeInTheDocument()
})
})
Ressources
- Documentation officielle : https://ui.shadcn.com
- Radix UI : https://www.radix-ui.com
- Exemples : https://ui.shadcn.com/examples
- Thèmes : https://ui.shadcn.com/themes
Note de novembre 2025
ShadCN UI est la référence standard de l'industrie pour les bibliothèques de composants React en novembre 2025. Toutes les nouvelles applications Quetrex doivent utiliser ShadCN UI pour garantir cohérence, accessibilité et maintenabilité.