# 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 ShellUI Build 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, `` lists) in the matching theme. The theme `shellui init` and `shellui theme apply` write includes it from 0.3.4; in an older `input.css`, add the two lines yourself. Let users switch with [ThemeToggle](https://shellui.dev/docs/v0.3/components/interactive/theme-toggle.md): ```razor ``` ## Charts Chart containers use `--radius`, `--shadow`, `--border`, `--card` and `--card-foreground`, so they match your theme. The series colors come from the `ChartTheme` enum: `Default`, `Colorful` or `Monochrome`. See [Charts](https://shellui.dev/docs/v0.3/components/advanced/charts.md). ## Fonts ShellUI reads `--font-sans` and `--font-mono`. Load a font, then point the variables at it: ```html ``` ```css :root { --font-sans: 'Inter', sans-serif; } ``` ## Per-component changes Every component accepts `Class`, which is merged with its default classes. From 0.3.5, your classes win: when one of yours sets the same CSS property as a default class under the same variants, the default is dropped, like tailwind-merge. `` replaces the card's `max-w-md`, and `p-4` replaces `px-2`. Classes that don't conflict (a text colour and a text size, say) are both kept, and classes ShellUI doesn't recognise pass through. You no longer need Tailwind's `!` modifier to beat a default. In a CLI project, `shellui update shell` brings in the new merge. ```razor ... ``` When you install with the CLI, you own the component source in `Components/UI/` and can change anything. --- # Components > Browse all ShellUI 0.3 components organized by category Source: https://shellui.dev/docs/v0.3/components Explore the ShellUI 0.3 component library, organized by category. Each component is fully accessible, type-safe, and customizable via the CLI. ## Component Categories - [Form Components](https://shellui.dev/docs/v0.3/components/form.md): Button, Input, Textarea, Select, Checkbox, RadioGroup, Switch, Toggle, Label, Slider - [Data Display](https://shellui.dev/docs/v0.3/components/data-display.md): Table, Badge, Avatar, Alert, Toast, Skeleton, Progress, Loading - [Layout Components](https://shellui.dev/docs/v0.3/components/layout.md): Card, Dialog, Sheet, Drawer, Popover, Tooltip, Separator, Collapsible, Accordion - [Navigation Components](https://shellui.dev/docs/v0.3/components/navigation.md): Navbar, NavigationMenu, Pagination, Tabs, Breadcrumb - [Interactive Components](https://shellui.dev/docs/v0.3/components/interactive.md): Dropdown, ContextMenu, HoverCard, ThemeToggle, EmptyState - [Advanced Components](https://shellui.dev/docs/v0.3/components/advanced.md): Calendar, DatePicker, Combobox, AlertDialog, Carousel, Stepper, Callout, Sonner, Charts ## What's New in v0.3.0 - **Compositional APIs**: Select, Dropdown, Popover, HoverCard, ContextMenu, NavigationMenu, Carousel, Tabs, Accordion, Collapsible, Drawer and Sheet all have subcomponent patterns, and `shellui add` installs the subcomponents with their parent - **New components**: Callout, CopyButton, LinkCard, PrevNextNav, Sonner, Stepper - **Also new**: [Command Palette](https://shellui.dev/docs/v0.3/components/advanced/command-palette.md), [Data Picker](https://shellui.dev/docs/v0.3/components/form/data-picker.md), [Multi Select](https://shellui.dev/docs/v0.3/components/form/multi-select.md), [Tag Input](https://shellui.dev/docs/v0.3/components/form/tag-input.md), [Typed Select](https://shellui.dev/docs/v0.3/components/form/typed-select.md), and the [Donut](https://shellui.dev/docs/v0.3/components/advanced/charts/donut-chart.md), [Radar](https://shellui.dev/docs/v0.3/components/advanced/charts/radar-chart.md) and [Radial](https://shellui.dev/docs/v0.3/components/advanced/charts/radial-chart.md) charts - **Dependencies resolved for you**: `shellui add` installs sub-components, models, NuGet packages and `_Imports.razor` usings ## Getting Started ```bash dotnet tool install -g ShellUI.CLI --version 0.3.6 # Add components shellui add button input card drawer sheet # The newest components shellui add command-palette data-picker multi-select tag-input typed-select donut-chart radar-chart radial-chart ``` --- # Form Components > Form components for ShellUI 0.3 Source: https://shellui.dev/docs/v0.3/components/form Form components for building accessible, type-safe input controls. - [Button](https://shellui.dev/docs/v0.3/components/form/button.md): Flexible button with variants, sizes, and loading state - [Checkbox](https://shellui.dev/docs/v0.3/components/form/checkbox.md): Accessible checkbox input - [Form](https://shellui.dev/docs/v0.3/components/form/form.md): Form wrapper with EditContext and validation - [Input](https://shellui.dev/docs/v0.3/components/form/input.md): Styled text input field - [Input OTP](https://shellui.dev/docs/v0.3/components/form/input-otp.md): One-time password input fields - [Label](https://shellui.dev/docs/v0.3/components/form/label.md): Accessible form label - [Radio Group](https://shellui.dev/docs/v0.3/components/form/radio-group.md): Group of radio button inputs - [Select](https://shellui.dev/docs/v0.3/components/form/select.md): Dropdown select input - [Slider](https://shellui.dev/docs/v0.3/components/form/slider.md): Range slider input - [Switch](https://shellui.dev/docs/v0.3/components/form/switch.md): Toggle switch input - [Textarea](https://shellui.dev/docs/v0.3/components/form/textarea.md): Multi-line text input - [Toggle](https://shellui.dev/docs/v0.3/components/form/toggle.md): Pressable toggle button - [Typed Select · New](https://shellui.dev/docs/v0.3/components/form/typed-select.md): Native select bound to a typed value: enums, numbers, Guids, bools or strings - [Data Picker · New](https://shellui.dev/docs/v0.3/components/form/data-picker.md): Searchable single-select for objects, with custom templates - [Multi Select · New](https://shellui.dev/docs/v0.3/components/form/multi-select.md): Searchable multi-select for objects, shown as chips - [Tag Input · New](https://shellui.dev/docs/v0.3/components/form/tag-input.md): Free-text tags with keyboard and paste support --- # Button > Interactive button component with type-safe variants, sizes, and loading state. Source: https://shellui.dev/docs/v0.3/components/form/button The Button component provides a flexible, accessible button for Blazor applications with enum-based variants and sizes following shadcn/ui patterns. ## Installation ```bash shellui add button ``` ## Usage ### Basic ```razor ``` ### Variants ```razor ``` ### Sizes ```razor ``` ### Loading and Disabled ```razor ``` ### With Icon ```razor ``` ### Event Handling ```razor @code { private void HandleClick(MouseEventArgs args) { // Handle button click } } ``` ## API Reference | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `Variant` | `ButtonVariant` | `Default` | Visual style: `Default`, `Secondary`, `Destructive`, `Outline`, `Ghost`, `Link` | | `Size` | `ButtonSize` | `Default` | Button size: `Default`, `Sm`, `Lg`, `Icon` | | `Type` | `string` | `"button"` | HTML button type attribute | | `Class` | `string?` | `null` | Additional CSS classes | | `Disabled` | `bool` | `false` | Disables the button | | `IsLoading` | `bool` | `false` | Shows loading spinner and disables interaction | | `OnClick` | `EventCallback` | — | Click event callback | | `ChildContent` | `RenderFragment` | `null` | Button content | ## Accessibility - Uses native ` @code { private FormModel model = new(); private void HandleSubmit() { } private class FormModel { public bool AcceptTerms { get; set; } public bool Subscribe { get; set; } } } ``` ## API Reference | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `Checked` | `bool` | `false` | Checked state | | `CheckedChanged` | `EventCallback` | — | Fires when checked state changes | | `Disabled` | `bool` | `false` | Disables the checkbox | | `Class` | `string?` | `null` | Additional CSS classes | ## Accessibility - Proper ARIA attributes (`role="checkbox"`, `aria-checked`) - Keyboard navigation support (Space to toggle) - Screen reader compatible --- # Data Picker > Searchable single-select for objects, with custom templates Source: https://shellui.dev/docs/v0.3/components/form/data-picker `DataPicker` picks one object from a list, with a search box. Unlike `Select`, the value is the item itself, not a string. ## Installation ```bash shellui add data-picker ``` ## Usage ```razor

