Blog

Shadcn/UI : Tutoriel pour débutants et guide de démarrage

Audrey Lopez

Audrey Lopez

14 June 2025

Shadcn/UI : Tutoriel pour débutants et guide de démarrage

Pour les développeurs web, la quête de la boîte à outils d'interface utilisateur parfaite est un effort constant. Pendant des années, les développeurs React se sont appuyés sur des bibliothèques de composants traditionnelles comme Material-UI (MUI), Ant Design et Chakra UI. Ces bibliothèques offrent une multitude de composants pré-construits, promettant d'accélérer le développement. Cependant, elles s'accompagnent souvent d'un compromis : un manque de contrôle, des surcharges de style qui ressemblent à un combat, et des tailles de bundle gonflées.

Voici Shadcn UI, une approche révolutionnaire qui a pris d'assaut la communauté React. Ce n'est pas une bibliothèque de composants comme vous en avez l'habitude ; c'est quelque chose de mieux. C'est une collection de composants magnifiquement conçus, accessibles et infiniment réutilisables que vous n'installez pas depuis npm en tant que dépendance – vous les copiez directement dans votre projet.

Ce tutoriel complet de 4000 mots vous servira de guide définitif, vous faisant passer du statut de débutant complet à celui de praticien confiant de Shadcn UI. Nous explorerons sa philosophie fondamentale, parcourrons une configuration détaillée, construirons des interfaces utilisateur complexes, maîtriserons les thèmes avancés et la gestion des formulaires, et discuterons des meilleures pratiques pour les applications à grande échelle. Préparez-vous à repenser ce que vous attendez d'une boîte à outils d'interface utilisateur.

💡
Vous voulez un excellent outil de test d'API qui génère une belle documentation d'API ?

Vous voulez une plateforme intégrée tout-en-un pour que votre équipe de développeurs travaille ensemble avec une productivité maximale ?

Apidog répond à toutes vos demandes et remplace Postman à un prix beaucoup plus abordable !
button

La Philosophie de Shadcn UI - Une Nouvelle Façon de Construire

Avant d'écrire une seule ligne de code, il est primordial de comprendre pourquoi Shadcn UI existe et quels problèmes il résout. Saisir cette philosophie fondamentale est la clé pour libérer tout son potentiel.

Ce que Shadcn UI N'est Pas

Ce que Shadcn UI Est

L'avantage principal de ce modèle est la fusion de la vitesse et du contrôle. Vous bénéficiez de la vélocité initiale de l'utilisation de composants pré-construits sans sacrifier la flexibilité et la maintenabilité à long terme qui découlent de la possession de votre propre code.

Préparer le Terrain - Configuration et Installation du Projet

Passons de la théorie à la pratique. Nous allons configurer un nouveau projet à partir de zéro. Pour ce guide, nous utiliserons principalement Next.js, car ses composants serveur et son routage basé sur les fichiers s'alignent parfaitement avec l'éthos de Shadcn UI. Nous couvrirons également brièvement la configuration pour Vite.

Étape 1 : Prérequis de l'Environnement

Assurez-vous que votre environnement de développement est prêt. Vous aurez besoin de :

Étape 2 : Créer une Nouvelle Application Next.js

Ouvrez votre terminal et exécutez la commande suivante pour initialiser un nouveau projet Next.js.

npx create-next-app@latest my-pro-shadcn-app --typescript --tailwind --eslint\n

Cette commande crée une nouvelle application dans un répertoire nommé my-pro-shadcn-app. Nous avons inclus quelques drapeaux importants :

L'installateur vous posera quelques questions. Voici les choix recommandés pour une configuration moderne de Next.js 14+ :

✔ Would you like to use `src/` directory? … No / **Yes**\n✔ Would you like to use App Router? (recommended) … No / **Yes**\n✔ Would you like to customize the default import alias? … **No** / Yes\n

L'utilisation de l'App Router est une pratique courante, et le répertoire src/ aide à organiser le code. Une fois terminé, naviguez dans votre nouveau projet :

cd my-pro-shadcn-app\n

Étape 3 : La Commande init - Donner Vie à Shadcn UI

C'est l'étape la plus importante. Shadcn UI fournit un outil CLI pour configurer votre projet. Exécutez la commande suivante depuis le répertoire racine de votre projet :

npx shadcn-ui@latest init\n

Cela déclenchera un questionnaire interactif pour configurer votre projet. Analysons chaque question et sa signification :

Après avoir confirmé, le CLI opère sa magie :

  1. Installe les Dépendances : Il ajoute les packages nécessaires comme tailwindcss-animate et class-variance-authority.
  2. Crée components.json : Stocke vos choix de configuration.
  3. Met à Jour tailwind.config.ts : Injecte le plugin Shadcn UI et la configuration des thèmes.
  4. Met à Jour globals.css : Ajoute un grand bloc de variables CSS qui définissent toute votre palette de couleurs, les rayons de bordure, et plus encore.
  5. Crée lib/utils.ts : Ce fichier exporte une fonction utilitaire cn, qui est un utilitaire astucieux pour fusionner conditionnellement les classes Tailwind CSS.

