# shadcn-svelte

shadcn-svelte is a community-led Svelte port of shadcn/ui that provides accessible and customizable components for Svelte and SvelteKit applications. Rather than installing components as npm packages, shadcn-svelte uses a CLI tool to copy component source code directly into your project, giving you complete ownership and customization control. Components are built with Tailwind CSS, use Tailwind Variants for styling variants, and leverage modern Svelte 5 features like runes and snippets.

The project consists of a CLI tool for managing components, a component registry system, and comprehensive documentation. The CLI handles project initialization, component installation, and updates, while the registry provides a centralized source for component definitions, dependencies, and metadata. This architecture allows developers to pick and choose specific components, modify them freely, and maintain full control over their UI layer without being locked into a package ecosystem.

## CLI Commands

### Initialize Project

Initialize shadcn-svelte in your SvelteKit project by creating a `components.json` configuration file and setting up path aliases.

```bash
# Interactive initialization
npx shadcn-svelte@latest init

# Non-interactive with options
npx shadcn-svelte@latest init \
  --cwd ./my-project \
  --base-color slate \
  --css src/app.css \
  --components-alias '$lib/components' \
  --utils-alias '$lib/utils' \
  --hooks-alias '$lib/hooks' \
  --ui-alias '$lib/components/ui' \
  --lib-alias '$lib'
```

**Generated components.json:**

```json
{
  "$schema": "https://www.shadcn-svelte.com/schema.json",
  "aliases": {
    "lib": "$lib",
    "components": "$lib/components",
    "ui": "$lib/components/ui",
    "utils": "$lib/utils",
    "hooks": "$lib/hooks"
  },
  "tailwind": {
    "css": "src/app.css",
    "baseColor": "slate"
  },
  "typescript": true,
  "registry": "https://www.shadcn-svelte.com/registry"
}
```

### Add Components

Add one or more components to your project. Components are copied directly into your codebase with all dependencies resolved.

```bash
# Interactive selection
npx shadcn-svelte@latest add

# Add specific components
npx shadcn-svelte@latest add button card input

# Add all components
npx shadcn-svelte@latest add --all

# Skip confirmation and dependency installation
npx shadcn-svelte@latest add button --yes --no-deps

# Use proxy for registry access
npx shadcn-svelte@latest add button --proxy http://proxy.example.com:8080

# Add to specific directory
npx shadcn-svelte@latest add button --cwd ./my-project
```

**Example: Adding button component creates the following structure:**

```
src/lib/
├── components/
│   └── ui/
│       └── button/
│           └── button.svelte
└── utils.ts
```

### Update Components

Update existing components to their latest versions from the registry.

```bash
# Interactive selection
npx shadcn-svelte@latest update

# Update specific components
npx shadcn-svelte@latest update button card

# Update all components
npx shadcn-svelte@latest update --all --yes
```

## Component Usage

### Button Component

Flexible button component with multiple variants and sizes using Tailwind Variants.

```svelte
<script>
  import { Button } from "$lib/components/ui/button";
</script>

<!-- Default button -->
<Button>Click me</Button>

<!-- Variant examples -->
<Button variant="destructive">Delete</Button>
<Button variant="outline">Cancel</Button>
<Button variant="secondary">Secondary Action</Button>
<Button variant="ghost">Ghost Button</Button>
<Button variant="link">Link Button</Button>

<!-- Size examples -->
<Button size="sm">Small</Button>
<Button size="default">Default</Button>
<Button size="lg">Large</Button>
<Button size="icon">🔍</Button>

<!-- With icon -->
<Button>
  <svg><!-- icon --></svg>
  Button with Icon
</Button>

<!-- Disabled state -->
<Button disabled>Disabled</Button>

<!-- Custom classes -->
<Button class="custom-class">Custom Styled</Button>

<!-- Using as child component with render delegation -->
<Button child={MyCustomElement} />
```

### Card Component

Container component for grouping related content with header, content, and footer sections.

```svelte
<script>
  import { Card } from "$lib/components/ui/card";
</script>

<Card.Root>
  <Card.Header>
    <Card.Title>Card Title</Card.Title>
    <Card.Description>Card description text</Card.Description>
  </Card.Header>
  <Card.Content>
    <p>Main content goes here</p>
  </Card.Content>
  <Card.Footer>
    <Button>Action</Button>
  </Card.Footer>
</Card.Root>

<!-- Complex card example with form -->
<Card.Root class="w-full max-w-sm">
  <Card.Header>
    <Card.Title>Create Account</Card.Title>
    <Card.Description>Enter your details below to create your account</Card.Description>
  </Card.Header>
  <Card.Content>
    <form>
      <div class="space-y-4">
        <div class="space-y-2">
          <Label for="email">Email</Label>
          <Input id="email" type="email" placeholder="m@example.com" />
        </div>
        <div class="space-y-2">
          <Label for="password">Password</Label>
          <Input id="password" type="password" />
        </div>
      </div>
    </form>
  </Card.Content>
  <Card.Footer>
    <Button class="w-full">Sign up</Button>
  </Card.Footer>
</Card.Root>
```

