jezweb/shadcn-ui

Que fait shadcn-ui ?

Installe et configure les composants shadcn/ui pour les projets React. Guide la sélection des composants, l'ordre d'installation, la gestion des dépendances, la personnalisation avec des tokens sémantiques et les recettes UI courantes (formulaires, tableaux de données, navigation, modales). À utiliser après que tailwind-theme-builder ait mis en place l'infrastructure thématique, lors de l'ajout de composants, de la création de formulaires, de tableaux de données ou de la mise en place de la navigation.

Prérequis

• Projet React avec Tailwind CSS configuré
• tailwind-theme-builder exécuté pour configurer le thème de base
• Configuration components.json dans le projet

Processus d'installation

1. Initialiser shadcn/ui (si ce n'est pas déjà fait)

npx shadcn@latest init

Cela crée le fichier components.json et ajoute les dépendances nécessaires.

2. Ajouter des composants

Utilisez la commande add pour installer les composants individuellement :

npx shadcn@latest add button
npx shadcn@latest add card
npx shadcn@latest add form

Ordre d'installation recommandé :

1. Composants de base : button, card, input, label
2. Composants de formulaire : form, select, checkbox, radio-group
3. Composants de retour visuel : toast, dialog, sheet
4. Composants de navigation : tabs, dropdown-menu, navigation-menu
5. Composants avancés : data-table, calendar, command

3. Gestion des dépendances

Chaque composant shadcn/ui peut avoir des dépendances spécifiques (par exemple, lucide-react pour les icônes, react-hook-form pour les formulaires). Assurez-vous qu'elles sont installées :

npm install lucide-react react-hook-form @hookform/resolvers zod

Personnalisation avec des tokens sémantiques

Utilisez des variables CSS (tokens sémantiques) pour personnaliser les couleurs, les espacements et les typographies. Exemple :

:root {
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 98%;
  --secondary: 210 40% 96.1%;
  --secondary-foreground: 222.2 47.4% 11.2%;
  --radius: 0.5rem;
}

Ces variables sont définies dans globals.css et peuvent être remplacées pour créer des thèmes personnalisés.

Recettes UI courantes

Formulaires

Utilisez react-hook-form avec zod pour la validation :

import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import * as z from "zod"
import { Button } from "@/components/ui/button"
import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from "@/components/ui/form"
import { Input } from "@/components/ui/input"

const formSchema = z.object({
  email: z.string().email(),
})

export function ProfileForm() {
  const form = useForm<z.infer<typeof formSchema>>({
    resolver: zodResolver(formSchema),
  })

  function onSubmit(values: z.infer<typeof formSchema>) {
    console.log(values)
  }

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)}>
        <FormField
          control={form.control}
          name="email"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Email</FormLabel>
              <FormControl>
                <Input placeholder="[email protected]" {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />
        <Button type="submit">Envoyer</Button>
      </form>
    </Form>
  )
}

Tableaux de données

Utilisez @tanstack/react-table avec le composant DataTable :

"use client"

import { DataTable } from "@/components/ui/data-table"
import { columns } from "./columns"

export function UsersTable({ data }: { data: User[] }) {
  return <DataTable columns={columns} data={data} />
}

Navigation

Utilisez Tabs ou NavigationMenu pour une navigation structurée :

import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"

export function SettingsTabs() {
  return (
    <Tabs defaultValue="account">
      <TabsList>
        <TabsTrigger value="account">Compte</TabsTrigger>
        <TabsTrigger value="password">Mot de passe</TabsTrigger>
      </TabsList>
      <TabsContent value="account">Contenu du compte</TabsContent>
      <TabsContent value="password">Contenu du mot de passe</TabsContent>
    </Tabs>
  )
}

Modales

Utilisez Dialog ou Sheet pour des fenêtres modales :

import { Button } from "@/components/ui/button"
import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog"

export function ConfirmModal() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="outline">Ouvrir la modale</Button>
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Confirmer l'action</DialogTitle>
          <DialogDescription>Cette action est irréversible. Voulez-vous continuer ?</DialogDescription>
        </DialogHeader>
        <DialogFooter>
          <Button variant="outline">Annuler</Button>
          <Button>Confirmer</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}

Bonnes pratiques

• Utilisez toujours npx shadcn@latest add plutôt que de copier manuellement les fichiers des composants.
• Centralisez les imports via @/components/ui/*.
• Pour les classes conditionnelles, utilisez la fonction utilitaire cn() (incluse par défaut).
• Personnalisez les composants en étendant les tokens CSS plutôt qu'en modifiant les fichiers source de shadcn/ui.
• Testez l'accessibilité après avoir ajouté des composants (par exemple, navigation au clavier, attributs ARIA).

Dépannage

• Problème : Erreur "Module not found" pour @/components/ui/button.

  • Solution : Vérifiez que le composant est installé via npx shadcn@latest add button et que le fichier tsconfig.json ou jsconfig.json comporte un alias @/ pointant vers ./src/.

• Problème : Les classes Tailwind ne s'appliquent pas.

  • Solution : Assurez-vous que tailwind.config.js inclut les fichiers de composants shadcn/ui dans la propriété content.

• Problème : Conflits de version avec React.

  • Solution : Mettez à jour React et React DOM vers la version 18 ou ultérieure.