# 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.4.0. Other versions: [v0.3.6](https://shellui.dev/docs/v0.3/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.4/introduction Welcome to ShellUI v0.4.0, the current stable release of the CLI-first Blazor component library inspired by shadcn/ui. Compared with 0.3 it adds 19 components and three sign-in page blocks (98 install targets in all), compositional parts for eight more components, `shellui add all`, `doctor` and `migrate`, and .NET 8 and 9 support for both the CLI and the NuGet package. v0.4.0 stable 98 install targets .NET 8, 9 & 10 tweakcn themes > The CLI runs on .NET 8 or later and works in Blazor projects on .NET 8, 9 and 10. The `ShellUI.Components` NuGet package targets .NET 8, 9 and 10. Still on 0.3? See the [v0.3 docs](https://shellui.dev/docs/v0.3/introduction.md) and [upgrading from 0.3](https://shellui.dev/docs/v0.4/release-notes.md#upgrading-from-0.3). ## Getting Started ### Installation Choose your preferred installation method: **CLI Installation (Recommended)** ```bash dotnet tool install -g ShellUI.CLI # Or upgrade an existing install dotnet tool update -g ShellUI.CLI # 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 ``` 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.4/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.4/components/form.md): Buttons, inputs, selects, and form controls - [Layout Components](https://shellui.dev/docs/v0.4/components/layout.md): Cards, dialogs, sheets, and structural elements - [Navigation Components](https://shellui.dev/docs/v0.4/components/navigation.md): Menus, breadcrumbs, tabs, and navigation elements - [Interactive Components](https://shellui.dev/docs/v0.4/components/interactive.md): Dropdowns, tooltips, and interactive elements - [Advanced Components](https://shellui.dev/docs/v0.4/components/advanced.md): Calendars, charts, carousels, steppers, and complex UI elements ## What's New in v0.4.0 The 0.4 line is stable. Since 0.4.0-alpha.3: - **Six components for AI and app UIs:** [Prompt Suggestions](https://shellui.dev/docs/v0.4/components/advanced/prompt-suggestions.md), [Reasoning](https://shellui.dev/docs/v0.4/components/advanced/reasoning.md), [Tool Call](https://shellui.dev/docs/v0.4/components/advanced/tool-call.md), [Field](https://shellui.dev/docs/v0.4/components/form/field.md), [JSON Viewer](https://shellui.dev/docs/v0.4/components/data-display/json-viewer.md), and a real [Resizable](https://shellui.dev/docs/v0.4/components/layout/resizable.md) panel group you can drag or move with the keyboard. - **`shellui add all`** installs the whole library (`--except` leaves components out), **`shellui doctor`** checks a project's setup, and **`shellui migrate`** rewrites your pages after a template API change. See the [CLI guide](https://shellui.dev/docs/v0.4/installation/cli.md). - **.NET 8 and 9:** the CLI runs on .NET 8 or later, and the `ShellUI.Components` package targets .NET 8, 9 and 10. - **`SonnerService.Clear()`** and **destructive [context menu](https://shellui.dev/docs/v0.4/components/interactive/context-menu.md) items.** - **Fixes:** `add` no longer hangs on .NET 8 and 9 apps, `doctor` no longer calls a fresh `app.css` stale, `list` counts correctly, and the package safelist has the 198 classes it was missing. Everything in 0.3.5 and 0.3.6 is included. See the [release notes](https://shellui.dev/docs/v0.4/release-notes.md). ## What's New in v0.4.0-alpha.3 - **`Class` wins over a component's own classes:** `` replaces the card's `max-w-md` instead of competing with it, so the `!` modifier is no longer needed. See [Theming](https://shellui.dev/docs/v0.4/theming.md#per-component-changes). - **Focus stays inside open overlays:** Dialog, Alert Dialog, Sheet and Drawer keep Tab inside while open and return focus when they close. - **`shellui add` never downgrades a NuGet package** your project already has at the same or a newer version. - **Razor class libraries:** `init` sets up a library shared by several apps. See [Razor Class Library](https://shellui.dev/docs/v0.4/installation/razor-class-library.md). - **The CLI templates match the NuGet package,** fixing RadioGroup, ScrollArea, DatePicker, TimePicker, Sheet and Drawer, among others. After `shellui update`, `InputVariant` and the Stepper parts change: see the [release notes](https://shellui.dev/docs/v0.4/release-notes.md). ## What's New in v0.4.0-alpha.2 - **One Tailwind CLI per machine:** the standalone Tailwind CLI is downloaded once into `~/.shellui/bin` and shared by every project, so a new project is about 130 KB instead of 112 MB, and later projects set up offline. The download resumes over slow connections, and if it fails `init` still finishes. - **`shellui update` keeps your changes** and installs new dependencies, so a project updated from 0.3 builds. **`shellui remove`** handles layouts and custom component paths. - **Fixes:** dark mode sets `color-scheme` for the browser's own controls, and the NuGet package's `TimePicker` shows its value. Everything in 0.3.3 and 0.3.4 is included. See the [release notes](https://shellui.dev/docs/v0.4/release-notes.md). ## What's New in v0.4.0-alpha.1 - **14 new components:** [Kbd](https://shellui.dev/docs/v0.4/components/data-display/kbd.md), [Aspect Ratio](https://shellui.dev/docs/v0.4/components/layout/aspect-ratio.md), [Button Group](https://shellui.dev/docs/v0.4/components/form/button-group.md), [Toggle Group](https://shellui.dev/docs/v0.4/components/form/toggle-group.md), [Input Group](https://shellui.dev/docs/v0.4/components/form/input-group.md), [Number Input](https://shellui.dev/docs/v0.4/components/form/number-input.md), [Stat Card](https://shellui.dev/docs/v0.4/components/data-display/stat-card.md), [Timeline](https://shellui.dev/docs/v0.4/components/data-display/timeline.md), [Tree View](https://shellui.dev/docs/v0.4/components/data-display/tree-view.md), [QR Code](https://shellui.dev/docs/v0.4/components/data-display/qr-code.md), [Image Viewer](https://shellui.dev/docs/v0.4/components/advanced/image-viewer.md) and [Chat](https://shellui.dev/docs/v0.4/components/advanced/chat.md) with its message and input parts. - **Compositional parts** for [Alert Dialog](https://shellui.dev/docs/v0.4/components/advanced/alert-dialog.md), [Breadcrumb](https://shellui.dev/docs/v0.4/components/layout/breadcrumb.md), [Command](https://shellui.dev/docs/v0.4/components/advanced/command.md), [Form](https://shellui.dev/docs/v0.4/components/form/form.md), [Menubar](https://shellui.dev/docs/v0.4/components/navigation/menubar.md), [Pagination](https://shellui.dev/docs/v0.4/components/navigation/pagination.md), [Sheet](https://shellui.dev/docs/v0.4/components/layout/sheet.md) and [Drawer](https://shellui.dev/docs/v0.4/components/layout/drawer.md). Each mode is opt-in, so existing markup keeps working. - **Dashboard setup in `init`:** `shellui init --dashboard 02` makes the dashboard your app's layout, builds the sidebar links from your pages, and removes the template's layout when you haven't changed it. See the [dashboard guide](https://shellui.dev/docs/v0.4/dashboard.md), and try the layouts on the [Blocks page](https://shellui.dev/blocks). - **ASP.NET Core Identity:** apps created with `--auth Individual` work after `init`, the sidebar shows the signed-in user, and the `auth-01`, `auth-02` and `auth-03` blocks restyle the sign-in pages. See the [authentication guide](https://shellui.dev/docs/v0.4/authentication.md). - **[Loading](https://shellui.dev/docs/v0.4/components/data-display/loading.md)** has 23 variants, and **Command** and **Command Palette** filter as you type, support the arrow keys and run each item's `Action`. - **One breaking change:** `Calendar.SelectedDateChanged` is now `EventCallback`. See the [release notes](https://shellui.dev/docs/v0.4/release-notes.md) for the full list and how to upgrade from 0.3. ## Key Features - **CLI-First**: Copy components directly to your codebase for full control - **Hybrid Workflow**: CLI + NuGet packages for maximum flexibility - **Tailwind CSS v4.3.2**: Modern styling with standalone CLI (no Node.js required) - **Production-Ready Components**: Comprehensive component library - **Type-Safe Variants**: CVA patterns with full C# type safety - **Accessible**: WCAG 2.1 AA compliant by default - **Performance Optimized**: Built for both Server and WASM scenarios - **Customizable**: Easy theme customization with CSS variables ## Architecture ShellUI offers a unique hybrid approach: - **Copy Components**: Like shadcn/ui, components are copied to your project - **NuGet Option**: Traditional package installation for quick starts - **Tailwind Integration**: Standalone CLI or npm setup options - **Build Integration**: Automatic CSS compilation on project build ## Theming Customize your theme instantly with [tweakcn](https://tweakcn.com) or modify CSS variables: ```css :root { --background: oklch(0.9900 0 0); --foreground: oklch(0 0 0); --primary: oklch(0 0 0); --primary-foreground: oklch(1 0 0); --secondary: oklch(0.9400 0 0); --secondary-foreground: oklch(0 0 0); /* ... more variables */ } ``` ## Learn More - [GitHub Repository](https://github.com/shellui-dev/shellui) - [Installation Guide](https://shellui.dev/docs/v0.4/installation.md) - [Component API](https://shellui.dev/docs/v0.4/components.md) - [Theming Guide](https://shellui.dev/docs/v0.4/theming.md) - [Contributing](https://shellui.dev/docs/v0.4/contributing.md) --- # Quickstart > Get started with ShellUI in minutes Source: https://shellui.dev/docs/v0.4/quickstart Get up and running with ShellUI v0.4.0 in just a few minutes. This guide will walk you through installing and using your first components from our growing component library. ## Prerequisites - .NET 8 SDK or later, and a Blazor project on .NET 8, 9 or 10 - A Blazor project (Server, WebAssembly, or Hybrid) ## Installation ShellUI 0.4 offers a **hybrid workflow** - use CLI for customization, NuGet for speed: ### Option 1: CLI Tool (Recommended for Customization) ```bash # Install CLI globally (one-time) dotnet tool install -g ShellUI.CLI # Initialize in your Blazor project (choose npm or standalone, and a dashboard layout if you want one) shellui init # Add components directly to your codebase shellui add button input card dialog # List all available components shellui list ``` ### Option 2: NuGet Package (Quick Start) ```bash # Install components package dotnet add package ShellUI.Components # Manual Tailwind CSS v4.3.2 setup required # See installation guide for details ``` **Why choose CLI?** Components are copied to your project for full control and customization. ## Your First Component Let's create a simple button and card combination: ```razor @page "/"