### Input Component

Form input component with label integration and error states.

```svelte
<script>
  import { Input } from "$lib/components/ui/input";
  import { Label } from "$lib/components/ui/label";

  let value = $state("");
  let email = $state("");
</script>

<!-- Basic input -->
<Input placeholder="Enter text" bind:value={value} />

<!-- With label -->
<div class="space-y-2">
  <Label for="email">Email</Label>
  <Input id="email" type="email" bind:value={email} />
</div>

<!-- Disabled input -->
<Input disabled placeholder="Disabled input" />

<!-- Input with error state -->
<Input
  aria-invalid="true"
  placeholder="Invalid input"
  value={email}
/>

<!-- File input -->
<Input type="file" />

<!-- Number input with validation -->
<Input
  type="number"
  min="0"
  max="100"
  placeholder="0-100"
  bind:value={value}
/>
```

## Configuration API

### components.json Schema

The configuration file that defines project structure and aliases for the CLI.

```typescript
{
  // Schema for validation
  "$schema": "https://www.shadcn-svelte.com/schema.json",

  // Path aliases for imports
  "aliases": {
    "lib": "$lib",              // Root library alias
    "components": "$lib/components",  // Components directory
    "ui": "$lib/components/ui",      // UI components
    "utils": "$lib/utils",           // Utility functions
    "hooks": "$lib/hooks"            // Custom hooks
  },

  // Tailwind configuration
  "tailwind": {
    "css": "src/app.css",      // Global CSS file path
    "baseColor": "slate"       // Base color theme: slate|gray|zinc|neutral|stone
  },

  // TypeScript configuration
  "typescript": true,          // boolean or { "config": "path/to/tsconfig.json" }

  // Registry URL for fetching components
  "registry": "https://www.shadcn-svelte.com/registry"
}
```

**Loading config programmatically:**

```typescript
import * as cliConfig from "shadcn-svelte/utils/get-config";

// Load configuration from disk
const config = cliConfig.loadConfig("/path/to/project");

// Get resolved configuration with absolute paths
const resolved = await cliConfig.getConfig("/path/to/project");
console.log(resolved.resolvedPaths.ui); // /path/to/project/src/lib/components/ui

// Write configuration
cliConfig.writeConfig("/path/to/project", {
  aliases: {
    lib: "$lib",
    components: "$lib/components",
    ui: "$lib/components/ui",
    utils: "$lib/utils",
    hooks: "$lib/hooks"
  },
  tailwind: {
    css: "src/app.css",
    baseColor: "slate"
  },
  typescript: true
});
```

### Path Alias Resolution

Configure TypeScript/JavaScript path aliases in `tsconfig.json` or `jsconfig.json` to match the aliases defined in `components.json`.

```json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "$lib": ["./src/lib"],
      "$lib/*": ["./src/lib/*"]
    }
  }
}
```

**SvelteKit Configuration:**

```javascript
// svelte.config.js
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

/** @type {import('@sveltejs/kit').Config} */
const config = {
  preprocess: vitePreprocess(),
  kit: {
    alias: {
      $lib: './src/lib',
      '$lib/*': './src/lib/*'
    }
  }
};

export default config;
```

## Registry API

### Fetching Registry Index

Retrieve the complete list of available components from the registry.

```typescript
import * as registry from "shadcn-svelte/utils/registry";

const registryUrl = "https://www.shadcn-svelte.com/registry";
const index = await registry.getRegistryIndex(registryUrl);

// Index structure
console.log(index);
// [
//   {
//     name: "button",
//     type: "registry:ui",
//     registryDependencies: [],
//     dependencies: ["tailwind-variants"],
//     devDependencies: []
//   },
//   {
//     name: "card",
//     type: "registry:ui",
//     registryDependencies: [],
//     dependencies: []
//   }
// ]

// Filter by type
const uiComponents = index.filter(item => item.type === "registry:ui");
const blocks = index.filter(item => item.type === "registry:block");
```

### Resolving Component Dependencies

Resolve a component and all its registry dependencies recursively.