Selected: @_selected?.Name

@code { private Person? _selected; } @code { private List _people = new() { new(1, "Ada Lovelace", "Engineering"), new(2, "Grace Hopper", "Engineering"), new(3, "Katherine Johnson", "Research"), }; record Person(int Id, string Name, string Team); } ``` ## Custom templates ```razor
@context.Name @context.Team
@code { private Person? _selected; private List _people = new() { new(1, "Ada Lovelace", "Engineering"), new(2, "Grace Hopper", "Compilers"), new(3, "Alan Turing", "Research"), }; record Person(int Id, string Name, string Team); } ``` ## API Reference | Property | Type | Default | Description | |----------|------|---------|-------------| | `TItem` | `Generic type` | — | The item type | | `TKey` | `Generic type` | — | The key type returned by `KeySelector` | | `Items` | `IEnumerable` | required | Items to choose from | | `Value` | `TItem?` | `default` | Selected item (supports `@bind-Value`) | | `ValueChanged` | `EventCallback` | — | Raised when the selection changes | | `KeySelector` | `Func` | required | Unique key for each item | | `DisplaySelector` | `Func?` | `null` | Text shown for an item (defaults to `ToString()`) | | `SearchPredicate` | `Func?` | `null` | Custom search match (defaults to a case-insensitive match on the display text) | | `SelectedTemplate` | `RenderFragment?` | `null` | Custom rendering of the selected item in the trigger | | `OptionTemplate` | `RenderFragment?` | `null` | Custom rendering for each option in the list | | `Placeholder` | `string` | `"Select..."` | Text shown when nothing is selected | | `SearchPlaceholder` | `string` | `"Search..."` | Placeholder of the search box | | `EmptyText` | `string` | `"No results found."` | Text shown when the search matches nothing | | `Disabled` | `bool` | `false` | Disables the control | | `CloseOnScroll` | `bool` | `false` | Close the list when the page scrolls | | `Class` | `string?` | `null` | Additional CSS classes | --- # Form > Form wrapper component with validation and submission handling. Source: https://shellui.dev/docs/v0.3/components/form/form The Form component provides a styled wrapper for forms with built-in support for Blazor validation and submission handling. ## Installation ```bash shellui add form ``` ## Usage ### Basic ```razor
@code { private string name = ""; private string email = ""; private void HandleSubmit() { } } ``` ### With Validation ```razor @using System.ComponentModel.DataAnnotations
@code { private LoginModel model = new(); private void HandleValid() { } private void HandleInvalid() { } private class LoginModel { [Required, EmailAddress] public string Email { get; set; } = ""; [Required, MinLength(8)] public string Password { get; set; } = ""; } } ``` ### Custom class ```razor
``` ## API Reference | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `ChildContent` | `RenderFragment` | `null` | Form content | | `OnValidSubmit` | `EventCallback` | — | Fires when form is valid on submit | | `OnInvalidSubmit` | `EventCallback` | — | Fires when form has validation errors | | `ClassName` | `string` | `"space-y-6"` | CSS classes for the form element | ## Accessibility - Uses semantic `
` element - Integrates with Blazor DataAnnotationsValidator - Proper form submission handling --- # Input > Text input field component with variant support and two-way binding. Source: https://shellui.dev/docs/v0.3/components/form/input The Input component provides a styled text input field with support for all standard HTML input types, two-way binding, and focus/blur events. ## Installation ```bash shellui add input ``` ## Usage ### Basic ```razor
``` ### Input Types ```razor
``` ### With Label ```razor
``` ### Two-way Binding ```razor
@code { private string email = ""; } ``` ### ValueChanged Callback ```razor
@code { private string email = ""; private void HandleEmailChanged(string value) { email = value; } } ``` ### Disabled and ReadOnly ```razor
``` ### Custom Class ```razor
@@
``` ## API Reference | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `Variant` | `InputVariant` | `Default` | Visual style variant | | `Type` | `string` | `"text"` | HTML input type attribute | | `Value` | `string` | `""` | Current input value | | `Placeholder` | `string` | `""` | Placeholder text | | `Disabled` | `bool` | `false` | Disables the input | | `ReadOnly` | `bool` | `false` | Makes input read-only | | `Class` | `string?` | `null` | Additional CSS classes | | `ValueChanged` | `EventCallback` | — | Fires when value changes | | `OnFocus` | `EventCallback` | — | Fires when input gains focus | | `OnBlur` | `EventCallback` | — | Fires when input loses focus | ## Accessibility - Proper label association via `For` / `Id` attributes - ARIA attributes for validation states - Keyboard navigation support - Screen reader compatible --- # Input OTP > One-time password input field with auto-focus and grouping. Source: https://shellui.dev/docs/v0.3/components/form/input-otp The InputOTP component provides a multi-digit input for one-time passwords and verification codes with auto-focus navigation. ## Installation ```bash shellui add input-otp ``` ## Usage ### Basic ```razor @code { private string otpCode = ""; private void HandleChanged(string value) { otpCode = value; } } ``` ### Two-way Binding ```razor @code { private string otpCode = ""; } ``` ### Custom Length ```razor @code { private string otpCode = ""; } ``` ### With Grouping Groups digits with a separator. For example, `Length="6"` and `GroupBy="3"` displays as `[1][2][3] - [4][5][6]`. ```razor @code { private string otpCode = ""; } ``` ### With Completion Handler ```razor @code { private string otpCode = ""; private void HandleComplete(string value) { // All digits entered — verify the code } } ``` ### With Label ```razor

We sent a code to your email

@code { private string code = ""; } ``` ### Disabled ```razor ``` ## API Reference | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `Value` | `string` | `""` | Current OTP value | | `ValueChanged` | `EventCallback` | — | Fires when value changes | | `OnComplete` | `EventCallback` | — | Fires when all digits are entered | | `Length` | `int` | `6` | Number of input digits | | `GroupBy` | `int` | `3` | Group digits with separator (0 to disable) | | `Disabled` | `bool` | `false` | Disables the input | | `Class` | `string?` | `null` | Additional CSS classes | ## Accessibility - Input attributes: `inputmode="numeric"`, `pattern="[0-9]*"` - Auto-focus advances to next input on digit entry - Backspace clears current and moves to previous - Arrow key navigation between inputs - Screen reader compatible --- # Label > Accessible form label component for input association. Source: https://shellui.dev/docs/v0.3/components/form/label The Label component provides accessible labels for form inputs with proper association and styling. ## Installation ```bash shellui add label ``` ## Usage ### Basic ```razor
``` ### With Input Association ```razor
``` ### With Checkbox ```razor
@code { private bool acceptTerms = false; } ``` ### With Switch ```razor
@code { private bool notificationsEnabled = false; } ``` ### Required Field Indicator ```razor
``` ## API Reference | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `For` | `string` | `""` | Associates label with an input via `id` | | `ChildContent` | `RenderFragment` | `null` | Label text content | ## Accessibility - Uses semantic `