ShadCN UI Patterns – November 2025 Standards
Wann verwenden
- Neue UI-Komponenten erstellen
- Vorhandene Komponenten auf ShadCN umstellen
- Formulare mit Validierung implementieren
- Modals, Dialogs und Overlays erstellen
- Barrierefreiheit sicherstellen
Warum ShadCN UI?
- Copy-paste, nicht npm – Vollständige Kontrolle über den Komponenten-Code
- Radix UI Primitives – Barrierefreiheit bereits eingebaut (WCAG 2.1 AA-konform)
- TailwindCSS-first – Vollständig anpassbar, kein CSS-in-JS
- TypeScript-native – Typsichere Props und Varianten
- Server Component-kompatibel – Funktioniert mit Next.js 15 App Router
Kernprinzipien
1. Komponenten-Installationsmuster
# Einzelne Komponenten nach Bedarf installieren
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
Komponenten werden in das Verzeichnis src/components/ui/ kopiert – Sie besitzen den Code.
2. Komponenten-Nutzungsmuster
Button-Komponente
import { Button } from "@/components/ui/button"
// ✅ RICHTIG: Semantische Varianten verwenden
<Button variant="default">Speichern</Button>
<Button variant="destructive">Löschen</Button>
<Button variant="outline">Abbrechen</Button>
<Button variant="ghost">Überspringen</Button>
<Button variant="link">Mehr erfahren</Button>
// ✅ RICHTIG: Größen-Varianten verwenden
<Button size="default">Mittel</Button>
<Button size="sm">Klein</Button>
<Button size="lg">Groß</Button>
<Button size="icon"><Icon /></Button>
// ❌ FALSCH: Benutzerdefinierte Buttons ohne Button-Komponente erstellen
<button className="px-4 py-2 bg-blue-500">Schlecht</button>
Dialog/Modal-Komponente
import {
Dialog,
DialogContent,
DialogDescription,
DialogHeader,
DialogTitle,
DialogTrigger,
} from "@/components/ui/dialog"
// ✅ RICHTIG: Korrekte Dialog-Struktur verwenden (Barrierefreiheit)
<Dialog>
<DialogTrigger asChild>
<Button>Einstellungen öffnen</Button>
</DialogTrigger>
<DialogContent>
<DialogHeader>
<DialogTitle>Einstellungen</DialogTitle>
<DialogDescription>
Konfigurieren Sie hier Ihre Anwendungseinstellungen.
</DialogDescription>
</DialogHeader>
{/* Dialog-Inhalt */}
</DialogContent>
</Dialog>
// ❌ FALSCH: DialogHeader oder DialogTitle weglassen (unterbricht Screenreader)
<DialogContent>
<h2>Einstellungen</h2> {/* Falsch - DialogTitle verwenden */}
</DialogContent>
Form-Komponente (mit 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"
// ✅ RICHTIG: Zuerst Zod-Schema definieren (Validierung)
const formSchema = z.object({
email: z.string().email("Ungültige E-Mail-Adresse"),
password: z.string().min(8, "Passwort muss mindestens 8 Zeichen lang sein"),
})
function LoginForm() {
const form = useForm<z.infer<typeof formSchema>>({
resolver: zodResolver(formSchema),
defaultValues: {
email: "",
password: "",
},
})
async function onSubmit(values: z.infer<typeof formSchema>) {
// Typsichere validierte Daten
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>
Wir geben Ihre E-Mail niemals weiter.
</FormDescription>
<FormMessage />
</FormItem>
)}
/>
<FormField
control={form.control}
name="password"
render={({ field }) => (
<FormItem>
<FormLabel>Passwort</FormLabel>
<FormControl>
<Input type="password" {...field} />
</FormControl>
<FormMessage />
</FormItem>
)}
/>
<Button type="submit">Anmelden</Button>
</form>
</Form>
)
}
// ❌ FALSCH: Unkontrollierte Formulare ohne Validierung verwenden
<form>
<input name="email" /> {/* Keine Validierung */}
</form>
3. Server vs. Client-Komponenten
// ✅ RICHTIG: Server-Komponente für statische Dialoge verwenden
import { Dialog, DialogContent } from "@/components/ui/dialog"
export default function ServerDialog() {
// Kein 'use client' erforderlich
return <Dialog>...</Dialog>
}
// ✅ RICHTIG: Client-Komponente verwenden, wenn Zustand benötigt wird
'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. Barrierefreiheitsanforderungen
Fokusverwaltung
// ✅ RICHTIG: DialogTrigger mit asChild für korrekten Fokus verwenden
<DialogTrigger asChild>
<Button>Öffnen</Button>
</DialogTrigger>
// ❌ FALSCH: Manuell auslösen ohne korrekte Fokusbehandlung
<Button onClick={() => setOpen(true)}>Öffnen</Button>
Tastaturnavigation
// ✅ ShadCN kümmert sich automatisch darum:
// - ESC schließt Dialoge
// - Tab navigiert zwischen fokussierbaren Elementen
// - Enter/Leertaste aktiviert Buttons
// - Pfeiltasten navigieren durch Menüs
// ❌ FALSCH: Standard-Tastaturverhalten ohne guten Grund überschreiben
Screenreader-Unterstützung
// ✅ RICHTIG: Immer DialogTitle einfügen (für ARIA erforderlich)
<DialogHeader>
<DialogTitle>Projekt löschen</DialogTitle>
<DialogDescription>
Diese Aktion kann nicht rückgängig gemacht werden.
</DialogDescription>
</DialogHeader>
// ❌ FALSCH: Visuell versteckte Titel falsch verwenden
<DialogTitle className="sr-only">Löschen</DialogTitle>
// Nur verstecken, wenn es eine klare visuelle Alternative gibt
5. Häufig verwendete Komponenten
| Komponente | Anwendungsfall | Wichtige Props |
|---|---|---|
Button | Alle klickbaren Aktionen | variant, size, asChild |
Dialog | Modals, Bestätigungen | open, onOpenChange |
Sheet | Seitenpanels, Schubladen | side, open, onOpenChange |
Popover | Tooltips, Menüs | open, onOpenChange |
Form | Alle Formulare | form (von useForm) |
Input | Texteingabe | type, placeholder |
Select | Dropdowns | value, onValueChange |
Checkbox | Boolesche Eingabe | checked, onCheckedChange |
RadioGroup | Einzelauswahl | value, onValueChange |
Table | Datentabellen | table (von TanStack Table) |
Card | Inhaltscontainer | CardHeader, CardContent, CardFooter |
Toast | Benachrichtigungen | title, description, variant |
Command | Befehlspalette | onSelect |
Tabs | Tab-Navigation | value, onValueChange |
6. TailwindCSS Best Practices
// ✅ RICHTIG: Tailwind Utility-Klassen verwenden
<Button className="w-full mt-4">Absenden</Button>
// ✅ RICHTIG: cn()-Hilfsfunktion für bedingte Klassen
import { cn } from "@/lib/utils"
<Button className={cn(
"w-full",
isLoading && "opacity-50 cursor-not-allowed"
)}>
Absenden
</Button>
// ❌ FALSCH: Inline-Stile verwenden
<Button style={{ width: '100%', marginTop: '16px' }}>Absenden</Button>
// ❌ FALSCH: Benutzerdefinierte CSS-Dateien für Komponenten erstellen
/* styles.css */
.my-button { width: 100%; }
7. Dark Mode Unterstützung
// ✅ RICHTIG: Tailwind Dark Mode-Klassen verwenden
<div className="bg-white dark:bg-gray-900 text-black dark:text-white">
Inhalt
</div>
// ✅ ShadCN-Komponenten haben Dark Mode bereits eingebaut
<Button variant="default">
{/* Automatisch für Dark Mode gestylt */}
</Button>
Häufige Fehler
❌ Fehlender DialogTitle (Barrierefreiheitsverletzung)
// SCHLECHT
<DialogContent>
<h2>Einstellungen</h2>
<p>Inhalt</p>
</DialogContent>
// GUT
<DialogContent>
<DialogHeader>
<DialogTitle>Einstellungen</DialogTitle>
</DialogHeader>
<p>Inhalt</p>
</DialogContent>
❌ Keine Form-Komponente für Formulare verwenden
// SCHLECHT - Keine Validierung, schlechte UX
<form>
<input name="email" />
<button type="submit">Absenden</button>
</form>
// GUT - Validierung, Fehlermeldungen, Barrierefreiheit
<Form {...form}>
<form onSubmit={form.handleSubmit(onSubmit)}>
<FormField name="email" ... />
</form>
</Form>
❌ Farben hartkodieren statt Varianten zu verwenden
// SCHLECHT
<Button className="bg-red-500 hover:bg-red-600">Löschen</Button>
// GUT
<Button variant="destructive">Löschen</Button>
❌ asChild für Trigger nicht verwenden
// SCHLECHT - Erzeugt unnötig verschachtelte Buttons
<DialogTrigger>
<Button>Öffnen</Button>
</DialogTrigger>
// Rendert: <button><button>Öffnen</button></button> (ungültiges HTML)
// GUT - Fasst Props in einem Button zusammen
<DialogTrigger asChild>
<Button>Öffnen</Button>
</DialogTrigger>
// Rendert: <button>Öffnen</button>
ShadCN-Komponenten testen
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('sollte sich öffnen, wenn auf Trigger geklickt wird', async () => {
const user = userEvent.setup()
render(
<Dialog>
<DialogTrigger asChild>
<button>Öffnen</button>
</DialogTrigger>
<DialogContent>
<div>Dialog-Inhalt</div>
</DialogContent>
</Dialog>
)
// Dialog-Inhalt sollte anfangs nicht sichtbar sein
expect(screen.queryByText('Dialog-Inhalt')).not.toBeInTheDocument()
// Trigger klicken
await user.click(screen.getByText('Öffnen'))
// Dialog-Inhalt sollte jetzt sichtbar sein
expect(screen.getByText('Dialog-Inhalt')).toBeInTheDocument()
})
it('sollte mit ESC-Taste schließen', async () => {
const user = userEvent.setup()
render(
<Dialog defaultOpen>
<DialogContent>Dialog-Inhalt</DialogContent>
</Dialog>
)
expect(screen.getByText('Dialog-Inhalt')).toBeInTheDocument()
await user.keyboard('{Escape}')
expect(screen.queryByText('Dialog-Inhalt')).not.toBeInTheDocument()
})
})
Ressourcen
- Offizielle Dokumentation: https://ui.shadcn.com
- Radix UI: https://www.radix-ui.com
- Beispiele: https://ui.shadcn.com/examples
- Themes: https://ui.shadcn.com/themes
November 2025 Hinweis
ShadCN UI ist der Industriestandard für React-Komponentenbibliotheken ab November 2025. Alle neuen Quetrex-Anwendungen müssen ShadCN UI für Konsistenz, Barrierefreiheit und Wartbarkeit verwenden.