```typescript
import * as registry from "shadcn-svelte/utils/registry";

const registryUrl = "https://www.shadcn-svelte.com/registry";
const index = await registry.getRegistryIndex(registryUrl);

// Resolve component tree with dependencies
const resolved = await registry.resolveRegistryItems({
  registryIndex: index,
  items: ["button", "card"]
});

console.log(resolved);
// Returns all components including transitive dependencies

// Fetch full component data with file contents
const components = await registry.fetchRegistryItems({
  baseUrl: registryUrl,
  items: resolved
});

console.log(components[0]);
// {
//   name: "button",
//   type: "registry:ui",
//   files: [
//     {
//       type: "registry:ui",
//       target: "button/button.svelte",
//       content: "<script lang=\"ts\" module>..."
//     }
//   ],
//   dependencies: ["tailwind-variants"],
//   cssVars: { ... }
// }
```

### Base Color Themes

Fetch CSS variable definitions for different color themes.

```typescript
import * as registry from "shadcn-svelte/utils/registry";

const registryUrl = "https://www.shadcn-svelte.com/registry";
const baseColor = await registry.getRegistryBaseColor(registryUrl, "slate");

console.log(baseColor);
// {
//   name: "slate",
//   label: "Slate",
//   cssVarsTemplate: "@tailwind base;\n@tailwind components;..."
// }

// Available base colors
const colors = registry.getBaseColors();
// [
//   { name: "slate", label: "Slate" },
//   { name: "gray", label: "Gray" },
//   { name: "zinc", label: "Zinc" },
//   { name: "neutral", label: "Neutral" },
//   { name: "stone", label: "Stone" }
// ]
```

## Utility Functions

### cn() - Class Name Utility

Merge Tailwind CSS classes with proper precedence handling using clsx and tailwind-merge.

```typescript
import { cn } from "$lib/utils";

// Basic usage
const className = cn("px-4 py-2", "bg-blue-500");
// "px-4 py-2 bg-blue-500"

// Conditional classes
const buttonClass = cn(
  "px-4 py-2 rounded",
  isActive && "bg-blue-500",
  isDisabled && "opacity-50 cursor-not-allowed"
);

// Override classes (tailwind-merge handles conflicts)
const merged = cn("px-4 text-sm", "px-6 text-lg");
// "px-6 text-lg" (later values override earlier ones)

// Array and object syntax
const classes = cn(
  "base-class",
  ["conditional-class", isTrue && "another-class"],
  {
    "active": isActive,
    "disabled": isDisabled
  }
);

// Component usage
export let variant: "default" | "outline" = "default";
export let className: string = "";

const buttonClasses = cn(
  "inline-flex items-center justify-center",
  {
    "bg-primary text-white": variant === "default",
    "border border-primary text-primary": variant === "outline"
  },
  className
);
```

### Component Variants with Tailwind Variants

Define type-safe component variants using the tailwind-variants library.

```typescript
import { tv, type VariantProps } from "tailwind-variants";

// Define variants
export const buttonVariants = tv({
  base: "inline-flex items-center justify-center rounded-md font-medium transition-all",
  variants: {
    variant: {
      default: "bg-primary text-primary-foreground hover:bg-primary/90",
      destructive: "bg-destructive text-white hover:bg-destructive/90",
      outline: "border bg-background hover:bg-accent",
      ghost: "hover:bg-accent hover:text-accent-foreground"
    },
    size: {
      default: "h-9 px-4 py-2",
      sm: "h-8 px-3",
      lg: "h-10 px-6",
      icon: "size-9"
    }
  },
  defaultVariants: {
    variant: "default",
    size: "default"
  }
});

// Use in component
type ButtonProps = VariantProps<typeof buttonVariants>;

export let variant: ButtonProps["variant"] = "default";
export let size: ButtonProps["size"] = "default";

const classes = buttonVariants({ variant, size });
```

## Integration Patterns

shadcn-svelte excels in SvelteKit applications where developers need complete control over their component layer while maintaining consistency and accessibility. The copy-paste approach means components become part of your codebase immediately, allowing for project-specific customizations without fighting against framework constraints. This is particularly valuable for design systems, where teams need to enforce specific styling patterns while allowing individual projects to adapt components to their needs. The CLI handles the tedious work of dependency resolution and file organization, while developers retain full ownership of the component code.

The registry-based architecture enables teams to create private component registries for organization-specific components, extending the public registry with custom elements. By pointing the `registry` field in `components.json` to a custom endpoint, teams can maintain internal design systems that follow the same patterns as shadcn-svelte. Components integrate seamlessly with existing Svelte 5 features like runes (`$state`, `$derived`, `$props`) and snippets for render delegation, making them feel native to modern Svelte development. The Tailwind CSS foundation ensures consistent styling across components while remaining flexible enough for design token customization through CSS variables, and the TypeScript-first approach provides excellent type safety and autocomplete support throughout the development experience.