Votre projet est maintenant entièrement configuré.

(Alternative : Configuration avec Vite)

Si vous utilisez Vite avec React, le processus est très similaire. Après avoir configuré un projet Vite + React + TS, vous installeriez manuellement Tailwind CSS, puis exécuteriez npx shadcn-ui@latest init. Le CLI est assez intelligent pour détecter une configuration Vite et posera des questions légèrement différentes sur les emplacements des fichiers (par exemple, index.css au lieu de globals.css).

Construire une Interface Utilisateur - Des Composants Simples aux Layouts Complexes

La configuration étant terminée, commençons à construire. Le flux de travail principal est le suivant : identifier un besoin, ajouter le composant, l'utiliser.

Étape 4 : Ajouter et Utiliser Vos Premiers Composants

Nettoyons le code passe-partout par défaut de Next.js et construisons une interface simple.

1. Ajouter un Bouton :

npx shadcn-ui@latest add button\n

Observez ce qui se passe : un nouveau fichier, src/components/ui/button.tsx, est créé. C'est votre bouton. Il vous appartient.

2. Ajouter une Carte (Card) :

npx shadcn-ui@latest add card\n

Cette commande est plus intéressante. Elle crée src/components/ui/card.tsx. Si vous inspectez ce fichier, vous verrez qu'il exporte plusieurs composants : Card, CardHeader, CardTitle, CardDescription, CardContent, et CardFooter. C'est un modèle courant pour les composants composés.

3. Construire l'Interface Utilisateur :

Maintenant, ouvrez src/app/page.tsx et remplacez son contenu par ce qui suit :

import { Button } from "@/components/ui/button";\nimport {\n  Card,\n  CardContent,\n  CardDescription,\n  CardFooter,\n  CardHeader,\n  CardTitle,\n} from "@/components/ui/card";\nimport { Input } from "@/components/ui/input"; // Nous ajouterons ceci ensuite\nimport { Label } from "@/components/ui/label";   // Et ceci\n\nexport default function Home() {\n  return (\n    <main className="flex min-h-screen items-center justify-center bg-background p-8">\n      <Card className="w-full max-w-md">\n        <CardHeader>\n          <CardTitle className="text-2xl">Create Project</CardTitle>\n          <CardDescription>\n            Deploy your new project in one-click.\n          </CardDescription>\n        </CardHeader>\n        <CardContent className="grid gap-4">\n          <div className="grid gap-2">\n            <Label htmlFor="name">Name</Label>\n            <Input id="name" placeholder="Name of your project" />\n          </div>\n          <div className="grid gap-2">\n            <Label htmlFor="framework">Framework</Label>\n            {/* Nous remplacerons ceci par un composant Select plus tard */}\n            <Input id="framework" placeholder="e.g. Next.js" />\n          </div>\n        </CardContent>\n        <CardFooter>\n          <Button className="w-full">Deploy</Button>\n        </CardFooter>\n      </Card>\n    </main>\n  );\n}\n

Notre code ne fonctionnera pas encore car il nous manque les composants Input et Label. Ajoutons-les :

npx shadcn-ui@latest add input\nnpx shadcn-ui@latest add label\n

Maintenant, lancez votre serveur de développement :

npm run dev\n

Naviguez vers http://localhost:3000. Vous verrez un formulaire propre et professionnel dans une carte. Remarquez comment nous avons utilisé des classes utilitaires comme w-full, max-w-md, et grid directement dans notre JSX pour contrôler le layout. C'est la puissance de la combinaison de Shadcn et Tailwind CSS.

Étape 5 : Introduire des Composants Plus Sophistiqués

Les champs de saisie statiques sont bien, mais les applications réelles nécessitent des éléments interactifs. Améliorons notre formulaire.

1. Ajouter un Composant Select : Le champ "Framework" devrait être une liste déroulante. Ajoutons le composant Select. Celui-ci est plus complexe et a des dépendances sur d'autres composants.

npx shadcn-ui@latest add select\n

Le CLI est intelligent. Il verra que Select nécessite un composant Popover pour fonctionner et vous demandera la permission de l'installer ainsi que ses dépendances. C'est une fonctionnalité fantastique qui vous évite d'avoir à suivre manuellement les dépendances.

2. Intégrer le Composant Select : Remplacez le Input pour "Framework" dans src/app/page.tsx par le nouveau composant Select.

// Ajoutez ces imports en haut\nimport {\n  Select,\n  SelectContent,\n  SelectItem,\n  SelectTrigger,\n  SelectValue,\n} from "@/components/ui/select";\n\n// ... à l'intérieur du CardContent\n<div className="grid gap-2">\n  <Label htmlFor="framework">Framework</Label>\n  <Select>\n    <SelectTrigger id="framework">\n      <SelectValue placeholder="Select a framework" />\n    </SelectTrigger>\n    <SelectContent>\n      <SelectItem value="nextjs">Next.js</SelectItem>\n      <SelectItem value="sveltekit">SvelteKit</SelectItem>\n      <SelectItem value="astro">Astro</SelectItem>\n      <SelectItem value="nuxt">Nuxt.js</SelectItem>\n    </SelectContent>\n  </Select>\n</div>\n