Welcome to ShellUI

Your first ShellUI components

@code { private void HandleClick(MouseEventArgs args) { // Your logic here } } ``` ## Add Charts Build data-rich dashboards with ApexCharts-powered chart components: ```bash shellui add chart bar-chart line-chart pie-chart dotnet add package Blazor-ApexCharts ``` ```razor @page "/dashboard" @code { private List salesData = new() { new("Jan", 12000), new("Feb", 19000), new("Mar", 15000), new("Apr", 25000) }; record SalesData(string Month, decimal Revenue); } ``` ## What's Next? - [Installation Guide](https://shellui.dev/docs/v0.4/installation.md) - Detailed setup instructions - [Dashboard Layout](https://shellui.dev/docs/v0.4/dashboard.md) - A sidebar layout set up by `shellui init --dashboard 02` - [Authentication](https://shellui.dev/docs/v0.4/authentication.md) - ASP.NET Core Identity apps and the sign-in page blocks - [Browse Components](https://shellui.dev/docs/v0.4/components.md) - Explore all available components - [Charts](https://shellui.dev/docs/v0.4/components/advanced/charts.md) - Data visualization with ApexCharts - [Comparison](https://shellui.dev/docs/v0.4/comparison.md) - See how ShellUI compares to other libraries --- # Installation > Install ShellUI via CLI or NuGet package Source: https://shellui.dev/docs/v0.4/installation ShellUI 0.4 offers a **hybrid workflow** with two installation methods. Choose the approach that fits your project. These pages cover 0.4.0, the current stable release, which `dotnet tool install` and `dotnet add package` install by default. For 0.3, see the [v0.3 docs](https://shellui.dev/docs/v0.3/installation.md). ## Prerequisites - **.NET 8 SDK or later** to run the CLI; your Blazor project can target **.NET 8, 9 or 10** with the CLI or the NuGet package - **Node.js** (optional — only needed if using npm for Tailwind) - A **Blazor project** (Server, WebAssembly, Hybrid, or Interactive Server) --- ## Installation Methods - [CLI Installation (Recommended)](https://shellui.dev/docs/v0.4/installation/cli.md): Copy components directly into your project for full ownership and customization. Automatic Tailwind setup, MSBuild integration, and component management. - [NuGet Package](https://shellui.dev/docs/v0.4/installation/nuget.md): Traditional package install for quick prototyping. Pre-compiled components with manual Tailwind CSS setup. --- ## CLI vs NuGet — Which to Choose? | Aspect | CLI Tool | NuGet Package | |--------|----------|---------------| | **Install command** | `shellui add button card` | `dotnet add package ShellUI.Components` | | **Components** | Source copied to your project | Pre-compiled, referenced as package | | **Customization** | Full source code access — edit anything | Override via CSS, limited code changes | | **Tailwind setup** | Automatic via `shellui init` | Manual setup required | | **Bundle size** | Only components you add | All components included | | **Updates** | `shellui update`, then `shellui migrate` | Bump package version | | **Best for** | Production apps, full customization | Prototyping, quick starts | > **Pick one per project.** The package and the CLI define the same component names, so using both makes those names ambiguous (`shellui doctor` warns about it). Start with the package if you like, and move to the CLI when you need to change a component's source. --- ## Quick Start The fastest way to get started with ShellUI: ```bash # 1. Install the CLI tool dotnet tool install -g ShellUI.CLI # 2. Initialize in your Blazor project cd your-blazor-project shellui init # 3. Add components shellui add button input card dialog # 4. Run your app dotnet run ``` `shellui init` also offers to set up a [dashboard layout](https://shellui.dev/docs/v0.4/dashboard.md); pass `--dashboard 02` to choose one without the prompt. That's it — `shellui init` handles Tailwind CSS setup, Bootstrap cleanup, folder creation, and MSBuild integration automatically. [View full CLI guide](https://shellui.dev/docs/v0.4/installation/cli.md) | [View full NuGet guide](https://shellui.dev/docs/v0.4/installation/nuget.md) --- ## Project Types ShellUI works with all Blazor hosting models: **Blazor Server** ```bash dotnet new blazorserver -n MyApp cd MyApp shellui init shellui add button card input dotnet run ``` **Blazor WebAssembly** ```bash dotnet new blazorwasm -n MyApp cd MyApp shellui init shellui add button card input dotnet run ``` **Blazor Hybrid** Works with MAUI, WPF, and WinForms Blazor Hybrid apps. ```bash dotnet new maui-blazor -n MyApp cd MyApp shellui init shellui add button card input dotnet run ``` **Interactive Server** Supports Blazor's Interactive Server rendering mode. ```bash dotnet new blazor -n MyApp cd MyApp shellui init shellui add button card input dotnet run ``` --- ## Verification After installation, verify everything is working: 1. **Build** your project: `dotnet build` 2. **Check** that `wwwroot/app.css` was generated 3. **Run** the project: `dotnet run` ### Quick Test ```razor @page "/test" @using YourProject.Components.UI
``` If the buttons render with proper styling, your installation is successful. --- ## Getting Help - [GitHub Issues](https://github.com/shellui-dev/shellui/issues) — Report bugs or request features - [Documentation](https://shellui.dev/docs/v0.4/introduction.md) — Full ShellUI docs - [Community Discussions](https://github.com/shellui-dev/shellui/discussions) — Ask questions --- # CLI Installation > Install ShellUI via the CLI tool for full component ownership and automatic Tailwind setup Source: https://shellui.dev/docs/v0.4/installation/cli The ShellUI CLI copies component source files directly into your project, giving you **full ownership and customization control**. It also handles Tailwind CSS setup, Bootstrap cleanup, folder creation, and MSBuild integration automatically. The CLI runs on .NET 8 or later and sets up Blazor projects on .NET 8, 9 and 10. (The 0.3 line and the 0.4 prereleases needed the .NET 10 runtime.) ## Install the CLI Tool **Global Install** ### Global Installation Global installation makes the `shellui` command available system-wide. **Best for individual developers, quick prototyping, and personal projects.** ```bash # Install globally dotnet tool install -g ShellUI.CLI ``` After installation, use the CLI without the `dotnet` prefix: ```bash shellui init shellui add button input card shellui list ``` **Local Install (Teams)** ### Local Tool Installation Local installation locks the CLI version per-project and shares it via source control. **Best for teams, CI/CD pipelines, and enterprise projects.** ```bash # Step 1: Create a tool manifest (one-time, in project root) dotnet new tool-manifest # Step 2: Install as a local tool dotnet tool install ShellUI.CLI ``` This creates a `.config/dotnet-tools.json` file — commit it to source control: ```json { "version": 1, "isRoot": true, "tools": { "shellui.cli": { "version": "0.4.0", "commands": ["shellui"] } } } ``` Local tools require the `dotnet` prefix: ```bash dotnet shellui init dotnet shellui add button input card dotnet shellui list ``` > **Team onboarding:** New team members just run `dotnet tool restore` to get the exact same CLI version. ### Global vs Local — When to Use Which | Aspect | Global (`-g`) | Local (manifest) | |--------|--------------|------------------| | **Command** | `shellui init` | `dotnet shellui init` | | **Install location** | User profile | Project directory | | **Sharing** | Each dev installs separately | Auto-restored via manifest | | **Version lock** | Latest (unless pinned) | Locked in manifest file | | **CI/CD** | Requires explicit install step | `dotnet tool restore` | | **Best for** | Individual developers | Teams & CI/CD | --- ## Initialize Your Project Navigate to your Blazor project directory and run init: **Global** ```bash cd your-blazor-project shellui init ``` **Local** ```bash cd your-blazor-project dotnet shellui init ``` The init command will: 1. **Detect** your Blazor project type (Server, WASM, Hybrid, etc.) 2. **Clean up** the template's Bootstrap files and restyle its sample pages (Home, Counter, Weather, Error, NotFound) with Tailwind, when you haven't edited them 3. **Set up Tailwind CSS**: choose between standalone CLI (no Node.js) or npm 4. **Download** the Tailwind CSS v4.3.2 standalone CLI once per machine into `~/.shellui/bin` (if selected). Later projects reuse it, even offline 5. **Create** component folders, config files, and CSS entry point 6. **Configure** MSBuild integration for automatic Tailwind compilation 7. **Offer a dashboard layout**: sticky header (`dashboard-02`), scrolling header (`dashboard-01`), or none. See the [dashboard guide](https://shellui.dev/docs/v0.4/dashboard.md) Choose your Tailwind CSS setup method when prompted: - **Standalone CLI** (recommended): No Node.js required, uses Tailwind v4.3.2 - **npm**: Traditional setup with Node.js, uses tailwindcss@^4.3.2 In an app created with `--auth Individual`, `init` also keeps the `/Account` pages working. See [Authentication](https://shellui.dev/docs/v0.4/authentication.md). ### Options | Option | What it does | |--------|--------------| | `--yes` | No prompts. Uses standalone Tailwind and adds no dashboard unless the options below say otherwise | | `--tailwind ` | `standalone` or `npm`. Picks the Tailwind setup and skips that prompt | | `--dashboard ` | `01`, `02` or `none`. Sets up a dashboard layout, or skips it, without asking | | `--replace-layout` | Lets the dashboard replace a layout you have customized | | `--style