Shadcn Svelte

shadcn-svelte

A framework for building UI, components, and design systems for Svelte. Components are added as source to the user's project via the CLI.

IMPORTANT: Run all CLI commands using the project's package runner: npx shadcn-svelte@latest, pnpm dlx shadcn-svelte@latest, or bunx --bun shadcn-svelte@latest — based on the project's package manager. Examples below use npx shadcn-svelte@latest but substitute the correct runner for the project.

Current Project Context

Read components.json at the project root and, when you need the live file layout, list the directory given by the aliases.ui path (resolved with the same rules as the CLI).

Imports (Svelte)

Each component lives in its own folder with an index.ts barrel. Match the installation docs:

• Multi-part components (dialog, select, card, field, tabs, …): import * as Dialog from "$lib/components/ui/dialog" then Dialog.Content, Dialog.Title, Card.Root, Card.Header, etc. — whatever the barrel exports (short names and/or Root as … aliases).
• Single-component barrels (only one meaningful component in the folder): named imports — import { Button } from "$lib/components/ui/button" and <Button>, not import * as Button + Button.Root. Same pattern for { Input }, { Badge }, { Spinner }, { Checkbox }, { Separator }, { Skeleton }, etc.

import * as Dialog from "$lib/components/ui/dialog";
import { Button } from "$lib/components/ui/button";
import { Separator } from "$lib/components/ui/separator";

Use the real aliases from components.json (often $lib/components/ui/...), not hardcoded paths.

Principles

1. Use existing components first. Run npx shadcn-svelte@latest add with no arguments to browse available components, or check Components before writing custom UI.
2. Compose, don't reinvent. Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.
3. Use built-in variants before custom styles. variant="outline", size="sm", etc.
4. Use semantic colors. bg-primary, text-muted-foreground — never raw values like bg-blue-500.

Critical Rules

These rules are always enforced. Each links to a file with Incorrect/Correct code pairs.

Styling & Tailwind → styling.md

• class for layout, not styling. Never override component colors or typography.
• No space-x-* or space-y-*. Use flex with gap-*. For vertical stacks, flex flex-col gap-*.
• Use size-* when width and height are equal. size-10 not w-10 h-10.
• Use truncate shorthand. Not overflow-hidden text-ellipsis whitespace-nowrap.
• No manual dark: color overrides. Use semantic tokens (bg-background, text-muted-foreground).
• Use cn() for conditional classes. Don't write manual template literal ternaries.
• No manual z-index on overlay components. Dialog, Sheet, Popover, etc. handle their own stacking.

Forms & Inputs → forms.md

• Forms use Field.FieldGroup + Field.Field. Never use raw div with space-y-* or grid gap-* for form layout.
• InputGroup uses InputGroup.Input/InputGroup.Textarea. Never raw Input/Textarea inside InputGroup.Root.
• Buttons inside inputs use InputGroup.Root + InputGroup.Addon.
• Option sets (2–7 choices) use ToggleGroup. Don't loop Button with manual active state.
• Field.FieldSet + Field.FieldLegend for grouping related checkboxes/radios. Don't use a div with a heading.
• Field validation uses data-invalid + aria-invalid. data-invalid on Field, aria-invalid on the control. For disabled: data-disabled on Field, disabled on the control.

Component Structure → composition.md

• Items always inside their Group. Select.Item → Select.Group. DropdownMenu.Item → DropdownMenu.Group. Command.Item → Command.Group.
• Custom triggers. Wrap controls in Dialog.Trigger / AlertDialog.Trigger, or control open state with bind:open on the root — see component docs.
• Dialog, Sheet, and Drawer always need a Title. Dialog.Title, Sheet.Title, Drawer.Title required for accessibility. Use class="sr-only" if visually hidden.
• Use full Card composition. Card.Header/Card.Title/Card.Description/Card.Content/Card.Footer. Don't dump everything in Card.Content.
• Button has no isPending/isLoading. Compose with Spinner inside Button + disabled; use data-icon="inline-start" / inline-end on Spinner for correct spacing (import { Button }, import { Spinner }).
• Tabs.Trigger must be inside Tabs.List. Never render triggers directly in Tabs.
• Avatar always needs Avatar.Fallback. For when the image fails to load.

Use Components, Not Custom Markup → composition.md

• Use existing components before custom markup. Check if a component exists before writing a styled div.
• Callouts use Alert. Don't build custom styled divs.
• Empty states use Empty. Don't build custom empty state markup.
• Toast via svelte-sonner. Use toast() from svelte-sonner with the Sonner component from your UI folder.
• Use Separator instead of <hr> or a div with border-only classes.
• Use Skeleton for loading placeholders. No custom animate-pulse divs.
• Use Badge instead of custom styled spans.

Icons → icons.md

• Icons in <Button> use data-icon. data-icon="inline-start" or data-icon="inline-end" on the icon.
• No sizing classes on icons inside components. Components handle icon sizing via CSS. No size-4 or w-4 h-4.
• Pass icons as components. Import from the configured iconLibrary (e.g. @lucide/svelte), not string keys.

CLI

• Presets — copy the encoded string from the design-system builder on shadcn-svelte.com and pass it to npx shadcn-svelte@latest init --preset <code>.

Key Patterns

These are the most common patterns that differentiate correct shadcn-svelte code. For edge cases, see the linked rule files above.

<script lang="ts">
  import * as Field from "$lib/components/ui/field";
  import { Input } from "$lib/components/ui/input";
  import { Button } from "$lib/components/ui/button";
  import SearchIcon from "@lucide/svelte/icons/search";
  import { Badge } from "$lib/components/ui/badge";
  import * as Avatar from "$lib/components/ui/avatar";
</script>

<!-- Form layout: Field.FieldGroup + Field.Field, not div + Label. -->
<Field.FieldGroup>
  <Field.Field>
    <Field.FieldLabel for="email">Email</Field.FieldLabel>
    <Input id="email" />
  </Field.Field>
</Field.FieldGroup>

<!-- Validation: data-invalid on Field, aria-invalid on the control. -->
<Field.Field data-invalid>
  <Field.FieldLabel for="email">Email</Field.FieldLabel>
  <Input id="email" aria-invalid />
  <Field.FieldDescription>Invalid email.</Field.FieldDescription>
</Field.Field>

<!-- Icons in buttons: data-icon, no sizing classes. -->
<Button>
  <SearchIcon data-icon="inline-start" />
  Search
</Button>

<!-- Spacing: gap-*, not space-y-*. -->
<div class="flex flex-col gap-4"></div>

<!-- Equal dimensions: size-*, not w-* h-*. -->
<Avatar.Root class="size-10">
  <Avatar.Image src="/u.png" alt="User" />
  <Avatar.Fallback>U</Avatar.Fallback>
</Avatar.Root>

<!-- Status colors: Badge variants or semantic tokens, not raw colors. -->
<Badge variant="secondary">+20.1%</Badge>