# ShellUI
> ShellUI is a shadcn/ui-style component library for Blazor. Components are installed into your project as source files with the `shellui` CLI, or used from the `ShellUI.Components` NuGet package. These docs are for v0.3.6. Other versions: [v0.4.0](https://shellui.dev/docs/v0.4/llms.txt), [v0.2.1](https://shellui.dev/docs/v0.2.1/llms.txt).
## Rules for AI agents
Read these before writing UI in a ShellUI project.
1. **Use ShellUI's components; don't write your own.** Before building a button, input, dialog, sheet, dropdown, table, chart, sidebar or any other UI element, check whether ShellUI has it. `llms.txt` lists every component with its `shellui add` command.
2. **Check what the project already has.**
- `shellui.json` in the project root means the project uses the CLI. `InstalledComponents` lists what's installed and `ComponentsPath` says where (default `Components/UI`).
- `shellui list --installed` and `shellui list --available` print the same from the terminal.
- A `PackageReference` to `ShellUI.Components` in the `.csproj` means the project uses the NuGet package, which already contains every component.
3. **Install a missing component; never recreate it.** Run `shellui add `, or several at once: `shellui add button card dialog`. Don't hand-write a file with a ShellUI component's name, port one from shadcn/ui (React), or build a look-alike in another folder. `add` also installs the sub-components, models, variants and NuGet packages a component needs, and adds the `@using` lines to `_Imports.razor`.
4. **CLI projects own the source.** Installed components are ordinary `.razor` files in `Components/UI`, in the `.Components.UI` namespace, and may be edited. Package projects use `@using ShellUI.Components` and link `_content/ShellUI.Components/shellui-all.css`; `shellui add` isn't used there. Pick one per project: both define the same component names.
5. **Give components an interactive render mode.** Set it app-wide with `` in `App.razor`, or per page with `@rendermode InteractiveServer`. Under static server rendering, components render but clicks, dialogs, dropdowns and toggles do nothing.
6. **Follow the API reference.** Each component page has a parameter table. Variants and sizes are enums (`Variant="ButtonVariant.Destructive"`, `Size="ButtonSize.Sm"`). Add classes with `Class` (`ClassName` is deprecated). Don't guess parameter names.
7. **Style with the theme tokens.** ShellUI uses Tailwind CSS v4 and shadcn-style tokens: `bg-background`, `text-foreground`, `bg-primary`, `text-primary-foreground`, `bg-muted`, `text-muted-foreground`, `border-border`, `bg-card`, `ring-ring`. Use them instead of fixed colors so dark mode keeps working. The theme lives in `wwwroot/input.css`; `shellui theme apply ` replaces it with a tweakcn theme.
8. **Copy the examples.** The Razor examples on each component page are the source of working demos, so they compile as shown.
9. **Match the version.** `shellui --version` (or the `ShellUI.Components` version in the `.csproj`) says which docs apply. Read the release notes before upgrading: `shellui update` rewrites installed components from the CLI's templates (and keeps files you changed). From 0.4, run `shellui migrate` after `update` to rewrite pages for template API changes, and `shellui doctor` to check the project's setup.
---
# ShellUI Documentation
> CLI-first Blazor component library inspired by shadcn/ui
Source: https://shellui.dev/docs/v0.3/introduction
Welcome to ShellUI v0.3.6, the latest release of the 0.3 line of the CLI-first Blazor component library inspired by shadcn/ui. It ships 76 components, Tailwind CSS 4.3.2, and everything from the 0.3.0 alphas and release candidates.
> **0.4 is the current release**
>
> ShellUI 0.4.0 is the current stable release: see the [v0.4 docs](https://shellui.dev/docs/v0.4/introduction.md). These pages cover 0.3.6, so their install commands name `--version 0.3.6`; without it, `dotnet tool install` and `dotnet add package` get 0.4.
v0.3.6 76 components .NET 8, 9 & 10 (CLI) tweakcn themes
> The CLI needs the .NET 10 SDK and works in Blazor projects on .NET 8, 9 and 10. The `ShellUI.Components` NuGet package targets .NET 10 only; on .NET 8 or 9, use the CLI.
## Getting Started
### Installation
Choose your preferred installation method:
**CLI Installation (Recommended)**
```bash
dotnet tool install -g ShellUI.CLI --version 0.3.6
# Or upgrade an existing install
dotnet tool update -g ShellUI.CLI --version 0.3.6
# Initialize in your Blazor project (safe to re-run)
shellui init
# Add components
shellui add button input card table chart drawer sheet
```
**NuGet Package**
```bash
dotnet add package ShellUI.Components --version 0.3.6
```
With the package, add `@using ShellUI.Components` to `_Imports.razor`, give the app an interactive render mode (for example ``), and link `_content/ShellUI.Components/shellui-all.css`. See the [NuGet guide](https://shellui.dev/docs/v0.3/installation/nuget.md).
### Quick Example
```razor
Welcome to ShellUIBuild beautiful Blazor applications
Your content goes here.
```
## Component Categories
Explore our comprehensive component library, organized by category:
- [Form Components](https://shellui.dev/docs/v0.3/components/form.md): Buttons, inputs, selects, and form controls
- [Layout Components](https://shellui.dev/docs/v0.3/components/layout.md): Cards, dialogs, sheets, and structural elements
- [Navigation Components](https://shellui.dev/docs/v0.3/components/navigation.md): Menus, breadcrumbs, tabs, and navigation elements
- [Interactive Components](https://shellui.dev/docs/v0.3/components/interactive.md): Dropdowns, tooltips, and interactive elements
- [Advanced Components](https://shellui.dev/docs/v0.3/components/advanced.md): Calendars, charts, carousels, steppers, and complex UI elements
## What's New in v0.3.6
- **Safelist:** `shellui-classes.txt`, used by apps that build their own Tailwind CSS from the NuGet package, now has the 181 classes it was missing, among them the dialog's centring and the Sonner variant colours. The precompiled `shellui-all.css` wasn't affected.
- **Package icon:** `ShellUI.CLI` and `ShellUI.Components` show the ShellUI logo on nuget.org. See the [release notes](https://shellui.dev/docs/v0.3/release-notes.md).
## What's New in v0.3.5
The 0.4 prerelease fixes come to the stable line:
- **One Tailwind CLI per machine:** `init` no longer downloads the 112 MB Tailwind CLI into every project. It lives once in `~/.shellui/bin`, downloads resume over slow connections, and a failed download no longer stops `init`.
- **`shellui update` keeps your changes** and installs dependencies a component gained; **`shellui remove`** honours a custom components path and removes the dashboard layouts; **`shellui add` never downgrades** a NuGet package.
- **`Class` wins over a component's own classes,** so the `!` modifier is no longer needed. See [Theming](https://shellui.dev/docs/v0.3/theming.md#per-component-changes).
- **Focus stays inside open overlays** (Dialog, Alert Dialog, Sheet, Drawer), and fixes to RadioGroup, ScrollArea, DatePicker, TimePicker, Sheet, Drawer and Label.
- **Razor class libraries:** see [Razor Class Library](https://shellui.dev/docs/v0.3/installation/razor-class-library.md).
See the [release notes](https://shellui.dev/docs/v0.3/release-notes.md).
## What's New in v0.3.4
Dark mode fixes: the themes set `color-scheme`, so the browser draws its own controls (date pickers, number spinners, scrollbars, autofill, `
```
## 3. Add the theme script to each app
`ThemeToggle` stores the choice in `localStorage` and sets the `dark` class on ``, but only after the first render. In a normal app, `init` puts this script in the host page's `
` so the right theme applies before the first paint. A library has no host page, so add it to each app yourself:
```html
```
Without it, a user who picked dark mode sees a flash of the light theme on every load, and the toggle starts out of step.
## 4. Classes used in an app's own markup
Tailwind generates CSS only for classes it finds in the files it scans, and the library's build scans the library. Pages and components that live in the library are covered. If an app has its own markup (a page or layout only one app has), point Tailwind at it from the library's `wwwroot/input.css`. Paths are relative to `input.css`:
```css
@import "tailwindcss";
@source "../../MyApp.Web/Components";
@source "../../MyApp.Mobile/Components";
```
Rebuild the library after adding a `@source` line.
## 5. Apps that keep state in browser storage
Apps that read `ProtectedLocalStorage`, `ProtectedSessionStorage` or `localStorage` during startup (for example to restore a signed-in session) can't do it while prerendering, because the page renders on the server before the browser is connected. Render those apps without prerendering:
```razor
```
MAUI Blazor Hybrid apps don't prerender, so this applies only to the web app.
## Checklist
- [ ] `shellui init` ran in the library, and components are in `MyApp.UI/Components/UI`
- [ ] Each app references the library and links `_content//app.css` and `shellui.js` (before the Blazor script)
- [ ] Each app's host page has the theme script in ``
- [ ] `@source` lines for markup that lives in an app rather than the library
- [ ] Web apps that restore state from browser storage use `prerender: false`
- [ ] `dotnet build` the library after changing components or `input.css`, then run each app and toggle dark mode
---
# Comparison
> How ShellUI compares to other Blazor UI libraries
Source: https://shellui.dev/docs/v0.3/comparison
How is ShellUI different from other existing Blazor UI libraries?
## MudBlazor
MudBlazor is a mature, Bootstrap-based component library with a large community and extensive documentation. It's one of the most popular choices for Blazor applications.
ShellUI takes a different approach by offering CLI-first installation, component ownership, and Tailwind CSS integration. If you prefer Bootstrap styling and want a battle-tested library with extensive community support, MudBlazor might be a better choice. However, if you want full control over component code, prefer Tailwind CSS, or need a CLI-first workflow, ShellUI offers unique advantages.
### Feature Table
| Feature | ShellUI | MudBlazor |
|---------|---------|-----------|
| Installation Method | CLI + NuGet | NuGet |
| Component Ownership | Yes | No |
| Tailwind CSS | Yes (v4.3.2) | No (Bootstrap) |
| No Node.js Required | Yes (Standalone CLI) | N/A |
| Hybrid Workflow | Yes | No |
| Type-Safe Variants | Yes (CVA) | No |
| Charts | Yes (ApexCharts) | Yes (MudChart) |
| Free & Open Source | Yes (MIT) | Yes (MIT) |
| Components | 80 | 70+ |
| Customization | Full Control | Limited |
| Current Status | v0.3.6 (0.4.0 is the current stable) | Mature |
## Radzen
Radzen is a commercial Blazor component library that offers visual design tools and code generation capabilities. It provides a comprehensive set of components with a focus on rapid application development.
ShellUI is completely free and open source, offering component ownership through the CLI approach. Radzen's visual designer and code generation tools are powerful, but come with commercial licensing requirements. If you need visual design tools and are willing to pay for premium features, Radzen might suit your needs. ShellUI is better suited for developers who want full control, prefer Tailwind CSS, and want to avoid vendor lock-in.
### Feature Table
| Feature | ShellUI | Radzen |
|---------|---------|--------|
| Installation Method | CLI + NuGet | NuGet |
| Component Ownership | Yes | No |
| Tailwind CSS | Yes (v4.3.2) | No (Custom) |
| Visual Designer | No | Yes |
| Code Generation | No | Yes |
| Charts | Yes (ApexCharts) | Yes |
| Type-Safe Variants | Yes (CVA) | No |
| Free & Open Source | Yes (MIT) | Partial |
| Components | 80 | 50+ |
| Customization | Full Control | Limited |
| Current Status | v0.3.6 (0.4.0 is the current stable) | Commercial |
## Blazorise
Blazorise is a feature-rich component library that supports multiple CSS frameworks (Bootstrap, Material, Bulma) and offers one of the largest component collections for Blazor.
ShellUI focuses on Tailwind CSS exclusively, which provides a more consistent and modern styling approach. While Blazorise offers more CSS framework options, ShellUI's CLI-first approach gives you complete component ownership. If you need support for multiple CSS frameworks or want the largest component library, Blazorise might be preferable. ShellUI is better if you want Tailwind CSS, component ownership, and a simpler setup process.
### Feature Table
| Feature | ShellUI | Blazorise |
|---------|---------|-----------|
| Installation Method | CLI + NuGet | NuGet |
| Component Ownership | Yes | No |
| Tailwind CSS | Yes (v4.3.2) | No (Bootstrap/Material/Bulma) |
| CSS Framework Support | Tailwind Only | Multiple |
| Charts | Yes (ApexCharts) | Yes (ChartJS) |
| Type-Safe Variants | Yes (CVA) | No |
| Free & Open Source | Yes (MIT) | Yes (MIT) |
| Components | 80 | 80+ |
| Customization | Full Control | Limited |
| Current Status | v0.3.6 (0.4.0 is the current stable) | Mature |
## Summary
### When to Choose ShellUI
ShellUI is ideal if you:
- Want full control over component code
- Prefer Tailwind CSS styling
- Need a CLI-first workflow
- Want to avoid Node.js dependencies
- Plan to heavily customize components
- Need type-safe, accessible components
- Want data visualization with ApexCharts integration
- Prefer open-source solutions
### When to Choose Alternatives
**MudBlazor** if you:
- Prefer Bootstrap styling
- Need a mature, battle-tested library
- Want extensive community support
- Are comfortable with package-based workflows
**Radzen** if you:
- Want visual component designer
- Need rapid prototyping tools
- Are willing to pay for premium features
- Prefer code generation approach
**Blazorise** if you:
- Need multiple CSS framework support
- Want the largest component library
- Are building admin dashboards
- Need commercial support options
## Getting Started
Ready to try ShellUI? Get started with our [Quickstart Guide](https://shellui.dev/docs/v0.3/quickstart.md) or [Installation Guide](https://shellui.dev/docs/v0.3/installation.md).
---
# AI Agents
> Point Claude Code, Cursor, Copilot and other coding agents at the ShellUI docs, so they use its components instead of writing their own.
Source: https://shellui.dev/docs/v0.3/ai-agents
ShellUI publishes these docs for AI coding agents in the [llms.txt](https://llmstxt.org) format. An agent that reads them knows which components exist, how to install one with `shellui add`, and how each one is used, so it doesn't write its own versions.
> **Use the v0.3 files on 0.3**
>
> The bare `/llms.txt` and `/agents/` files describe the current stable release, 0.4. On 0.3.6, point your agent at the `/docs/v0.3/` URLs on this page.
## Set up your project
Coding agents read an instructions file in the project root at the start of every session. Add ShellUI's rules to the one your agent reads: they tell it to use ShellUI's components, check what's installed, and run `shellui add` for anything missing, and they link these docs. Each file is a `## ShellUI` section, so the commands append it to a file you already have, or create the file.
**Claude Code**
Claude Code reads `CLAUDE.md`. [Download CLAUDE.md](https://shellui.dev/docs/v0.3/agents/CLAUDE.md), or run this in the project root:
```bash
curl -fsSL https://shellui.dev/docs/v0.3/agents/CLAUDE.md >> CLAUDE.md
```
**Cursor**
Cursor reads rules from `.cursor/rules`. [Download shellui.mdc](https://shellui.dev/docs/v0.3/agents/shellui.mdc) into that folder, or run this in the project root:
```bash
curl -fsSL --create-dirs -o .cursor/rules/shellui.mdc https://shellui.dev/docs/v0.3/agents/shellui.mdc
```
**GitHub Copilot**
Copilot reads `.github/copilot-instructions.md`. [Download copilot-instructions.md](https://shellui.dev/docs/v0.3/agents/copilot-instructions.md) into `.github`, or run this in the project root:
```bash
mkdir -p .github && curl -fsSL https://shellui.dev/docs/v0.3/agents/copilot-instructions.md >> .github/copilot-instructions.md
```
**Other agents**
Codex and many other agents read `AGENTS.md`. [Download AGENTS.md](https://shellui.dev/docs/v0.3/agents/AGENTS.md), or run this in the project root:
```bash
curl -fsSL https://shellui.dev/docs/v0.3/agents/AGENTS.md >> AGENTS.md
```
The file is for ShellUI v0.3. When you upgrade, replace its `## ShellUI` section with the one for the new version.
## Or ask the agent
Paste this into your agent to have it read the docs and set up the instructions file itself:
```text
Read https://shellui.dev/docs/v0.3/llms.txt and follow its rules in this project.
Then add the ShellUI section from https://shellui.dev/docs/v0.3/agents/AGENTS.md
to the instructions file you read at startup (AGENTS.md, CLAUDE.md or
.github/copilot-instructions.md), creating it if it doesn't exist.
```
For a one-off task, give it the docs with the task:
```text
Read https://shellui.dev/docs/v0.3/llms.txt, then add a settings page with a form.
```
## What agents can read
| URL | Contents |
|-----|----------|
| [`/docs/v0.3/llms.txt`](https://shellui.dev/docs/v0.3/llms.txt) | Rules for agents, then every page of these docs with a one-line description and, for components, the `shellui add` command |
| [`/docs/v0.3/llms-full.txt`](https://shellui.dev/docs/v0.3/llms-full.txt) | The rules and every page as Markdown in one file, examples included |
| Any page + `.md` | One page as Markdown, for example [`/docs/v0.3/components/form/button.md`](https://shellui.dev/docs/v0.3/components/form/button.md) |
| [`/llms.txt`](https://shellui.dev/llms.txt), [`/llms-full.txt`](https://shellui.dev/llms-full.txt) | The same for the current stable release (0.4) |
Every page also has a ⋯ menu next to its title: **Copy page** copies its Markdown, **View as Markdown** opens it, and **Open in Claude** and **Open in ChatGPT** start a chat that reads it.
## What the rules say
- Look for an existing ShellUI component before building any UI element.
- Check `shellui.json` (or `shellui list --installed`) for what the project has, and run `shellui add ` for what it doesn't. Never recreate a ShellUI component or port one from shadcn/ui.
- Tell CLI projects (source in `Components/UI`) from NuGet projects (`@using ShellUI.Components`).
- Give components an interactive render mode, follow each page's API reference, and style with the theme tokens so dark mode works.
---
# Dashboard Layout
> Add the ShellUI dashboard (sidebar, header, breadcrumb, theme toggle) and make it your app's layout
Source: https://shellui.dev/docs/v0.3/dashboard
ShellUI ships two dashboard layouts, each a sidebar plus a content area with a header, breadcrumb and theme toggle:
| Block | Header | Install |
|-------|--------|---------|
| `dashboard-02` | Sticky: stays at the top while the page scrolls | `shellui add dashboard-02` |
| `dashboard-01` | Scrolls with the content | `shellui add dashboard-01` |
In 0.3, `shellui add` installs the files. You then make the dashboard your app's layout, which takes a few steps, all below. The examples use `dashboard-02`; for `dashboard-01`, use `DashboardLayout01` instead.
## 1. Install
From your project root, after `shellui init`:
```bash
shellui add dashboard-02
```
This adds:
| File | What it is |
|------|------------|
| `Components/Layout/DashboardLayout02.razor` | The layout: sidebar, header, breadcrumb, theme toggle |
| `Components/UI/AppSidebar.razor` | Your app's sidebar: brand, navigation links, user menu |
| `Components/UI/Sidebar*.razor`, `SidebarProvider.razor` | The sidebar building blocks |
| `Components/UI/Breadcrumb*.razor`, `Separator.razor`, `ThemeToggle.razor`, `Avatar.razor` | Header and sidebar parts |
The sidebar needs an interactive render mode and `shellui.js`; `shellui init` already set up both in `App.razor`.
## 2. Make it the default layout
Open `Components/Routes.razor` and change `DefaultLayout`:
```razor
```
With ASP.NET Core Identity (`--auth Individual`), the element is ``; change its `DefaultLayout` the same way.
> **Only some pages?**
>
> Leave `Routes.razor` alone and add a `@layout` directive to the pages that should use the dashboard:
>
> ```razor
> @page "/reports"
> @layout Layout.DashboardLayout02
> ```
## 3. Point the sidebar at your pages
`AppSidebar.razor` ships with placeholder links (`/`, `/dashboard`, `/settings`), a placeholder brand ("My App") and a placeholder user. Edit them to match your app.
In `Components/UI/AppSidebar.razor`, find the `Navigation` group and replace the `` entries inside its ``. For the pages in a new Blazor project:
```razor
NavigationHomeCounterWeather
```
> **Edit the file, don't replace it**
>
> Keep the rest of `AppSidebar.razor`: the header, the footer, and the `@code` block at the bottom, which defines `IsCurrentPath`. Replacing the whole file with this snippet fails the build with "The name 'IsCurrentPath' does not exist in the current context".
Keep an icon inside each button if you want one; the placeholders show inline SVGs. `IsCurrentPath` highlights the link of the current page. Remove the Settings entry if you have no settings page.
## 4. Remove the old layout (optional)
After step 2, the template's `MainLayout` is no longer used. You can delete these from `Components/Layout/`:
- `MainLayout.razor` and `MainLayout.razor.css`
- `NavMenu.razor` and `NavMenu.razor.css`
Keep `ReconnectModal.*` (.NET 10). Before deleting, do these two things, or the build or the error bar will break.
**Pages that name `MainLayout`.** The .NET 10 template's `Components/Pages/NotFound.razor` has `@layout MainLayout`, and Identity's `Components/Account/Shared/ManageLayout.razor` does too. Change them to the dashboard:
```razor
@layout DashboardLayout02
```
**The error bar.** `MainLayout.razor` contains Blazor's error bar (`
`). Move it into `Components/App.razor`, just before ``. Its old styles were in `MainLayout.razor.css`, so use this Tailwind-styled version:
```html
```
It stays hidden until Blazor shows it after an error.
## 5. Run it
```bash
dotnet watch
```
Your pages now render inside the dashboard. On desktop, **Ctrl+B** (**⌘B** on macOS) collapses and expands the sidebar; on small screens, the menu button in the header opens it.
> **JSDisconnectedException in the terminal?**
>
> With the 0.3.2 CLI, every page reload or closed tab logged `Microsoft.JSInterop.JSDisconnectedException` from `SidebarProvider.DisposeAsync`. It was harmless, and 0.3.3 fixes it: update the tool and run `shellui update sidebar-provider`. Or keep your file and add a second `catch` in `DisposeAsync`:
>
> ```csharp
> try { await JSRuntime.InvokeVoidAsync("ShellUI.disposeSidebar", _handle); }
> catch (JSException) { }
> catch (JSDisconnectedException) { }
> ```
> **Template sample pages**
>
> `shellui init` removes Bootstrap, so the template's Counter, Weather and Error pages lose their Bootstrap styling. Style them with Tailwind or ShellUI components, for example `