Rafraîchissez votre navigateur. Vous avez maintenant une liste déroulante de sélection entièrement fonctionnelle et accessible, complète avec des animations et une navigation au clavier appropriée, tout cela grâce à Radix UI qui travaille en coulisses.

3. Ajouter un Feedback Utilisateur avec Toast : Que se passe-t-il lorsqu'un utilisateur clique sur "Deploy" ? Nous devrions lui donner un feedback. Le composant Toast est parfait pour cela.

D'abord, ajoutez-le :

npx shadcn-ui@latest add toast\n

Ensuite, pour utiliser les toasts, vous devez ajouter un composant <Toaster /> à votre layout racine afin qu'il puisse être affiché n'importe où dans l'application. Ouvrez src/app/layout.tsx et modifiez-le :

import { Toaster } from "@/components/ui/toaster" // Importer le Toaster\n\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\n  return (\n    <html lang="en">\n      <body>\n        {children}\n        <Toaster /> {/* L'ajouter ici, juste avant de fermer le body */}\n      </body>\n    </html>\n  )\n}\n

Maintenant, nous avons besoin d'un moyen de déclencher le toast. Nous utiliserons le hook useToast. Mettons à jour src/app/page.tsx pour en faire un composant client et gérer le clic sur le bouton.

'use client'; // <-- Ajouter ceci tout en haut du fichier\n\n// ... autres imports\nimport { useToast } from "@/components/ui/use-toast";\n\nexport default function Home() {\n  const { toast } = useToast(); // Obtenir la fonction toast depuis le hook\n\n  function handleDeploy() {\n    toast({\n      title: "Deployment Scheduled!",\n      description: "Your project 'Name of your project' is being deployed.",\n      duration: 5000,\n    });\n  }\n\n  return (\n    <main className="flex min-h-screen items-center justify-center bg-background p-8">\n      <Card className="w-full max-w-md">\n        {/* ... CardHeader et CardContent ... */}\n        <CardFooter>\n          <Button className="w-full" onClick={handleDeploy}> {/* Ajouter le gestionnaire onClick */}\n            Deploy\n          </Button>\n        </CardFooter>\n      </Card>\n    </main>\n  );\n}\n

Maintenant, lorsque vous cliquez sur le bouton "Deploy", une notification élégante apparaîtra dans le coin de votre écran.

Construire un Formulaire Professionnel avec Validation

La plupart des applications réelles nécessitent une gestion robuste des formulaires, y compris la validation côté client. La manière officielle de gérer cela avec Shadcn UI est de le combiner avec react-hook-form pour la gestion de l'état et zod pour la validation du schéma. Construisons-le.

Étape 6 : Installer les Dépendances de Formulaire

Tout d'abord, installons les bibliothèques nécessaires :

npm install react-hook-form zod @hookform/resolvers\n

Étape 7 : Ajouter le Composant Form de Shadcn

Shadcn UI fournit un composant spécial Form qui agit comme un wrapper pour connecter de manière transparente react-hook-form avec vos composants d'interface utilisateur.

npx shadcn-ui@latest add form\n

Cela ajoutera src/components/ui/form.tsx. Ce fichier fournit un ensemble de composants sensibles au contexte (Form, FormField, FormItem, FormLabel, FormControl, FormDescription, FormMessage) qui réduisent considérablement le code passe-partout.

Étape 8 : Créer le Schéma de Validation

Dans votre fichier src/app/page.tsx, définissons la structure et les règles de nos données de formulaire en utilisant zod.

// Ajouter ces imports en haut\nimport { z } from "zod";\nimport { zodResolver } from "@hookform/resolvers/zod";\nimport { useForm } from "react-hook-form";\nimport {\n  Form,\n  FormControl,\n  FormDescription,\n  FormField,\n  FormItem,\n  FormLabel,\n  FormMessage,\n} from "@/components/ui/form";\n

Maintenant, créons le schéma juste au-dessus de notre composant Home :

const formSchema = z.object({\n  projectName: z.string().min(2, {\n    message: "Le nom du projet doit contenir au moins 2 caractères.",\n  }).max(50, {\n    message: "Le nom du projet ne doit pas dépasser 50 caractères.",\n  }),\n  framework: z.string({\n    required_error: "Veuillez sélectionner un framework à afficher.",\n  }),\n});\n

Ce schéma définit deux champs : projectName doit être une chaîne de caractères entre 2 et 50 caractères, et framework est une chaîne de caractères requise.

Étape 9 : Connecter le Formulaire

Maintenant, refactorisons notre composant Home pour utiliser tous ces nouveaux outils.

export default function Home() {\n  const { toast } = useToast();\n\n  // 1. Définir votre formulaire.\n  const form = useForm<z.infer<

Pratiquez le Design-first d'API dans Apidog

Découvrez une manière plus simple de créer et utiliser des API

S'inscrire gratuitementTélécharger