Installation

Get started with ShadCn.Blazor in your Blazor project.

Prerequisites

  • .NET 8.0 or later
  • Blazor WebAssembly or Blazor Server project

1. Install NuGet Package

Install the ShadCn.Blazor package via NuGet Package Manager or the .NET CLI.

.NET CLI

dotnet add package ShadCn.Blazor.Components

Package Manager Console

Install-Package ShadCn.Blazor.Components

2. Add Theme CSS

Add the theme stylesheet to your index.html (Blazor WebAssembly) or _Host.cshtml / App.razor (Blazor Server). 

<link rel="stylesheet" href="_content/ShadCn.Blazor.Theme.Default/theme.css" />

3. Register Services

Register ShadCn.Blazor services in your Program.cs. 

builder.Services.AddShadCnBlazorComponents();

Add using ShadCn.Blazor.Components; if needed.

4. Add Imports

Add the following using statements to your _Imports.razor file. 

@using ShadCn.Blazor.Components
@using ShadCn.Blazor.Components.Alert
@using ShadCn.Blazor.Components.Badge
@using ShadCn.Blazor.Components.Button
@using ShadCn.Blazor.Components.Card
@using ShadCn.Blazor.Components.Input
@using ShadCn.Blazor.Components.Separator

Add imports for each component namespace you want to use in your project.

5. Start Using Components

You're all set! Start using the components in your Blazor pages and components. 

<Button>Click me</Button>

<Card>
    <CardHeader>
        <CardTitle>Welcome</CardTitle>
        <CardDescription>Get started with ShadCn.Blazor</CardDescription>
    </CardHeader>
    <CardContent>
        <p>Your content here</p>
    </CardContent>
</Card>

<Alert>
    <AlertTitle>Heads up!</AlertTitle>
    <AlertDescription>You can customize all components.</AlertDescription>
</Alert>

Dark Mode

The theme supports dark mode out of the box. Add the dark class to your <html> element to enable dark mode. 

<html class="dark">
  ...
</html>

You can toggle dark mode dynamically using JavaScript or by persisting the user's preference.

Customization

All components accept a Class parameter that allows you to add custom Tailwind CSS classes to override or extend the default styling. 

<Button Class="w-full">Full Width Button</Button>
<Card Class="max-w-md mx-auto">...</Card>

For deeper customization, you can override the CSS variables defined in the theme. All color values use HSL format (hue saturation% lightness%) without the hsl() wrapper.

Light Mode Variables

:root {
  /* Background colors */
  --background: 0 0% 100%;           /* Page background */
  --foreground: 222.2 84% 4.9%;      /* Default text color */

  /* Card */
  --card: 0 0% 100%;                 /* Card background */
  --card-foreground: 222.2 84% 4.9%; /* Card text color */

  /* Popover (dropdowns, tooltips) */
  --popover: 0 0% 100%;              /* Popover background */
  --popover-foreground: 222.2 84% 4.9%; /* Popover text */

  /* Primary (buttons, links, accents) */
  --primary: 222.2 47.4% 11.2%;      /* Primary background */
  --primary-foreground: 210 40% 98%; /* Primary text */

  /* Secondary */
  --secondary: 210 40% 96.1%;        /* Secondary background */
  --secondary-foreground: 222.2 47.4% 11.2%; /* Secondary text */

  /* Muted (subtle backgrounds, placeholder text) */
  --muted: 210 40% 96.1%;            /* Muted background */
  --muted-foreground: 215.4 16.3% 46.9%; /* Muted text */

  /* Accent (hover states, highlights) */
  --accent: 210 40% 96.1%;           /* Accent background */
  --accent-foreground: 222.2 47.4% 11.2%; /* Accent text */

  /* Destructive (errors, delete actions) */
  --destructive: 0 84.2% 60.2%;      /* Destructive background */
  --destructive-foreground: 210 40% 98%; /* Destructive text */

  /* Borders and inputs */
  --border: 214.3 31.8% 91.4%;       /* Border color */
  --input: 214.3 31.8% 91.4%;        /* Input border color */
  --ring: 222.2 84% 4.9%;            /* Focus ring color */

  /* Border radius */
  --radius: 0.5rem;                  /* Base border radius */

  /* Sidebar */
  --sidebar: var(--background);                   /* Sidebar background */
  --sidebar-foreground: var(--foreground);         /* Sidebar text color */
  --sidebar-primary: var(--primary);               /* Sidebar primary (active item) */
  --sidebar-primary-foreground: var(--primary-foreground); /* Sidebar primary text */
  --sidebar-accent: var(--accent);                 /* Sidebar hover/accent */
  --sidebar-accent-foreground: var(--accent-foreground);   /* Sidebar accent text */
  --sidebar-border: var(--border);                 /* Sidebar border color */
  --sidebar-ring: var(--ring);                     /* Sidebar focus ring */
}

Dark Mode Variables

.dark {
  /* Background colors */
  --background: 222.2 84% 4.9%;      /* Page background */
  --foreground: 210 40% 98%;         /* Default text color */

  /* Card */
  --card: 222.2 84% 4.9%;            /* Card background */
  --card-foreground: 210 40% 98%;    /* Card text color */

  /* Popover */
  --popover: 222.2 84% 4.9%;         /* Popover background */
  --popover-foreground: 210 40% 98%; /* Popover text */

  /* Primary */
  --primary: 210 40% 98%;            /* Primary background */
  --primary-foreground: 222.2 47.4% 11.2%; /* Primary text */

  /* Secondary */
  --secondary: 217.2 32.6% 17.5%;    /* Secondary background */
  --secondary-foreground: 210 40% 98%; /* Secondary text */

  /* Muted */
  --muted: 217.2 32.6% 17.5%;        /* Muted background */
  --muted-foreground: 215 20.2% 65.1%; /* Muted text */

  /* Accent */
  --accent: 217.2 32.6% 17.5%;       /* Accent background */
  --accent-foreground: 210 40% 98%;  /* Accent text */

  /* Destructive */
  --destructive: 0 62.8% 30.6%;      /* Destructive background */
  --destructive-foreground: 210 40% 98%; /* Destructive text */

  /* Borders and inputs */
  --border: 217.2 32.6% 17.5%;       /* Border color */
  --input: 217.2 32.6% 17.5%;        /* Input border color */
  --ring: 212.7 26.8% 83.9%;         /* Focus ring color */

  /* Sidebar (defaults reference the above values) */
  --sidebar: var(--background);
  --sidebar-foreground: var(--foreground);
  --sidebar-primary: var(--primary);
  --sidebar-primary-foreground: var(--primary-foreground);
  --sidebar-accent: var(--accent);
  --sidebar-accent-foreground: var(--accent-foreground);
  --sidebar-border: var(--border);
  --sidebar-ring: var(--ring);
}

Font Families

The theme uses Geist font (same as shadcn/ui). You can override fonts in your CSS: 

@theme {
  --font-sans: "Your Font", system-ui, sans-serif;
  --font-mono: "Your Mono Font", monospace;
}

Border Radius

Adjust the border radius for all components by changing the --radius variable: 

:root {
  --radius: 0.25rem;  /* Smaller, more subtle */
  --radius: 0.5rem;   /* Default */
  --radius: 0.75rem;  /* Larger, more rounded */
  --radius: 1rem;     /* Very rounded */
}

Next Steps

Explore the components in the sidebar to see examples and usage documentation for each component.

View Button View Card