# shadcn/ui

Ein Framework zum Erstellen von UI, Komponenten und Designsystemen. Komponenten werden als Quellcode über die CLI zum Projekt des Benutzers hinzugefügt.

> **WICHTIG:** Alle CLI-Befehle mit dem Paket-Manager des Projekts ausführen: `npx shadcn@latest`, `pnpm dlx shadcn@latest` oder `bunx --bun shadcn@latest` – basierend auf dem `packageManager` des Projekts. Die Beispiele unten verwenden `npx shadcn@latest`, aber ersetzen Sie den Befehl durch den korrekten für das Projekt.

## Aktueller Projektkontext

```json
!`npx shadcn@latest info --json`

Das obige JSON enthält die Projektkonfiguration und die installierten Komponenten. Verwenden Sie npx shadcn@latest docs <component>, um Dokumentations- und Beispiel-URLs für jede Komponente zu erhalten.

Grundsätze

Vorhandene Komponenten zuerst verwenden. Verwenden Sie npx shadcn@latest search, um Registries zu durchsuchen, bevor Sie benutzerdefiniertes UI schreiben. Durchsuchen Sie auch Community-Registries.
Komponieren, nicht neu erfinden. Einstellungsseite = Tabs + Card + Formularsteuerelemente. Dashboard = Sidebar + Card + Chart + Table.
Eingebaute Varianten vor benutzerdefinierten Stilen verwenden. variant="outline", size="sm", usw.
Semantische Farben verwenden. bg-primary, text-muted-foreground – niemals Rohwerte wie bg-blue-500.

Kritische Regeln

Diese Regeln werden immer durchgesetzt. Jede verlinkt auf eine Datei mit falschen/richtigen Code-Paaren.

Styling & Tailwind → styling.md

className für Layout, nicht für Styling. Überschreiben Sie niemals Komponentenfarben oder Typografie.
Kein space-x-* oder space-y-*. Verwenden Sie flex mit gap-*. Für vertikale Stapel: flex flex-col gap-*.
size-* verwenden, wenn Breite und Höhe gleich sind. size-10 nicht w-10 h-10.
truncate-Kurzform verwenden. Nicht overflow-hidden text-ellipsis whitespace-nowrap.
Keine manuellen dark:-Farbüberschreibungen. Semantische Tokens verwenden (bg-background, text-muted-foreground).
cn() für bedingte Klassen verwenden. Keine manuellen Template-Literal-Ternär-Schreibweisen.
Kein manuelles z-index auf Overlay-Komponenten. Dialog, Sheet, Popover usw. kümmern sich selbst um Ihr Stacking.

Formulare & Eingaben → forms.md

Formulare verwenden FieldGroup + Field. Niemals rohes div mit space-y-* oder grid gap-* für das Formular-Layout.
InputGroup verwendet InputGroupInput/InputGroupTextarea. Niemals rohes Input/Textarea innerhalb von InputGroup.
Buttons innerhalb von Eingaben verwenden InputGroup + InputGroupAddon.
Optionssets (2–7 Auswahlmöglichkeiten) verwenden ToggleGroup. Keine Button-Schleife mit manuellem aktivem Zustand.
FieldSet + FieldLegend zum Gruppieren verwandter Checkboxen/Radios. Kein div mit einer Überschrift.
Feldvalidierung verwendet data-invalid + aria-invalid. data-invalid auf Field, aria-invalid auf dem Steuerelement. Für deaktiviert: data-disabled auf Field, disabled auf dem Steuerelement.

Komponentenstruktur → composition.md

Items immer innerhalb ihrer Gruppe. SelectItem → SelectGroup. DropdownMenuItem → DropdownMenuGroup. CommandItem → CommandGroup.
asChild (radix) oder render (base) für benutzerdefinierte Auslöser verwenden. Prüfen Sie das Feld base von npx shadcn@latest info. → base-vs-radix.md
Dialog, Sheet und Drawer benötigen immer einen Titel. DialogTitle, SheetTitle, DrawerTitle für Barrierefreiheit erforderlich. Verwenden Sie className="sr-only", wenn visuell versteckt.
Vollständige Card-Komposition verwenden. CardHeader/CardTitle/CardDescription/CardContent/CardFooter. Nicht alles in CardContent packen.
Button hat kein isPending/isLoading. Mit Spinner + data-icon + disabled komponieren.
TabsTrigger muss innerhalb von TabsList sein. Auslöser niemals direkt in Tabs rendern.
Avatar benötigt immer AvatarFallback. Für den Fall, dass das Bild nicht geladen werden kann.

Komponenten verwenden, kein benutzerdefiniertes Markup → composition.md

Vorhandene Komponenten vor benutzerdefiniertem Markup verwenden. Prüfen, ob eine Komponente existiert, bevor ein gestyltes div geschrieben wird.
Hinweise verwenden Alert. Keine benutzerdefinierten gestylten Divs bauen.
Leere Zustände verwenden Empty. Kein benutzerdefiniertes Markup für leere Zustände bauen.
Toast folgt der Projektbasis. toast aus der toast-Komponente für Base-UI-Projekte verwenden. toast() von sonner für Radix- und React-Aria-Projekte verwenden.
Separator verwenden anstelle von <hr> oder <div className="border-t">.
Skeleton für Ladeplatzhalter verwenden. Keine benutzerdefinierten animate-pulse-Divs.
Badge anstelle von benutzerdefinierten gestylten Spans verwenden.

Icons → icons.md

Icons in Button verwenden data-icon. data-icon="inline-start" oder data-icon="inline-end" auf dem Icon.
Keine Größenklassen auf Icons innerhalb von Komponenten. Komponenten kümmern sich über CSS um die Icon-Größe. Kein size-4 oder w-4 h-4.
Icons als Objekte übergeben, nicht als String-Schlüssel. icon={CheckIcon}, nicht als String-Nachschlage.

Chat & Messaging → chat.md

Chat-UI komponiert die Chat-Primitive. Konversationen verwenden MessageScroller, Zeilen verwenden Message, Oberflächen verwenden Bubble. Niemals handgemachte Bubble-Divs oder einen rohen Scroll-Container.
MessageScroller besitzt das Scroll-Verhalten. Streaming-Follow, Verankerung und Sprung-zu-neuestem (MessageScrollerButton) sind eingebaut. Schreiben Sie keinen useStickToBottom/ResizeObserver-Hook.
Anhänge verwenden Attachment; Systemnotizen und Trennlinien verwenden Marker. Nicht Item-Karten oder Separator + eine Beschriftung.

CLI

Preset-Codes niemals manuell dekodieren oder Preset-URLs manuell erstellen. Verwenden Sie npx shadcn@latest preset decode <code>, preset url <code> oder preset open <code>. Für proaktive Preset-Erkennung verwenden Sie npx shadcn@latest preset resolve.
Preset-Codes direkt mit der CLI anwenden. Verwenden Sie npx shadcn@latest apply <code> für bestehende Projekte oder npx shadcn@latest init --preset <code> beim Initialisieren.

Schlüsselmuster

Dies sind die häufigsten Muster, die korrekten shadcn/ui-Code auszeichnen. Für Randfälle siehe die verlinkten Regeldateien oben.

// Formular-Layout: FieldGroup + Field, nicht div + Label.
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">E-Mail</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

// Validierung: data-invalid auf Field, aria-invalid auf dem Steuerelement.
<Field data-invalid>
  <FieldLabel>E-Mail</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>Ungültige E-Mail.</FieldDescription>
</Field>

// Icons in Buttons: data-icon, keine Größenklassen.
<Button>
  <SearchIcon data-icon="inline-start" />
  Suchen
</Button>

// Abstand: gap-*, nicht space-y-*.
<div className="flex flex-col gap-4">  // richtig
<div className="space-y-4">           // falsch

// Gleiche Abmessungen: size-*, nicht w-* h-*.
<Avatar className="size-10">   // richtig
<Avatar className="w-10 h-10"> // falsch

// Statusfarben: Badge-Varianten oder semantische Tokens, nicht Rohfarben.
<Badge variant="secondary">+20,1%</Badge>    // richtig
<span className="text-emerald-600">+20,1%</span> // falsch

Komponentenauswahl

Bedarf	Verwenden
Button/Aktion	`Button` mit passender Variante
Formulareingaben	`Input`, `Select`, `Combobox`, `Switch`, `Checkbox`, `RadioGroup`, `Textarea`, `InputOTP`, `Slider`
Umschalten zwischen 2–5 Optionen	`ToggleGroup` + `ToggleGroupItem`
Datenanzeige	`Table`, `Card`, `Badge`, `Avatar`
Navigation	`Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination`
Overlays	`Dialog` (Modal), `Sheet` (Seitenpanel), `Drawer` (unteres Blatt), `AlertDialog` (Bestätigung)
Feedback	`toast` (Base UI), `sonner` (Radix/Aria), `Alert`, `Progress`, `Skeleton`, `Spinner`
Befehlspalette	`Command` innerhalb von `Dialog`
Diagramme	`Chart` (umhüllt Recharts)
Layout	`Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible`
Leere Zustände	`Empty`
Menüs	`DropdownMenu`, `ContextMenu`, `Menubar`
Tooltips/Info	`Tooltip`, `HoverCard`, `Popover`
Chat-/Konversations-UI	`MessageScroller`, `Message`, `Bubble`, `Attachment`, `Marker`

Schlüsselfelder

Der eingefügte Projektkontext enthält diese Schlüsselfelder:

aliases → das tatsächliche Alias-Präfix für Importe verwenden (z.B. @/, ~/), niemals fest codieren.
isRSC → wenn true, benötigen Komponenten, die useState, useEffect, Event-Handler oder Browser-APIs verwenden, "use client" am Anfang der Datei. Dieses Feld immer referenzieren, wenn Sie die Direktive empfehlen.
tailwindVersion → "v4" verwendet @theme inline-Blöcke; "v3" verwendet tailwind.config.js.
tailwindCssFile → die globale CSS-Datei, in der benutzerdefinierte CSS-Variablen definiert sind. Diese Datei immer bearbeiten, niemals eine neue erstellen.
style → visuelle Behandlung der Komponente (z.B. nova, vega).
base → primitive Bibliothek (radix oder base). Beeinflusst Komponenten-APIs und verfügbare Props.
iconLibrary → bestimmt Icon-Importe. lucide-react für lucide, @tabler/icons-react für tabler usw. verwenden. Niemals lucide-react annehmen.
resolvedPaths → genaue Dateisystem-Ziele für Komponenten, Utils, Hooks usw.
framework → Routing- und Dateikonventionen (z.B. Next.js App Router vs. Vite SPA).
packageManager → für alle Nicht-shadcn-Abhängigkeitsinstallationen verwenden (z.B. pnpm add date-fns vs. npm install date-fns).
preset → aufgelöster Preset-Code und Werte für das aktuelle Projekt. Verwenden Sie npx shadcn@latest preset resolve --json, wenn Sie nur Preset-Informationen benötigen.

Siehe cli.md — info-Befehl für die vollständige Feldreferenz.

Komponentendokumentation, Beispiele und Verwendung

Führen Sie npx shadcn@latest docs <component> aus, um die URLs für die Dokumentation, Beispiele und API-Referenz einer Komponente zu erhalten. Rufen Sie diese URLs ab, um den tatsächlichen Inhalt zu erhalten.

npx shadcn@latest docs button dialog select

Führen Sie beim Erstellen, Reparieren, Debuggen oder Verwenden einer Komponente immer zuerst npx shadcn@latest docs aus und rufen Sie die URLs ab. Dadurch wird sichergestellt, dass Sie mit der korrekten API und den korrekten Verwendungsmustern arbeiten, anstatt zu raten.

Arbeitsablauf

Projektkontext abrufen — bereits oben eingefügt. Führen Sie npx shadcn@latest info erneut aus, wenn Sie ihn aktualisieren müssen.
Zuerst installierte Komponenten prüfen — vor dem Ausführen von add immer die Liste der components aus dem Projektkontext prüfen oder das Verzeichnis resolvedPaths.ui auflisten. Importieren Sie keine Komponenten, die nicht hinzugefügt wurden, und fügen Sie keine Komponenten, die bereits installiert sind, erneut hinzu.
Komponenten finden — npx shadcn@latest search.
Dokumentation und Beispiele abrufen — führen Sie npx shadcn@latest docs <component> aus, um URLs zu erhalten, und rufen Sie diese dann ab. Verwenden Sie npx shadcn@latest view, um Registry-Elemente zu durchsuchen, die Sie nicht installiert haben. Verwenden Sie npx shadcn@latest add --diff, um Änderungen an installierten Komponenten in der Vorschau anzuzeigen.
Installieren oder aktualisieren — npx shadcn@latest add. Verwenden Sie beim Aktualisieren vorhandener Komponenten --dry-run und --diff, um Änderungen zuerst in der Vorschau anzuzeigen (siehe Komponenten aktualisieren unten).
Importe in Drittanbieter-Komponenten korrigieren — Nach dem Hinzufügen von Komponenten aus Community-Registries (z.B. @bundui, @magicui) überprüfen Sie die hinzugefügten Nicht-UI-Dateien auf fest codierte Importpfade wie @/components/ui/.... Diese stimmen möglicherweise nicht mit den tatsächlichen Aliasen des Projekts überein. Verwenden Sie npx shadcn@latest info, um den korrekten ui-Alias zu erhalten (z.B. @workspace/ui/components) und schreiben Sie die Importe entsprechend um. Die CLI schreibt Importe für ihre eigenen UI-Dateien um, aber Drittanbieter-Registry-Komponenten können Standardpfade verwenden, die nicht mit dem Projekt übereinstimmen.
Hinzugefügte Komponenten überprüfen — Nach dem Hinzufügen einer Komponente oder eines Blocks aus einer beliebigen Registry lesen Sie immer die hinzugefügten Dateien und überprüfen Sie, ob sie korrekt sind. Überprüfen Sie auf fehlende Unterkomponenten (z.B. SelectItem ohne SelectGroup), fehlende Importe, falsche Komposition oder Verstöße gegen die Kritischen Regeln. Ersetzen Sie auch alle Icon-Importe mit der iconLibrary des Projekts aus dem Projektkontext (z.B. wenn das Registry-Element lucide-react verwendet, das Projekt aber hugeicons verwendet, tauschen Sie die Importe und Icon-Namen entsprechend aus). Beheben Sie alle Probleme, bevor Sie fortfahren.
Registry muss explizit sein — Wenn der Benutzer das Hinzufügen eines Blocks oder einer Komponente verlangt, raten Sie nicht die Registry. Wenn keine Registry angegeben ist (z.B. der Benutzer sagt "Füge einen Login-Block hinzu" ohne Angabe von @shadcn, @tailark, owner/repo usw.), fragen Sie, welche Registry verwendet werden soll. Verwenden Sie niemals standardmäßig eine Registry im Namen des Benutzers.
Presets wechseln — Fragen Sie zuerst den Benutzer: Überschreiben, Teilweise, Zusammenführen oder Überspringen?
- Aktuelles Preset inspizieren: npx shadcn@latest preset resolve. Verwenden Sie --json, wenn Sie strukturierte Werte benötigen.
- Eingehendes Preset inspizieren: npx shadcn@latest preset decode <code>. Verwenden Sie preset url <code> oder preset open <code>, um den Preset-Builder zu teilen oder zu öffnen.
- Überschreiben: npx shadcn@latest apply <code>. Überschreibt erkannte Komponenten, Schriftarten und CSS-Variablen.
- Teilweise: npx shadcn@latest apply <code> --only theme,font. Aktualisiert nur die ausgewählten Preset-Teile, ohne UI-Komponenten neu zu installieren. Unterstützte Werte sind theme und font; durch Kommas getrennte Kombinationen sind erlaubt. icon wird absichtlich nicht unterstützt, da Icon-Änderungen eine vollständige Neuinstallation der Komponenten erfordern können, um Inkonsistenzen zu vermeiden.
- Zusammenführen: Führen Sie zuerst npx shadcn@latest diff aus, um Unterschiede zwischen den installierten Komponenten und dem neuen Preset zu sehen. Verwenden Sie dann npx shadcn@latest apply <code> --only theme,font, um nur Design- und Schriftarteinstellungen zu übernehmen, und installieren Sie Komponenten einzeln nach Bedarf. Für Komponentenkonflikte verwenden Sie npx shadcn@latest add <component> --diff, um Änderungen zu überprüfen, bevor Sie sie anwenden.

Komponenten aktualisieren

Führen Sie zum Aktualisieren den Add-Befehl für die Komponente aus. Überprüfen Sie zuerst mit --dry-run und --diff, was sich ändert:

npx shadcn@latest add button --dry-run
npx shadcn@latest add button --diff
npx shadcn@latest add button

Fehlerbehebung

Bauschritte

Wenn Kompilierungsfehler auftreten:

befehl ausführen: npx shadcn@latest info --json – wenn dies fehlschlägt, ist shadcn nicht richtig eingerichtet.
JSON parsen – Der Kontext sollte unter dem Schlüssel components eine Liste installierter Komponenten enthalten.
Pfad auf Existenz prüfen – Prüfen Sie, ob resolvedPaths.ui vorhanden ist, mit den erwarteten Dateien.
Datei lesen – Wenn eine Komponentendatei beschädigt zu sein scheint, lesen Sie sie direkt.

Das Terminal kann shadcn nicht ausführen

Wenn der Befehl nicht gefunden wird, liegt dies daran, dass er nicht global installiert ist. Verwenden Sie stattdessen den Paket-Manager Ihres Projekts:

npm: npx shadcn@latest
pnpm: pnpm dlx shadcn@latest
bun: bunx --bun shadcn@latest

Fehler "No components.json found" (Keine components.json gefunden)

Wenn keine components.json vorhanden ist, initialisieren Sie shadcn/ui zuerst:

npx shadcn@latest init

Fehler beim Auflösen von Importen

Drittanbieter-Registry-Komponenten verwenden manchmal @/components/ui als Standard-Importpfad. Passen Sie die Importe an den tatsächlichen Alias des Projekts an, der in npx shadcn@latest info --json unter aliases.ui zu finden ist.

Verwaltung von Projektabhängigkeiten

shadcn/ui-spezifische Aktionen verwenden immer den packageManager des Projekts (aus dem Task-Kontext oder dem Ergebnis von npx shadcn@latest info). Beispiel: npx shadcn@latest add button.
Nicht-shadcn-Abhängigkeiten (z.B. date-fns, zod, recharts) werden mit dem Paket-Manager des Projekts installiert: npm install date-fns, pnpm add date-fns usw.
Installieren Sie keine Abhängigkeiten erneut, die bereits installiert sind. Prüfen Sie die package.json des Projekts oder die Liste der installierten Abhängigkeiten.
Verwenden Sie immer --save-exact, wenn Sie Abhängigkeiten installieren (z.B. pnpm add recharts --save-exact), um eine konsistente Paketauflösung zu gewährleisten.

Verwendung von Hooks

Verwenden Sie use-mobile aus @/hooks/use-mobile.
Siehe hooks.md für die vollständige Liste der verfügbaren Hooks.

Fehlerbehandlung mit KI

Wenn beim Erstellen, Hinzufügen, Aktualisieren oder Debuggen von Komponenten ein Fehler auftritt:

Führen Sie npx shadcn@latest info erneut aus, um den Projektkontext zu aktualisieren, falls der Fehler durch eine Änderung an components.json verursacht wurde.
Wenn der Fehler auf eine fehlerhafte Bedienung zurückzuführen zu sein scheint (z.B. eine nicht installierte Komponente verwenden), installieren Sie zuerst die erforderlichen Komponenten.
Wenn der Fehler auf einen fehlerhaften Import oder eine fehlerhafte API zurückzuführen zu sein scheint, lesen Sie die Komponentendokumentation mit npx shadcn@latest docs.```

shadcn-ui/ui

Was ist ui?

In Ihrer bevorzugten KI fragen

Dokumentation