# NeoUI — Complete Documentation
# Generated: 2026-04-07T11:37:24Z
# Base URL: https://neoui.io

==================================================================


==================================================================
FILE: getting-started.txt
URL:  https://neoui.io/llms/getting-started.txt
==================================================================

# NeoUI -- Getting Started

NeoUI is a production-ready Blazor component library inspired by shadcn/ui. It ships 100+ accessible,
customizable components built for .NET 10 with InteractiveAuto render mode support.

## Fastest Start -- Project Template

```bash
dotnet new install NeoUI.Blazor.Templates
dotnet new neoui -n MyApp
cd MyApp && dotnet run
```

Supports three interactivity modes via `-in` / `--interactivity`:
  -in Server -- Blazor Server (single project)
  -in WebAssembly  -- Blazor WASM (single project)
  -in Auto-- InteractiveAuto (two-project solution, default)

## Manual Setup in an Existing Project

### 1. Install the Package

```bash
dotnet add package NeoUI.Blazor --version 4.0.0
```

### 2. Add _Imports.razor Entries

```razor
@using NeoUI.Blazor
@using NeoUI.Blazor.Services
@using NeoUI.Icons.Lucide
```

### 3. Register Services

**Server / Auto host project (Program.cs):**
```csharp
builder.Services.AddNeoUIPrimitives();
builder.Services.AddNeoUIComponents();
```

**WASM client project (Program.cs):**
```csharp
builder.Services.AddNeoUIPrimitives();
builder.Services.AddNeoUIComponents();
```

### 4. Add Theme CSS in App.razor

```html
<!-- Component styles (always required) -->
<link rel="stylesheet" href="_content/NeoUI.Blazor/components.css" />
<!-- Base color (choose one: zinc | slate | gray | neutral | stone) -->
<link rel="stylesheet" href="_content/NeoUI.Blazor/css/themes/base/zinc.css" />
<!-- Primary accent (choose one: blue | green | red | violet | orange | ...) -->
<link rel="stylesheet" href="_content/NeoUI.Blazor/css/themes/primary/blue.css" />
<!-- Theme init script (prevents flash of unstyled content) -->
<script src="_content/NeoUI.Blazor/js/theme.js"></script>
```

### 5. Add Portal Hosts in MainLayout.razor

Place all four after `@Body`, outside any scrollable or clipping container:
```razor
<ToastViewport />
<DialogHost />
<ContainerPortalHost />
<OverlayPortalHost />
```

### 5.5. Wrap MainLayout in AppProvider

`AppProvider` must be the outermost wrapper in `MainLayout.razor`. It initializes ThemeService, restores the persisted theme from localStorage, and broadcasts StyleVariant as a CascadingValue to all child components:
```razor
@* MainLayout.razor *@
<AppProvider>
    @Body
    <ToastViewport />
    <SpotlightCommandPalette />
    <DialogHost />
</AppProvider>
```

Components rendered outside `AppProvider` will receive `StyleVariant.Default` permanently.

### 6. Enable InteractiveAuto Render Mode in App.razor

```razor
<HeadOutlet @rendermode="InteractiveAuto" />
<Routes @rendermode="InteractiveAuto" />
```

## Your First Component

```razor
@page "/demo"
@using NeoUI.Blazor

<Button OnClick="@(() => count++)" Variant="ButtonVariant.Default">
 Clicked @count times
</Button>

@code { int count; }
```

## Common Import Patterns

```razor
@* All styled components + services *@
@using NeoUI.Blazor
@using NeoUI.Blazor.Services

@* Charts (separate sub-namespace) *@
@using NeoUI.Blazor.Charts

@* Headless primitives only *@
@using NeoUI.Blazor.Primitives
@using NeoUI.Blazor.Primitives.Services

@* Icons *@
@using NeoUI.Icons.Lucide@* 1,640 icons *@
@using NeoUI.Icons.Heroicons@* 1,288 icons *@
@using NeoUI.Icons.Feather  @* 286 icons *@
```

## Render Mode Notes

- NeoUI is designed for InteractiveAuto (Server + WASM). Set the global render mode in App.razor.
- Interactive components (Tabs, NavigationMenu, etc.) require an interactive render mode.
- For Server-only apps use InteractiveServer; for pure WASM use InteractiveWebAssembly.


==================================================================
FILE: installation.txt
URL:  https://neoui.io/llms/installation.txt
==================================================================

# NeoUI -- Installation Reference

## Packages

| Package | Description | Version |
|---------|-------------|---------|
| NeoUI.Blazor | Styled components (includes Primitives + all icons transitively) | 4.0.0 |
| NeoUI.Blazor.Primitives | Headless accessibility layer only | 4.0.0 |
| NeoUI.Icons.Lucide | 1,640 stroke-based icons | 3.0.0 |
| NeoUI.Icons.Heroicons | 1,288 icons, 4 variants (outline/solid/mini/micro) | 3.0.0 |
| NeoUI.Icons.Feather | 286 minimalist icons | 3.0.0 |

## Install Commands

```bash
# Styled components -- everything included
dotnet add package NeoUI.Blazor --version 4.0.0

# Headless primitives only (custom design system)
dotnet add package NeoUI.Blazor.Primitives --version 4.0.0

# Icons (included transitively with NeoUI.Blazor)
dotnet add package NeoUI.Icons.Lucide --version 3.0.0
dotnet add package NeoUI.Icons.Heroicons --version 3.0.0
dotnet add package NeoUI.Icons.Feather --version 3.0.0
```

## Service Registration (Program.cs)

Required in both Server host and WASM client for InteractiveAuto:

```csharp
builder.Services.AddNeoUIPrimitives();
builder.Services.AddNeoUIComponents();
```

**AppProvider:** After registering services, wrap `MainLayout.razor` in `<AppProvider>` to initialize ThemeService and enable Theme v2 (StyleVariant, RadiusPreset, etc.). See the Getting Started guide for the full pattern.

## _Imports.razor

```razor
@using NeoUI.Blazor
@using NeoUI.Blazor.Services
@using NeoUI.Icons.Lucide
```

For chart components:
```razor
@using NeoUI.Blazor.Charts
```

For headless primitives:
```razor
@using NeoUI.Blazor.Primitives
@using NeoUI.Blazor.Primitives.Services
```

## Theme CSS (App.razor)

Place before `</head>` in this order:

```html
<!-- 1. Component styles (required) -->
<link rel="stylesheet" href="_content/NeoUI.Blazor/components.css" />

<!-- 2. Base color (choose one) -->
<!-- zinc | slate | gray | neutral | stone | luma | mist | mauve | taupe | olive -->
<link rel="stylesheet" href="_content/NeoUI.Blazor/css/themes/base/zinc.css" />

<!-- 3. Primary accent (choose one) -->
<!-- blue | green | red | rose | orange | amber | yellow | lime | teal | cyan |
     sky | indigo | violet | purple | fuchsia | pink | slate -->
<link rel="stylesheet" href="_content/NeoUI.Blazor/css/themes/primary/blue.css" />

<!-- 4. Style variant (optional) -->
<!-- vega | nova | maia | lyra | mira | luma   (Default = no file) -->
<!-- <link rel="stylesheet" href="_content/NeoUI.Blazor/css/themes/styles/vega.css" /> -->

<!-- 5. Radius preset (optional) -->
<!-- none | small | large   (medium = default, no file needed) -->
<!-- <link rel="stylesheet" href="_content/NeoUI.Blazor/css/themes/radius/small.css" /> -->

<!-- 6. Font preset (optional -- sets CSS variables only; load font faces separately) -->
<!-- inter | geist | calsans | dmsans | plusjakarta   (system = default, no file) -->
<!-- <link rel="stylesheet" href="_content/NeoUI.Blazor/css/themes/fonts/inter.css" /> -->

<!-- 7. Theme init script (must be before Blazor to prevent FOUC) -->
<script src="_content/NeoUI.Blazor/js/theme.js"></script>
```

This gives 10 base x 17 primary = **170** ready-made color combinations, plus style variant, radius, and font customization.

## Icon Usage

```razor
@* Lucide -- kebab-case name, Size, Class, StrokeWidth *@
<LucideIcon Name="circle-check" Size="20" Class="text-green-500" />

@* Heroicons -- Name, Variant (Outline|Solid|Mini|Micro), Size *@
<HeroIcon Name="check-circle" Variant="HeroIconVariant.Solid" Size="20" />

@* Feather *@
<FeatherIcon Name="check-circle" Size="20" />
```

## Tailwind CSS v4 (Optional -- for custom styles)

NeoUI ships pre-built CSS. Tailwind is only needed when customizing styles.

```bash
npm install
npm run build:css  # one-time build
npm run watch:css  # dev watch mode
```

Add to .csproj to auto-build during dotnet build:
```xml
<Target Name="BuildTailwindCss" BeforeTargets="Build">
  <Exec Command="npm run build:css" WorkingDirectory="$(ProjectDir)" />
</Target>
```

## Compatibility

- .NET 10+ (also compatible with .NET 8 and .NET 9)
- All Blazor hosting models: Server, WebAssembly, Auto
- Dark mode: automatic via CSS variables


==================================================================
FILE: architecture.txt
URL:  https://neoui.io/llms/architecture.txt
==================================================================

# NeoUI -- Architecture

NeoUI is built on a two-layer architecture separating behavior from styling,
designed for .NET 10's InteractiveAuto rendering mode.

## Two-Layer Overview

### Layer 1: NeoUI.Blazor (Styled Components)
- 100+ production-ready components with shadcn/ui design
- Pre-built CSS included -- no Tailwind CSS setup required
- Full theme support via CSS custom properties
- Built on top of the Primitives layer

### Layer 2: NeoUI.Blazor.Primitives (Headless Layer)
- 15 headless, unstyled components providing behavior only
- WCAG 2.1 AA accessibility, keyboard navigation, ARIA attributes
- Bring your own styles -- or use NeoUI.Blazor on top
- Available primitives: Accordion, Checkbox, Collapsible, Dialog, Dropdown Menu,
  Hover Card, Label, Popover, Radio Group, Select, Sheet, Switch, Table, Tabs, Tooltip

Every styled component in NeoUI.Blazor is built on a matching primitive.

## Project Structure (InteractiveAuto -- recommended)

```
MyApp.sln
MyApp/  # ASP.NET Core host (Server + WASM server-side)
+-- MyApp.csproj
+-- Program.cs# Registers both Interactive Server + WebAssembly
\-- App.razor # Global render mode = InteractiveAuto

MyApp.Client/ # Blazor WebAssembly project
+-- MyApp.Client.csproj
+-- Program.cs# WASM entry point with NeoUI services
+-- Layout/
|+-- MainLayout.razor  # Sidebar + ThemeSwitcher + DarkModeToggle
|\-- NavMenu.razor
\-- Components/Pages/
```

## Render Modes

### InteractiveAuto (Recommended)
Starts with Server rendering, seamlessly transitions to WebAssembly after download.
```razor
<!-- App.razor -->
<HeadOutlet @rendermode="InteractiveAuto" />
<Routes @rendermode="InteractiveAuto" />
```

### InteractiveServer
All interaction handled server-side via SignalR.
```razor
<Routes @rendermode="InteractiveServer" />
```

### InteractiveWebAssembly
Pure client-side rendering.
```razor
<Routes @rendermode="InteractiveWebAssembly" />
```

## Service Registration

### Server host Program.cs
```csharp
builder.Services.AddRazorComponents()
 .AddInteractiveServerComponents()
 .AddInteractiveWebAssemblyComponents();

builder.Services.AddNeoUIPrimitives();
builder.Services.AddNeoUIComponents();
```

### WASM client Program.cs
```csharp
builder.Services.AddNeoUIPrimitives();
builder.Services.AddNeoUIComponents();
```

## Portal System

NeoUI uses four dedicated portal hosts to render overlays at the root DOM level, outside any
stacking context that could clip or obscure them. Place all four **inside** `AppProvider` in MainLayout.razor,
after `@Body` — this ensures overlays inherit the active style variant.

### Setup
```razor
@inherits LayoutComponentBase

@* AppProvider provides Theme v2 StyleVariant to all components, including portal overlays *@
<AppProvider>
    <div class="min-h-screen bg-background">
        @Body
    </div>

    @* Portal hosts inside AppProvider so overlays inherit the active style variant *@
    <ToastViewport />
    <DialogHost />
    <ContainerPortalHost />
    <OverlayPortalHost />
</AppProvider>
```

### What Each Host Does

| Host | Renders |
|------|---------|
| `ToastViewport` | Toast notification messages (position configurable) |
| `DialogHost` | Programmatic dialogs via `DialogService` |
| `ContainerPortalHost` | Inline overlays: Popover, Tooltip, DropdownMenu |
| `OverlayPortalHost` | Full-screen overlays: Dialog, Sheet, Drawer |

## Component Namespace Structure

```csharp
NeoUI.Blazor// All styled components (Button, Card, Input, etc.)
NeoUI.Blazor.Services// IThemeService, IDialogService, etc.
NeoUI.Blazor.Charts  // Chart components (separate namespace)
NeoUI.Blazor.Primitives // Headless primitives
NeoUI.Blazor.Primitives.Services  // IKeyboardShortcutService
NeoUI.Icons.Lucide// LucideIcon component
NeoUI.Icons.Heroicons// HeroIcon component
NeoUI.Icons.Feather  // FeatherIcon component
```

## Keyboard Shortcuts

```razor
@inject IKeyboardShortcutService KeyboardShortcuts

protected override async Task OnAfterRenderAsync(bool firstRender)
{
 if (firstRender)
  await KeyboardShortcuts.RegisterAsync("Ctrl+K", OpenCommandPalette);
}
```


==================================================================
FILE: theming.txt
URL:  https://neoui.io/llms/theming.txt
==================================================================

# NeoUI -- Theming

NeoUI is 100% compatible with shadcn/ui themes. NeoUI v4.0.0 ships Theme v2: 10 base colors x 17 primary accents = 170 combinations, plus StyleVariant, RadiusPreset, FontPreset, MenuColor, MenuAccent, and ThemePreset bundling all dimensions atomically.

## How Theming Works

All NeoUI components use CSS custom properties (variables) in OKLCH color format for colors, spacing, and radius. Switching a theme means swapping variable definitions -- no recompiling, no class changes.

## AppProvider (Required in v4.0.0)

`AppProvider` must wrap everything in `MainLayout.razor`, including all portal hosts. It (1) initializes ThemeService and restores the persisted theme from localStorage, and (2) broadcasts the active StyleVariant as a CascadingValue. Components outside AppProvider receive StyleVariant.Default permanently.

```razor
@* MainLayout.razor *@
<AppProvider>
    @Body
    <ToastViewport />
    <SpotlightCommandPalette />
    <DialogHost />
</AppProvider>
```

## CSS Load Order (v4.0.0)

Place in `App.razor` in this exact order:

```html
<!-- 1. Component styles (required) -->
<link rel="stylesheet" href="_content/NeoUI.Blazor/components.css" />

<!-- 2. Base color (choose one) -->
<!-- zinc | slate | gray | neutral | stone | luma | mist | mauve | taupe | olive -->
<link rel="stylesheet" href="_content/NeoUI.Blazor/css/themes/base/zinc.css" />

<!-- 3. Primary accent (choose one) -->
<!-- blue | green | red | rose | orange | amber | yellow | lime | teal | cyan |
     sky | indigo | violet | purple | fuchsia | pink | slate -->
<link rel="stylesheet" href="_content/NeoUI.Blazor/css/themes/primary/blue.css" />

<!-- 4. Style variant (optional) -->
<!-- vega | nova | maia | lyra | mira | luma   (Default needs no file) -->
<link rel="stylesheet" href="_content/NeoUI.Blazor/css/themes/styles/vega.css" />

<!-- 5. Radius preset (optional) -->
<!-- none | small | large   (medium = default, no file needed) -->
<link rel="stylesheet" href="_content/NeoUI.Blazor/css/themes/radius/small.css" />

<!-- 6. Font preset (optional) -->
<!-- inter | geist | calsans | dmsans | plusjakarta   (system = default, no file) -->
<!-- Note: sets CSS variables only; load actual font faces separately (Google Fonts, etc.) -->
<link rel="stylesheet" href="_content/NeoUI.Blazor/css/themes/fonts/inter.css" />

<!-- 7. Theme init script (must be before Blazor to prevent FOUC) -->
<script src="_content/NeoUI.Blazor/js/theme.js"></script>
```

## Key CSS Variables

```css
:root {
  /* Surfaces */
  --background:             /* page background */;
  --foreground:             /* body text */;
  --card:                   /* card background */;
  --card-foreground:        /* card text */;
  --popover:                /* popover/dropdown background */;
  --popover-foreground:     /* popover text */;

  /* Brand */
  --primary:                /* primary brand color */;
  --primary-foreground:     /* text on primary */;
  --secondary:              /* secondary surface */;
  --secondary-foreground:   /* text on secondary */;
  --muted:                  /* muted background */;
  --muted-foreground:       /* muted text */;
  --accent:                 /* hover/accent surface */;
  --accent-foreground:      /* text on accent */;
  --destructive:            /* error/danger color */;
  --destructive-foreground: /* text on destructive */;

  /* Structure */
  --border:                 /* border color */;
  --ring:                   /* focus ring color */;
  --radius:                 /* base border radius */;

  /* Sidebar */
  --sidebar:                /* sidebar background */;
  --sidebar-foreground:     /* sidebar text */;
  --sidebar-primary:        /* sidebar active item */;
  --sidebar-accent:         /* sidebar hover */;
  --sidebar-border:         /* sidebar border */;

  /* Charts */
  --chart-1 ... --chart-5:  /* chart color palette */;

  /* Alerts */
  --alert-info, --alert-warning, --alert-success;

  /* Typography */
  --font-sans:              /* body font stack */;
  --font-heading:           /* heading font stack; falls back to --font-sans */;

  /* Radius scale (proportional, safe at --radius: 0rem) */
  --radius-xs:  /* x0.4 */;
  --radius-sm:  /* x0.6 */;
  --radius-md:  /* x0.8 */;
  --radius-lg:  /* x1.0 (base) */;
  --radius-xl:  /* x1.4 */;
  --radius-2xl: /* x1.8 */;
  --radius-4xl: /* x2.6 */;
}
```

## Dark Mode

Dark mode variables are defined in each theme file under `.dark` / `[data-theme="dark"]`.

Use the built-in toggle:
```razor
<DarkModeToggle />
```

Or `ThemeSwitcher` for full palette + style switching:
```razor
<ThemeSwitcher ShowStyles="true" />
```

Register the theme service:
```csharp
builder.Services.AddNeoUIComponents(); // includes ThemeService
```

## StyleVariant Enum

Controls `--radius`, `--spacing-scale`, and shadow values. Broadcast as CascadingValue from AppProvider.

| Variant | --radius   | --spacing-scale | Character                        |
|---------|------------|-----------------|----------------------------------|
| Default | unchanged  | 1               | Backward-compatible (no file)    |
| Vega    | 0.625rem   | 1               | Professional, balanced           |
| Nova    | 0.375rem   | 0.85            | Compact, dashboard/admin         |
| Maia    | 1rem       | 1.15            | Spacious, consumer-friendly      |
| Lyra    | 0rem       | 1               | Sharp/boxy, developer tooling    |
| Mira    | 0.25rem    | 0.7             | Ultra-dense, data-heavy          |
| Luma    | 0.75rem    | 1               | Glassmorphism, modern SaaS       |

CSS: `_content/NeoUI.Blazor/css/themes/styles/{vega,nova,maia,lyra,mira,luma}.css`

Luma extras: soft diffuse shadows, semi-transparent inputs via `color-mix`, stronger overlay blur (`--blur-sm: 4px` on `[data-slot="overlay"]`).

```csharp
await ThemeService.SetStyleVariantAsync(StyleVariant.Nova);
```

## RadiusPreset Enum

Independent named radius overrides; takes precedence over StyleVariant in the CSS cascade.

| Preset | Value                      |
|--------|----------------------------|
| None   | 0rem                       |
| Small  | 0.45rem                    |
| Medium | 0.625rem (default, no file)|
| Large  | 0.875rem                   |

CSS: `_content/NeoUI.Blazor/css/themes/radius/{none,small,large}.css`

```csharp
await ThemeService.SetRadiusPresetAsync(RadiusPreset.Large);
```

## 7-Step Proportional Radius Scale

All scale steps derive from `--radius`; safe at `--radius: 0rem` (Lyra style).

| Variable    | Multiplier |
|-------------|------------|
| --radius-xs | x0.4       |
| --radius-sm | x0.6       |
| --radius-md | x0.8       |
| --radius-lg | x1.0 (base)|
| --radius-xl | x1.4       |
| --radius-2xl| x1.8       |
| --radius-4xl| x2.6       |

## FontPreset Enum

6 curated font pairings setting `--font-sans` and `--font-heading`.

| Preset      | Description                    |
|-------------|-------------------------------|
| System      | system-ui stack (default, no file) |
| Inter       | Inter                         |
| Geist       | Geist                         |
| CalSans     | CalSans                       |
| DmSans      | DM Sans                       |
| PlusJakarta | Plus Jakarta Sans             |

CSS: `_content/NeoUI.Blazor/css/themes/fonts/{inter,geist,calsans,dmsans,plusjakarta}.css`

**Note:** Font CSS files set CSS variables only. Load the actual font face files separately (e.g. Google Fonts `<link>` tag or local @font-face declarations).

```csharp
await ThemeService.SetFontPresetAsync(FontPreset.Inter);
```

## --font-heading Variable

Falls back to `--font-sans` when not explicitly set. Font presets assign it independently to enable distinct heading typography.

## MenuColor Enum

Controls background treatment of all floating surfaces: Popover, DropdownMenu, Select, Combobox.

| Value                | Treatment                                                   |
|----------------------|-------------------------------------------------------------|
| Default              | Solid surface                                               |
| Inverted             | Dark surface (light mode only)                              |
| DefaultTranslucent   | 50% opacity + blur(18px) + saturate(150%)                   |
| InvertedTranslucent  | Dark + 70% opacity + blur (light mode only)                 |

```csharp
await ThemeService.SetMenuColorAsync(MenuColor.DefaultTranslucent);
```

## MenuAccent Enum

Controls hover intensity on menu items.

| Value  | Color                                    |
|--------|------------------------------------------|
| Subtle | --accent (default)                       |
| Bold   | --primary (high-contrast brand hover)    |

```csharp
await ThemeService.SetMenuAccentAsync(MenuAccent.Bold);
```

## BaseColor Enum (10 Total)

v4.0.0 adds 5 new chromatic neutrals.

| Color   | Character                         |
|---------|-----------------------------------|
| Zinc    | Neutral gray (default)            |
| Slate   | Cool blue-gray                    |
| Gray    | Neutral gray                      |
| Neutral | Warm gray                         |
| Stone   | Warm brownish                     |
| Luma    | Blue-indigo tinted (new in v4)    |
| Mist    | Cool blue-gray (new in v4)        |
| Mauve   | Warm purple-gray (new in v4)      |
| Taupe   | Warm brownish-gray (new in v4)    |
| Olive   | Muted green-gray (new in v4)      |

CSS: `_content/NeoUI.Blazor/css/themes/base/{luma,mist,mauve,taupe,olive}.css`
Total combinations: 10 base x 17 primary = **170**

```csharp
await ThemeService.SetBaseColorAsync(BaseColor.Luma);
```

## ThemePreset Record

Bundles all 8 theme dimensions atomically: BaseColor, PrimaryColor, StyleVariant, RadiusPreset, FontPreset, MenuAccent, MenuColor, and Name.

### Built-in Presets

| Preset  | Base  | Style   | Radius | Font        |
|---------|-------|---------|--------|-------------|
| Default | Zinc  | Default | Medium | System      |
| Luma    | Zinc  | Luma    | Medium | Inter       |
| Nova    | Zinc  | Nova    | Small  | Geist       |
| Maia    | Mauve | Maia    | Large  | PlusJakarta |
| Lyra    | Slate | Lyra    | None   | Geist       |

```csharp
// Apply a built-in preset
await ThemeService.ApplyPresetAsync(ThemePreset.Luma);

// Create and apply a custom preset
var custom = new ThemePreset(
    Name: "Glass Dashboard",
    BaseColor: BaseColor.Luma,
    PrimaryColor: PrimaryColor.Blue,
    StyleVariant: StyleVariant.Luma,
    RadiusPreset: RadiusPreset.Medium,
    FontPreset: FontPreset.Inter,
    MenuAccent: MenuAccent.Bold,
    MenuColor: MenuColor.DefaultTranslucent
);
await ThemeService.ApplyPresetAsync(custom);
```

## ThemeService API

```razor
@inject IThemeService ThemeService
```

### Properties

| Property              | Type           |
|-----------------------|----------------|
| CurrentBaseColor      | BaseColor      |
| CurrentPrimaryColor   | PrimaryColor   |
| CurrentStyleVariant   | StyleVariant   |
| CurrentRadiusPreset   | RadiusPreset   |
| CurrentFontPreset     | FontPreset     |
| CurrentMenuAccent     | MenuAccent     |
| CurrentMenuColor      | MenuColor      |

### Methods

| Method                              | Description                              |
|-------------------------------------|------------------------------------------|
| SetBaseColorAsync(BaseColor)        | Switch base palette                      |
| SetPrimaryColorAsync(PrimaryColor)  | Switch primary accent                    |
| SetStyleVariantAsync(StyleVariant)  | Switch style variant                     |
| SetRadiusPresetAsync(RadiusPreset)  | Switch radius preset                     |
| SetFontPresetAsync(FontPreset)      | Switch font preset                       |
| SetMenuAccentAsync(MenuAccent)      | Switch menu item hover intensity         |
| SetMenuColorAsync(MenuColor)        | Switch floating surface treatment        |
| ApplyPresetAsync(ThemePreset)       | Apply all 8 dimensions atomically        |
| SetTheme(base, primary)             | Legacy method -- still works             |

### Runtime Switching Examples

```razor
@inject IThemeService ThemeService

<Button OnClick="@(() => ThemeService.SetStyleVariantAsync(StyleVariant.Nova))">Nova</Button>
<Button OnClick="@(() => ThemeService.SetRadiusPresetAsync(RadiusPreset.Large))">Large Radius</Button>
<Button OnClick="@(() => ThemeService.SetFontPresetAsync(FontPreset.Inter))">Inter Font</Button>
<Button OnClick="@(() => ThemeService.SetMenuColorAsync(MenuColor.DefaultTranslucent))">Frosted Menus</Button>
<Button OnClick="@(() => ThemeService.ApplyPresetAsync(ThemePreset.Luma))">Luma Preset</Button>
```

## ThemeSwitcher Component

```razor
<ThemeSwitcher ShowStyles="true" />
```

| Parameter          | Type                | Default | Description                                           |
|--------------------|---------------------|---------|-------------------------------------------------------|
| ShowStyles         | bool                | false   | Adds Styles tab (variant, radius, font, menu options) |
| Strategy           | PositioningStrategy | Fixed   | Popover positioning strategy                          |
| ZIndex             | int                 | 60      | z-index of the switcher popover                       |
| TriggerClass       | string?             | null    | CSS classes on the trigger button                     |
| PopoverContentClass| string?             | null    | CSS classes on the popover content                    |
| Align              | PopoverAlign        | End     | Popover alignment                                     |

Trigger button shows a two-tone swatch: current base color (fill) + current primary (border). With `ShowStyles="true"`: Colors tab (base + primary selectors) + Styles tab (variant, radius, font, menu accent, menu color).

## Custom Theme (OKLCH Format)

NeoUI v4 uses OKLCH color format internally:

```css
/* wwwroot/css/my-theme.css */
:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.623 0.214 259.8);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.96 0 0);
  --muted: oklch(0.96 0 0);
  --accent: oklch(0.96 0 0);
  --destructive: oklch(0.577 0.245 27.3);
  --border: oklch(0.92 0 0);
  --ring: oklch(0.623 0.214 259.8);
  --radius: 0.625rem;
}
.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  /* ... */
}
```

## shadcn/ui Compatibility

NeoUI is 100% compatible with shadcn/ui themes. Use any theme from https://ui.shadcn.com/themes or https://tweakcn.com directly. shadcn/ui themes use HSL format; NeoUI's own files use OKLCH. Both formats work -- CSS custom properties accept either.

## Tailwind v4 Integration

NeoUI's pre-built CSS works without Tailwind. If using Tailwind v4 for custom styles, you **must** add `@theme inline` to your Tailwind build input. Without it, Tailwind v4 emits hardcoded `oklch()` values that override NeoUI's runtime CSS variable changes:

```css
/* app.css */
@import "tailwindcss";
@theme inline {
  /* your customizations */
}
```

==================================================================
FILE: cli.txt
URL:  https://neoui.io/llms/cli.txt
==================================================================

# NeoUI -- CLI Tools & Build Commands

## Package Management

```bash
# Install styled components (includes Primitives + all icon libraries)
dotnet add package NeoUI.Blazor --version 3.6.3

# Headless primitives only (custom design systems)
dotnet add package NeoUI.Blazor.Primitives --version 3.6.3

# Icon libraries (included transitively with NeoUI.Blazor)
dotnet add package NeoUI.Icons.Lucide --version 3.0.0
dotnet add package NeoUI.Icons.Heroicons --version 3.0.0
dotnet add package NeoUI.Icons.Feather --version 3.0.0

# Project template
dotnet new install NeoUI.Blazor.Templates
```

## Project Template CLI

```bash
# Create new NeoUI Blazor app
dotnet new neoui -n MyApp

# With specific interactivity mode
dotnet new neoui -n MyApp -in Server  # Blazor Server
dotnet new neoui -n MyApp -in WebAssembly# Blazor WASM
dotnet new neoui -n MyApp -in Auto # InteractiveAuto (default, two-project)

# Empty layout (no demo pages)
dotnet new neoui -n MyApp --empty

# List all template options
dotnet new neoui --help
```

## Build & Run

```bash
dotnet build # Builds project (also runs npm install + Tailwind CSS if configured)
dotnet run# Starts dev server at https://localhost:5001
dotnet watch # Hot-reload dev mode
dotnet publish  # Publish for deployment
```

## CSS Build (Tailwind CSS v4 -- optional)

```bash
npm install  # Install Tailwind and dependencies
npm run build:css  # One-time CSS compilation
npm run watch:css  # Watch mode for development
```

The NeoUI project template pre-configures the .csproj to auto-run the CSS build on `dotnet build`:

```xml
<Target Name="NpmInstall" BeforeTargets="BuildTailwindCss">
  <Exec Command="npm install" WorkingDirectory="$(ProjectDir)" />
</Target>
<Target Name="BuildTailwindCss" BeforeTargets="Build">
  <Exec Command="npm run build:css" WorkingDirectory="$(ProjectDir)" />
</Target>
```

## Testing

```bash
dotnet test  # Run all tests
dotnet test --filter "Category=Unit"
```

## NuGet Pack & Publish (library authors)

```bash
dotnet pack -c Release
dotnet nuget push bin/Release/*.nupkg --api-key $NUGET_API_KEY --source https://api.nuget.org/v3/index.json
```

## Useful dotnet CLI Tips

```bash
dotnet list package --outdated # Check for newer package versions
dotnet restore  # Restore NuGet packages
dotnet clean # Clean build outputs
dotnet format# Format code (requires dotnet-format tool)
```


==================================================================
FILE: templates.txt
URL:  https://neoui.io/llms/templates.txt
==================================================================

# NeoUI -- Project Templates

NeoUI ships a `dotnet new` template that scaffolds a complete, production-ready Blazor app
with sidebar layout, theme switcher, dark mode, Spotlight command palette, and Tailwind CSS v4.

## Install the Template

```bash
dotnet new install NeoUI.Blazor.Templates
```

## Create a New App

```bash
dotnet new neoui -n MyApp  # Auto mode (default)
dotnet new neoui -n MyApp -in Server# Blazor Server
dotnet new neoui -n MyApp -in WebAssembly # Blazor WebAssembly
dotnet new neoui -n MyApp -in Auto  # InteractiveAuto
dotnet new neoui -n MyApp --empty# Minimal layout, no demo pages
dotnet new neoui -n MyApp -in Auto --empty# Auto + minimal
```

## Template Options

| Option | Short | Values | Default | Description |
|--------|-------|--------|---------|-------------|
| `--interactivity` | `-in` | Server, WebAssembly, Auto | Auto | Blazor render mode |
| `--empty` | | flag | false | Skip demo pages, minimal layout |
| `--style` | | Default/Vega/Nova/Maia/Lyra/Mira/Luma | Default | Theme v2 style variant -- spacing/radius/density |
| `--font` | | System/Inter/Geist/CalSans/DmSans/PlusJakarta | System | Font preset (sets --font-sans/--font-heading CSS vars) |
| `--radius` | | None/Small/Medium/Large | Medium | Border radius preset |
| `--menuColor` | | Default/Inverted/DefaultTranslucent/InvertedTranslucent | Default | Menu/popover surface style |
| `--menuAccent` | | Subtle/Bold | Subtle | Menu item hover intensity |

## Project Structures

### Server Mode (`-in Server`) -- Single Project
```
MyApp/
+-- MyApp.csproj
+-- Program.cs
+-- App.razor
+-- Layout/
|+-- MainLayout.razor # NeoUI Sidebar + ThemeSwitcher + DarkModeToggle
|\-- NavMenu.razor
+-- Components/
|+-- Common/
||+-- AppLoader.razor
||\-- SpotlightCommandPalette.razor
|\-- Pages/
+-- Home.razor
+-- Counter.razor
+-- Weather.razor
\-- NotFound.razor
+-- styles/  # Tailwind CSS source
+-- wwwroot/ # Compiled CSS + static assets
+-- package.json
\-- tailwind.config.js
```

### Auto / WebAssembly Mode -- Two-Project Solution
```
MyApp.sln
MyApp/ # Web host project
\-- MyApp.csproj

MyApp.Client/# WebAssembly client
+-- MyApp.Client.csproj
+-- Program.cs
+-- Layout/
|+-- MainLayout.razor
|\-- NavMenu.razor
+-- Components/
|+-- Common/
||+-- AppLoader.razor
||+-- ReconnectModal.razor # Auto mode only
||\-- SpotlightCommandPalette.razor
|\-- Pages/
+-- Home.razor
+-- Counter.razor
+-- Weather.razor
\-- NotFound.razor
+-- styles/
+-- wwwroot/
+-- package.json
\-- tailwind.config.js
```

## What the Template Includes

- **Sidebar layout** -- collapsible navigation, breadcrumbs, responsive mobile support
- **ThemeSwitcher** -- 170-combination theme picker (10 base x 17 primary) with style variant selector
- **DarkModeToggle** -- OS-aware dark mode
- **Spotlight Command Palette** -- Ctrl+K fuzzy search for components and pages
- **Tailwind CSS v4** -- pre-configured with NeoUI design tokens
- **Pre-wired services** -- `AddNeoUIPrimitives()`, `AddNeoUIComponents()`
- **_Imports.razor** -- all NeoUI namespaces ready to use
- **Sample pages** -- Home, Counter, Weather (can be removed with `--empty`)

## Post-Create Steps

The Tailwind CSS build and `npm install` run automatically on `dotnet build`.
Node.js must be on your PATH.

```bash
cd MyApp
dotnet run --project MyApp# Start the app
```

## Updating the Template

```bash
dotnet new update # Update all installed templates
dotnet new install NeoUI.Blazor.Templates::4.0.0# Pin a version
```


==================================================================
FILE: components.txt
URL:  https://neoui.io/llms/components.txt
==================================================================

# NeoUI -- Components Reference

NeoUI ships 100+ production-ready styled components. All require `@using NeoUI.Blazor`.

## Quick Import

```razor
@using NeoUI.Blazor
@using NeoUI.Blazor.Services
@using NeoUI.Icons.Lucide
```

---

## Inputs & Forms

### Button
```razor
<Button Variant="ButtonVariant.Default" Size="ButtonSize.Default" OnClick="@Handler" Disabled="false">
 Click me
</Button>
```
Variants: `Default` | `Secondary` | `Destructive` | `Outline` | `Ghost` | `Link`
Sizes: `Default` | `Sm` | `Lg` | `Icon`

### Input
```razor
<Input Type="text" Placeholder="Enter text..." @bind-Value="value" Disabled="false" Class="" />
```
Types: text | password | email | number | search | url | tel

### Textarea
```razor
<Textarea Placeholder="Multi-line..." @bind-Value="value" Rows="4" AutoResize="true" />
```

### Checkbox
```razor
<Checkbox @bind-Checked="isChecked" Indeterminate="false" Disabled="false">
 Label text
</Checkbox>
```

### Switch
```razor
<Switch @bind-Checked="isOn" Disabled="false" />
```

### RadioGroup
```razor
<RadioGroup @bind-Value="selected" Orientation="Orientation.Vertical">
 <RadioGroupItem Value="a">Option A</RadioGroupItem>
 <RadioGroupItem Value="b">Option B</RadioGroupItem>
</RadioGroup>
```

### Select
```razor
<Select @bind-Value="selected" Placeholder="Choose...">
 <SelectTrigger />
 <SelectContent>
  <SelectItem Value="opt1">Option 1</SelectItem>
  <SelectItem Value="opt2">Option 2</SelectItem>
  <SelectGroup Label="Group">
<SelectItem Value="opt3">Option 3</SelectItem>
  </SelectGroup>
 </SelectContent>
</Select>
```

### NativeSelect
```razor
<NativeSelect @bind-Value="selected">
 <option value="a">Option A</option>
 <option value="b">Option B</option>
</NativeSelect>
```

### Label
```razor
<Label For="inputId">Field Label</Label>
```

### Field (Label + Input + Help Text)
```razor
<Field Label="Email" For="email" HelpText="We won't share your email.">
 <Input Id="email" Type="email" @bind-Value="email" />
</Field>
```

### Slider
```razor
<Slider @bind-Value="sliderValue" Min="0" Max="100" Step="1" />
```

### RangeSlider
```razor
<RangeSlider @bind-Values="rangeValues" Min="0" Max="100" />
```

### Toggle / ToggleGroup
```razor
<Toggle @bind-Pressed="isPressed" Variant="ToggleVariant.Default">Bold</Toggle>

<ToggleGroup @bind-Value="format" Type="ToggleGroupType.Single">
 <ToggleGroupItem Value="bold"><LucideIcon Name="bold" Size="16" /></ToggleGroupItem>
 <ToggleGroupItem Value="italic"><LucideIcon Name="italic" Size="16" /></ToggleGroupItem>
</ToggleGroup>
```

### Rating
```razor
<Rating @bind-Value="rating" Max="5" AllowHalf="true" ReadOnly="false" />
```

---

## Advanced Inputs

### Calendar
```razor
<Calendar @bind-Value="selectedDate" Mode="CalendarMode.Single" />
```
Modes: `Single` | `Multiple` | `Range`

### DatePicker
```razor
<DatePicker @bind-Value="date" Placeholder="Pick a date" Format="yyyy-MM-dd" />
```

### DateRangePicker
```razor
<DateRangePicker @bind-Start="startDate" @bind-End="endDate" ShowPresets="true" />
```

### TimePicker
```razor
<TimePicker @bind-Value="time" Format="HH:mm" />
```

### Combobox
```razor
<Combobox @bind-Value="selected" Placeholder="Search...">
 <ComboboxTrigger />
 <ComboboxContent>
  <ComboboxInput Placeholder="Search..." />
  <ComboboxList>
<ComboboxItem Value="item1">Item 1</ComboboxItem>
  </ComboboxList>
 </ComboboxContent>
</Combobox>
```

### MultiSelect
```razor
<MultiSelect @bind-Values="selectedItems" Placeholder="Select items...">
 <MultiSelectItem Value="a">Apple</MultiSelectItem>
 <MultiSelectItem Value="b">Banana</MultiSelectItem>
</MultiSelect>
```

### InputGroup
```razor
<InputGroup>
 <InputGroupAddon><LucideIcon Name="mail" Size="16" /></InputGroupAddon>
 <Input Type="email" Placeholder="email@example.com" />
 <InputGroupButton><Button>Send</Button></InputGroupButton>
</InputGroup>
```

### InputOtp
```razor
<InputOtp Length="6" @bind-Value="otpValue" OnComplete="@HandleComplete" />
```

### NumericInput
```razor
<NumericInput @bind-Value="quantity" Min="0" Max="999" Step="1" Format="N0" />
```

### CurrencyInput
```razor
<CurrencyInput @bind-Value="amount" Currency="USD" Locale="en-US" />
```

### MaskedInput
```razor
<MaskedInput @bind-Value="phone" Mask="(000) 000-0000" Placeholder="(555) 123-4567" />
```

### FileUpload
```razor
<FileUpload Accept=".pdf,.docx" Multiple="true" MaxSize="10485760"
OnFilesSelected="@HandleFiles" OnError="@HandleError" />
```

### MarkdownEditor
```razor
<MarkdownEditor @bind-Value="markdown" Placeholder="Write markdown..." />
```

### RichTextEditor
```razor
<RichTextEditor @bind-Value="htmlContent" Placeholder="Start writing..." />
```

### ColorPicker
```razor
<ColorPicker @bind-Value="color" ShowHex="true" ShowRgb="true" />
```

---

## Data Display

### Card
```razor
<Card Class="w-[350px]">
 <CardHeader>
  <CardTitle>Card Title</CardTitle>
  <CardDescription>Card description</CardDescription>
 </CardHeader>
 <CardContent>
  <p>Card content here.</p>
 </CardContent>
 <CardFooter>
  <Button>Action</Button>
 </CardFooter>
</Card>
```

### Badge
```razor
<Badge Variant="BadgeVariant.Default">New</Badge>
```
Variants: `Default` | `Secondary` | `Destructive` | `Outline` | `Success` | `Warning`

### Avatar
```razor
<Avatar>
 <AvatarImage Src="/avatar.jpg" Alt="User" />
 <AvatarFallback>JD</AvatarFallback>
</Avatar>
```

### DataGrid
See `datagrid.txt` for the complete DataGrid reference.

```razor
<DataGrid TItem="Product" Data="@products">
 <DataGridColumn Field="@nameof(Product.Name)" Header="Name" Sortable="true" />
 <DataGridColumn Field="@nameof(Product.Price)" Header="Price" />
</DataGrid>
```

### DataTable
```razor
<DataTable TItem="User" Data="@users" PageSize="10" Searchable="true" Sortable="true">
 <DataTableColumn Field="@nameof(User.Name)" Header="Name" />
 <DataTableColumn Field="@nameof(User.Email)" Header="Email" />
</DataTable>

@* Striped rows (3.6.3) *@
<DataTable TItem="User" Data="@users" Striped="true" SyncWidthOnResize="true" TableContainerClass="rounded-md border">
 <DataTableColumn Field="@nameof(User.Name)" Header="Name" />
</DataTable>

@* Pinned columns (3.6.2) *@
<DataTable TItem="User" Data="@users">
 <DataTableColumn Field="@nameof(User.Name)" Header="Name" Pinned="ColumnPinnedSide.Left" />
 <DataTableColumn Field="@nameof(User.Email)" Header="Email" />
</DataTable>

@* Client-side virtualization for large datasets (3.6.1) *@
<DataTable TItem="User" Data="@users" Virtualize="true" ItemHeight="40" Height="400px">
 <DataTableColumn Field="@nameof(User.Name)" Header="Name" />
</DataTable>

@* Server-side virtualization (3.6.1) *@
<DataTable TItem="User" ItemsProvider="@LoadUsers" Virtualize="true" Height="400px">
 <DataTableColumn Field="@nameof(User.Name)" Header="Name" />
</DataTable>

@* Hierarchical/tree rows (3.6.2) *@
<DataTable TItem="Category" Data="@categories" ChildrenProperty="@nameof(Category.Children)" HasChildrenField="@nameof(Category.HasChildren)">
 <DataTableColumn Field="@nameof(Category.Name)" Header="Name" />
</DataTable>
```

### FilterBuilder
```razor
<FilterBuilder TData="Product" @bind-Filters="filters" OnFilterChange="HandleChange">
 <FilterFields>
  <FilterField Field="Name" Label="Name" Icon="tag" Type="FilterFieldType.Text" />
  <FilterField Field="Category" Label="Category" Type="FilterFieldType.Select" Options="@opts" />
  <FilterField Field="Price" Label="Price" Type="FilterFieldType.Number" Min="0" />
  <FilterField Field="InStock" Label="In Stock" Type="FilterFieldType.Boolean" />
 </FilterFields>
</FilterBuilder>
```
Inline chip-based filter builder. 8 field types: `Text` | `Number` | `Date` | `DateRange` | `Boolean` | `Select` | `MultiSelect` | `Custom`. LINQ: `items.ApplyFilters(filters)`. See `components-full.txt` for presets and full reference.

### Skeleton
```razor
<Skeleton Class="h-4 w-[250px]" />
<Skeleton Class="h-4 w-[200px]" />
```

### ScrollArea
```razor
<ScrollArea Class="h-[200px] w-[350px]">
 @* long content *@
</ScrollArea>
```

### AspectRatio
```razor
<AspectRatio Ratio="16/9">
 <img src="image.jpg" alt="Image" class="object-cover w-full h-full" />
</AspectRatio>
```

### Empty
```razor
<Empty Icon="inbox" Title="No results" Description="Try adjusting your search.">
 <Button>Create New</Button>
</Empty>
```

### Item
```razor
<Item>
 <ItemMedia><LucideIcon Name="file" Size="20" /></ItemMedia>
 <ItemContent>
  <ItemTitle>Document.pdf</ItemTitle>
  <ItemDescription>2.4 MB</ItemDescription>
 </ItemContent>
 <ItemAction><Button Variant="ButtonVariant.Ghost" Size="ButtonSize.Icon">...</Button></ItemAction>
</Item>
```

### Kbd
```razor
<Kbd>Ctrl</Kbd> + <Kbd>K</Kbd>
```

### Typography
```razor
<TypographyH1>Heading 1</TypographyH1>
<TypographyH2>Heading 2</TypographyH2>
<TypographyH3>Heading 3</TypographyH3>
<TypographyP>Paragraph text</TypographyP>
<TypographyLead>Lead / intro text</TypographyLead>
<TypographyMuted>Muted text</TypographyMuted>
<TypographyBlockquote>A quotation</TypographyBlockquote>
<TypographyInlineCode>const x = 1;</TypographyInlineCode>
<TypographyList><li>Item 1</li><li>Item 2</li></TypographyList>
```

---

## Navigation

### Breadcrumb
```razor
<Breadcrumb>
 <BreadcrumbList>
  <BreadcrumbItem><BreadcrumbLink Href="/">Home</BreadcrumbLink></BreadcrumbItem>
  <BreadcrumbSeparator />
  <BreadcrumbItem><BreadcrumbLink Href="/docs">Docs</BreadcrumbLink></BreadcrumbItem>
  <BreadcrumbSeparator />
  <BreadcrumbItem><BreadcrumbPage>Components</BreadcrumbPage></BreadcrumbItem>
 </BreadcrumbList>
</Breadcrumb>
```

### Pagination
```razor
<Pagination TotalPages="@totalPages" @bind-CurrentPage="currentPage"
ShowFirstLast="true" MaxVisiblePages="5" />
```

### Sidebar
```razor
<SidebarProvider>
 <Sidebar>
  <SidebarHeader>Logo / Brand</SidebarHeader>
  <SidebarContent>
<SidebarGroup>
 <SidebarGroupLabel>Navigation</SidebarGroupLabel>
 <SidebarGroupContent>
  <SidebarMenu>
<SidebarMenuItem>
 <SidebarMenuButton Href="/dashboard">
  <LucideIcon Name="home" Size="16" />
  <span>Dashboard</span>
 </SidebarMenuButton>
</SidebarMenuItem>
  </SidebarMenu>
 </SidebarGroupContent>
</SidebarGroup>
  </SidebarContent>
  <SidebarFooter>User info / logout</SidebarFooter>
 </Sidebar>
 <SidebarInset>
  @Body
 </SidebarInset>
</SidebarProvider>
```

### NavigationMenu (requires InteractiveAuto/Server render mode)
```razor
<NavigationMenu>
 <NavigationMenuList>
  <NavigationMenuItem>
<NavigationMenuTrigger>Components</NavigationMenuTrigger>
<NavigationMenuContent>
 <ul class="grid gap-3 p-4 md:w-[400px]">
  <li><NavigationMenuLink Href="/docs/button">Button</NavigationMenuLink></li>
 </ul>
</NavigationMenuContent>
  </NavigationMenuItem>
  <NavigationMenuItem>
<NavigationMenuLink Href="/about">About</NavigationMenuLink>
  </NavigationMenuItem>
 </NavigationMenuList>
</NavigationMenu>
```

### Menubar
```razor
<Menubar>
 <MenubarMenu>
  <MenubarTrigger>File</MenubarTrigger>
  <MenubarContent>
<MenubarItem>New <MenubarShortcut>Ctrl+N</MenubarShortcut></MenubarItem>
<MenubarSeparator />
<MenubarItem>Exit</MenubarItem>
  </MenubarContent>
 </MenubarMenu>
</Menubar>
```

### Command (Command Palette)
```razor
<Command>
 <CommandInput Placeholder="Search..." />
 <CommandList>
  <CommandEmpty>No results found.</CommandEmpty>
  <CommandGroup Heading="Actions">
<CommandItem Value="new" OnSelect="@HandleNew">
 <LucideIcon Name="plus" Size="16" />
 <span>New File</span>
 <CommandShortcut>Ctrl+N</CommandShortcut>
</CommandItem>
  </CommandGroup>
 </CommandList>
</Command>
```

### ResponsiveNav
```razor
<ResponsiveNav>
 <NavBrand Href="/">MyApp</NavBrand>
 <NavItems>
  <NavLink Href="/features">Features</NavLink>
  <NavLink Href="/pricing">Pricing</NavLink>
 </NavItems>
 <NavActions>
  <Button>Sign In</Button>
 </NavActions>
</ResponsiveNav>
```

---

## Overlays

### Dialog
```razor
<Dialog @bind-Open="isOpen">
 <DialogTrigger AsChild>
  <Button>Open Dialog</Button>
 </DialogTrigger>
 <DialogContent>
  <DialogHeader>
<DialogTitle>Dialog Title</DialogTitle>
<DialogDescription>Description text.</DialogDescription>
  </DialogHeader>
  <p>Dialog body content.</p>
  <DialogFooter>
<Button Variant="ButtonVariant.Outline" OnClick="@(() => isOpen = false)">Cancel</Button>
<Button OnClick="@Confirm">Confirm</Button>
  </DialogFooter>
 </DialogContent>
</Dialog>
```

### AlertDialog
```razor
<AlertDialog @bind-Open="showAlert">
 <AlertDialogTrigger AsChild>
  <Button Variant="ButtonVariant.Destructive">Delete</Button>
 </AlertDialogTrigger>
 <AlertDialogContent>
  <AlertDialogHeader>
<AlertDialogTitle>Are you sure?</AlertDialogTitle>
<AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
  </AlertDialogHeader>
  <AlertDialogFooter>
<AlertDialogCancel>Cancel</AlertDialogCancel>
<AlertDialogAction OnClick="@Delete">Delete</AlertDialogAction>
  </AlertDialogFooter>
 </AlertDialogContent>
</AlertDialog>
```

### Sheet (Slide-out Panel)
```razor
<Sheet @bind-Open="sheetOpen" Side="SheetSide.Right">
 <SheetTrigger AsChild>
  <Button>Open Sheet</Button>
 </SheetTrigger>
 <SheetContent>
  <SheetHeader>
<SheetTitle>Panel Title</SheetTitle>
<SheetDescription>Panel description.</SheetDescription>
  </SheetHeader>
  <p>Sheet content.</p>
  <SheetFooter>
<Button OnClick="@Save">Save</Button>
  </SheetFooter>
 </SheetContent>
</Sheet>
```
Sides: `Top` | `Right` | `Bottom` | `Left`

### Drawer
```razor
<Drawer @bind-Open="drawerOpen" Side="DrawerSide.Bottom">
 <DrawerTrigger AsChild><Button>Open Drawer</Button></DrawerTrigger>
 <DrawerContent>
  <DrawerHeader><DrawerTitle>Title</DrawerTitle></DrawerHeader>
  <p>Content</p>
  <DrawerFooter><Button OnClick="@Close">Close</Button></DrawerFooter>
 </DrawerContent>
</Drawer>
```

### Popover
```razor
<Popover @bind-Open="popoverOpen">
 <PopoverTrigger AsChild>
  <Button Variant="ButtonVariant.Outline">Settings</Button>
 </PopoverTrigger>
 <PopoverContent Class="w-80">
  <p>Popover content</p>
 </PopoverContent>
</Popover>
```

### HoverCard
```razor
<HoverCard>
 <HoverCardTrigger AsChild>
  <a href="/user">@username</a>
 </HoverCardTrigger>
 <HoverCardContent Class="w-80">
  <div class="flex gap-4">
<Avatar><AvatarFallback>U</AvatarFallback></Avatar>
<p>User bio here</p>
  </div>
 </HoverCardContent>
</HoverCard>
```

### DropdownMenu
```razor
<DropdownMenu>
 <DropdownMenuTrigger AsChild>
  <Button Variant="ButtonVariant.Outline">Options</Button>
 </DropdownMenuTrigger>
 <DropdownMenuContent>
  <DropdownMenuLabel>My Account</DropdownMenuLabel>
  <DropdownMenuSeparator />
  <DropdownMenuItem OnClick="@Profile">Profile</DropdownMenuItem>
  <DropdownMenuItem OnClick="@Settings">Settings</DropdownMenuItem>
  <DropdownMenuSeparator />
  <DropdownMenuItem OnClick="@Logout" Class="text-destructive">Logout</DropdownMenuItem>
 </DropdownMenuContent>
</DropdownMenu>
```

### ContextMenu
```razor
<ContextMenu>
 <ContextMenuTrigger>
  <div class="border rounded p-8">Right-click me</div>
 </ContextMenuTrigger>
 <ContextMenuContent>
  <ContextMenuItem>Copy</ContextMenuItem>
  <ContextMenuItem>Paste</ContextMenuItem>
  <ContextMenuSeparator />
  <ContextMenuItem Class="text-destructive">Delete</ContextMenuItem>
 </ContextMenuContent>
</ContextMenu>

@* Programmatic open at coordinates (3.6.2) *@
<ContextMenu @ref="_ctxMenu">
 <ContextMenuContent>
  <ContextMenuItem>Action</ContextMenuItem>
 </ContextMenuContent>
</ContextMenu>

@code {
 ContextMenu? _ctxMenu;
 // Open programmatically (e.g. on canvas click, virtual list row, etc.)
 async Task OnCanvasClick(MouseEventArgs e) =>
  await _ctxMenu!.OpenAt(e.ClientX, e.ClientY);
}
```
`X` / `Y` parameters on `ContextMenuContent` set a fixed position. `OpenAt(x, y)` opens at runtime coordinates.

### Tooltip
```razor
<TooltipProvider>
 <Tooltip DelayDuration="300">
  <TooltipTrigger AsChild>
<Button Variant="ButtonVariant.Outline" Size="ButtonSize.Icon">
 <LucideIcon Name="info" Size="16" />
</Button>
  </TooltipTrigger>
  <TooltipContent>Helpful information</TooltipContent>
 </Tooltip>
</TooltipProvider>
```

---

## Feedback

### Alert
```razor
<Alert Variant="AlertVariant.Info">
 <Icon><LucideIcon Name="info" Size="16" /></Icon>
 <ChildContent>
  <AlertTitle>Note</AlertTitle>
  <AlertDescription>This is an informational alert.</AlertDescription>
 </ChildContent>
</Alert>
```
Variants: `Default` | `Info` | `Success` | `Warning` | `Destructive`

### Toast
```razor
@inject IToastService ToastService

<Button OnClick="@ShowToast">Show Toast</Button>

@code {
 void ShowToast() => ToastService.Show("Saved successfully!", ToastVariant.Success);
}
```
Variants: `Default` | `Success` | `Error` | `Warning` | `Info`

### Progress
```razor
<Progress Value="@progress" Max="100" Class="w-full" />
```

### Spinner
```razor
<Spinner Size="SpinnerSize.Default" />
```
Sizes: `Sm` | `Default` | `Lg`

---

## Layout

### Accordion
```razor
<Accordion Type="AccordionType.Single" Collapsible="true">
 <AccordionItem Value="item-1">
  <AccordionTrigger>Is it accessible?</AccordionTrigger>
  <AccordionContent>Yes. It adheres to WAI-ARIA design patterns.</AccordionContent>
 </AccordionItem>
 <AccordionItem Value="item-2">
  <AccordionTrigger>Is it styled?</AccordionTrigger>
  <AccordionContent>Yes. Pre-built CSS with shadcn/ui design.</AccordionContent>
 </AccordionItem>
</Accordion>
```
Types: `AccordionType.Single` | `AccordionType.Multiple`

### Tabs (requires interactive render mode)
```razor
<Tabs @bind-Value="activeTab" DefaultValue="account">
 <TabsList>
  <TabsTrigger Value="account">Account</TabsTrigger>
  <TabsTrigger Value="password">Password</TabsTrigger>
 </TabsList>
 <TabsContent Value="account">Account settings...</TabsContent>
 <TabsContent Value="password">Password settings...</TabsContent>
</Tabs>
```

### Collapsible
```razor
<Collapsible @bind-Open="isOpen">
 <CollapsibleTrigger AsChild>
  <Button Variant="ButtonVariant.Ghost">Toggle</Button>
 </CollapsibleTrigger>
 <CollapsibleContent>
  <p>Collapsible content here.</p>
 </CollapsibleContent>
</Collapsible>
```

### Separator
```razor
<Separator />@* horizontal *@
<Separator Orientation="Orientation.Vertical" Class="h-6" />
```

### Resizable
```razor
<ResizablePanelGroup Direction="ResizeDirection.Horizontal">
 <ResizablePanel DefaultSize="50">Left panel</ResizablePanel>
 <ResizableHandle />
 <ResizablePanel DefaultSize="50">Right panel</ResizablePanel>
</ResizablePanelGroup>
```

### ButtonGroup
```razor
<ButtonGroup>
 <Button Variant="ButtonVariant.Outline">Left</Button>
 <Button Variant="ButtonVariant.Outline">Center</Button>
 <Button Variant="ButtonVariant.Outline">Right</Button>
</ButtonGroup>
```

### ThemeSwitcher / DarkModeToggle
```razor
<ThemeSwitcher /> @* Full palette picker *@
<DarkModeToggle />@* Toggle light/dark *@
```

### DarkModeToggle
```razor
<DarkModeToggle />
```
Sun/moon toggle that controls dark mode via `ThemeService`. Self-contained, no parameters needed.

---

## Charts (`@using NeoUI.Blazor.Charts`)

All charts accept `Data`, `Width`, `Height`, and chart-specific configuration.

```razor
@using NeoUI.Blazor.Charts

<AreaChart Data="@chartData" XField="Month" YFields='new[]{"Revenue","Expenses"}' />
<BarChart Data="@chartData" XField="Month" YFields='new[]{"Sales"}' Orientation="ChartOrientation.Vertical" />
<LineChart Data="@chartData" XField="Month" YFields='new[]{"Users"}' />

@* Pie with custom slice colors (3.6.3) *@
<PieChart Data="@pieData" TData="Slice">
 <ChartTooltip />
 <Pie DataKey="value" NameKey="name" Colors="@(new[]{"#6366f1","#f59e0b","#22c55e"})" />
</PieChart>

<ScatterChart Data="@scatterData" XField="X" YField="Y" />
<RadarChart Data="@radarData" CategoryField="Subject" ValueFields='new[]{"Score"}' />
<ComposedChart Data="@composedData" XField="Month">
 <BarSeries YField="Revenue" />
 <LineSeries YField="Trend" />
</ComposedChart>

@* Funnel / conversion pipeline *@
<FunnelChart Data="@funnelData" TData="Stage">
 <ChartTooltip />
 <Funnel DataKey="count" NameKey="stage" Sort="FunnelSort.Descending" />
</FunnelChart>

@* Gauge — single KPI, multi-tile, or progress ring *@
<GaugeChart>
 <Gauge Value="72" Min="0" Max="100" Title="CPU" ShowPointer="true" />
</GaugeChart>

@* Heatmap — requires XAxis, YAxis, VisualMap *@
<HeatmapChart Data="@heatData" TData="Cell">
 <XAxis DataKey="hour" /><YAxis DataKey="day" />
 <VisualMap Min="0" Max="100" InRange='new[]{"var(--muted)","var(--primary)"}' ShowLegend="true" />
 <ChartTooltip />
 <Heatmap DataKey="value" XKey="hour" YKey="day" />
</HeatmapChart>

@* Candlestick — OHLC financial chart *@
<CandlestickChart Data="@ohlcData" TData="OhlcPoint">
 <XAxis DataKey="date" />
 <ChartTooltip />
 <Candlestick DataKey="open" OpenKey="open" CloseKey="close" HighKey="high" LowKey="low" />
</CandlestickChart>
```

---

## Animation

### Carousel
```razor
<Carousel>
 <CarouselContent>
  <CarouselItem>Slide 1</CarouselItem>
  <CarouselItem>Slide 2</CarouselItem>
  <CarouselItem>Slide 3</CarouselItem>
 </CarouselContent>
 <CarouselPrevious />
 <CarouselNext />
</Carousel>
```

### Motion
```razor
<Motion Preset="MotionPreset.FadeIn" Duration="0.3">
 <div>Animated content</div>
</Motion>
```
20+ presets: `FadeIn`, `FadeOut`, `SlideInLeft`, `SlideInRight`, `SlideInUp`, `SlideInDown`,
`ZoomIn`, `ZoomOut`, `Bounce`, `Pulse`, `Shake`, `Spin`, and more.

### HeightAnimation
```razor
<HeightAnimation Visible="isExpanded">
 <div>Animated height content</div>
</HeightAnimation>
```
Animates height from `0` to `auto` when `Visible` changes. Zero JS required. See `components-full.txt` for full reference.

### PageTransition
```razor
@* In MainLayout.razor *@
<RenderStateProvider>
 <PageTransition EnableSlide="true" Duration="0.3">
  @Body
 </PageTransition>
</RenderStateProvider>
```
Fade (+ optional slide-from-bottom) on page navigation. Requires `RenderStateProvider` ancestor. SSR-safe — no animation during prerender.

### RenderStateProvider
```razor
@* Wrap layout body *@
<RenderStateProvider>
 @Body
</RenderStateProvider>

@* Consume in child components *@
@code {
 [CascadingParameter] public AppRenderContext? RenderContext { get; set; }
 // RenderContext.IsInteractive, .IsHydrating, .IsEnhancedNavigation
}
```
Cascades `AppRenderContext` to children. Required ancestor for `PageTransition`.

---

## DialogService (Programmatic Dialogs)

```csharp
// Program.cs
builder.Services.AddNeoUIComponents(); // includes IDialogService, ILocalizer

// Localization (3.6.4+) -- override built-in English strings at startup
builder.Services.AddNeoUIComponents(loc =>
{
 loc.Set("Combobox.Placeholder", "Waehlen Sie...");
 loc.Set("DataTable.Loading", "Laden...");
 // 70+ keys -- see /components/localization for full key reference
});
// Option B: subclass DefaultLocalizer for .resx / IStringLocalizer<T> integration
// builder.Services.AddScoped<ILocalizer, AppLocalizer>();
```

```razor
@inject IDialogService DialogService

@code {
 async Task ShowConfirm()
 {
  var result = await DialogService.ShowAsync<ConfirmDialog>(
title: "Confirm Delete",
parameters: new() { ["Message"] = "Delete this item?" });

  if (result.Confirmed)
await DeleteItem();
 }
}
```

### DialogHost
```razor
@* In MainLayout.razor — place once *@
<DialogHost />

@* In a component *@
@inject IDialogService DialogService

@code {
 async Task Delete()
 {
  var result = await DialogService.ShowAsync(new DialogOptions
  {
   Title = "Delete Item",
   Message = "Are you sure?",
   Buttons = DialogButtons.YesNo,
   Variant = DialogVariant.Destructive,
   Icon = "trash-2"
  });
  if (result == DialogResult.Confirmed)
   await DeleteAsync();
 }
}
```
`DialogButtons`: `OkOnly` | `OkCancel` | `YesNo` | `YesNoCancel`
`DialogVariant`: `Default` | `Destructive` | `Warning` | `Success` | `Info`

---

## New in 3.5 -- Advanced Components

### Timeline
```razor
<Timeline>
 <TimelineItem Status="TimelineStatus.Completed" Title="Order Placed" Time="Jan 1" />
 <TimelineItem Status="TimelineStatus.Active"    Title="Processing"   Time="Jan 2" />
 <TimelineItem Status="TimelineStatus.Pending"   Title="Shipped"      Time="Pending" />
</Timeline>

@* With custom icons and content *@
<Timeline Align="TimelineAlign.Left">
 <TimelineItem Status="TimelineStatus.Completed">
  <IconContent><LucideIcon Name="check-circle" Size="16" /></IconContent>
  <ChildContent>
<TimelineHeader>
 <TimelineTitle>Deployment complete</TimelineTitle>
 <TimelineTime>2 hours ago</TimelineTime>
</TimelineHeader>
<TimelineDescription>v3.5.0 deployed to production.</TimelineDescription>
  </ChildContent>
 </TimelineItem>
</Timeline>
```
Statuses: `Pending` | `Active` | `Completed`
Aligns: `Left` | `Right` | `Alternate`
ConnectorStyles: `Solid` | `Dashed` | `Dotted`
Sizes: `Small` | `Default` | `Large`

---

### TreeView
```razor
<TreeView TItem="FileNode"
          Items="@rootNodes"
          ChildrenSelector="n => n.Children"
          TextSelector="n => n.Name"
          IconSelector="n => n.IsFolder ? &quot;folder&quot; : &quot;file&quot;"
          SelectionMode="TreeSelectionMode.Single"
          @bind-SelectedItem="selectedNode" />

@* Multi-select with tri-state checkboxes *@
<TreeView TItem="FileNode"
          Items="@rootNodes"
          ChildrenSelector="n => n.Children"
          TextSelector="n => n.Name"
          SelectionMode="TreeSelectionMode.Multiple"
          PropagateChecks="true"
          ShowLines="true"
          @bind-SelectedItems="checkedNodes" />
```
SelectionModes: `None` | `Single` | `Multiple`

---

### DataView
```razor
<DataView TItem="Product" Items="@products" PageSize="12">
 <DataViewColumn TItem="Product" Field="@nameof(Product.Name)"     Sortable="true" Filterable="true" />
 <DataViewColumn TItem="Product" Field="@nameof(Product.Category)" Sortable="true" />
 <DataViewColumn TItem="Product" Field="@nameof(Product.Price)"    Sortable="true" />
 <ListTemplate Context="p">
  <div class="flex gap-3 p-3 border rounded">
   <span>@p.Name</span><span class="ml-auto">@p.Price.ToString("C")</span>
  </div>
 </ListTemplate>
 <GridTemplate Context="p">
  <Card><CardContent>@p.Name</CardContent></Card>
 </GridTemplate>
</DataView>

@* Responsive grid with min column width (3.6.1) -- overrides GridColumns *@
<DataView TItem="Product" Items="@products" GridColumnMinWidth="250px">
 <GridTemplate Context="p"><Card><CardContent>@p.Name</CardContent></Card></GridTemplate>
</DataView>

@* Server-side infinite scroll *@
<DataView TItem="Order" OnLoadMore="@LoadMoreOrders" PageSize="20">
 <DataViewColumn TItem="Order" Field="@nameof(Order.Id)" />
 <ListTemplate Context="o"><div>@o.Id</div></ListTemplate>
</DataView>
```
SelectionModes: `None` | `Single` | `Multiple`
Layouts: `List` | `Grid`

---

### DynamicForm
```razor
@* Define a schema *@
@code {
 private FormSchema _schema = new()
 {
  Fields =
  [
   new FormFieldDefinition { Key = "name",  Label = "Full Name", Type = FieldType.Text,   IsRequired = true },
   new FormFieldDefinition { Key = "email", Label = "Email",     Type = FieldType.Email,  IsRequired = true },
   new FormFieldDefinition { Key = "role",  Label = "Role",      Type = FieldType.Select,
    Options = [new("admin","Admin"), new("user","User")] },
  ]
 };
 private Dictionary<string, object?> _values = new();
}

<DynamicForm Schema="@_schema"
             @bind-Values="_values"
             OnFieldChanged="@((e) => Console.WriteLine($&quot;{e.Key} = {e.Value}&quot;))" />
```
FieldTypes: `Text` | `Email` | `Password` | `Number` | `Date` | `DateRange` | `Select` | `MultiSelect` |
`Checkbox` | `Switch` | `Slider` | `SliderRange` | `Textarea` | `Rating` | `ColorPicker` |
`TimePicker` | `FileUpload` | `InputOtp` | `MaskedInput` | `CurrencyInput` | `RichText` | `MarkdownEditor`
FormLayouts: `SingleColumn` | `TwoColumn`

---

### TagInput
```razor
<TagInput @bind-Tags="tags" Placeholder="Add tag..." />

@* With async suggestions *@
<TagInput @bind-Tags="tags"
          OnSearchSuggestions="@SearchTags"
          AddTrigger="TagInputTrigger.Enter | TagInputTrigger.Comma"
          MaxTags="10"
          AllowDuplicates="false"
          Clearable="true" />

@code {
 private List<string> tags = new();
 private async Task<IEnumerable<string>> SearchTags(string q) =>
  await TagService.SearchAsync(q);
}
```
Variants: `Default` | `Outlined` | `Ghost`
Triggers (flags): `Enter` | `Comma` | `Tab` | `Space` | `Blur`

---

### SplitButton
```razor
<SplitButton Label="Save" OnPrimaryClick="@Save">
 <SplitButtonItem OnClick="@SaveDraft">Save as Draft</SplitButtonItem>
 <SplitButtonItem OnClick="@SaveTemplate">Save as Template</SplitButtonItem>
 <SplitButtonSeparator />
 <SplitButtonItem OnClick="@Discard">Discard</SplitButtonItem>
</SplitButton>

@* With variant and icon *@
<SplitButton Label="Deploy" Variant="ButtonVariant.Default" Size="ButtonSize.Default">
 <Icon><LucideIcon Name="rocket" Size="14" /></Icon>
 <SplitButtonItem OnClick="@DeployStaging">Deploy to Staging</SplitButtonItem>
 <SplitButtonItem OnClick="@DeployProd">Deploy to Production</SplitButtonItem>
</SplitButton>
```

---

## New in 3.5 -- New Chart Types

All new charts use `@using NeoUI.Blazor.Charts`.

### CandlestickChart
```razor
<CandlestickChart Data="@ohlcData" TData="OhlcPoint">
 <XAxis DataKey="date" />
 <ChartTooltip />
 <Candlestick DataKey="open"
              OpenKey="open" CloseKey="close" HighKey="high" LowKey="low"
              RisingColor="#22c55e" FallingColor="#ef4444" />
</CandlestickChart>
```

### FunnelChart
```razor
<FunnelChart Data="@funnelData" TData="Stage">
 <ChartTooltip />
 <Funnel DataKey="count" NameKey="stage" Sort="FunnelSort.Descending" Align="FunnelAlign.Center" />
</FunnelChart>

@* Custom color palette (3.6.3) *@
<FunnelChart Data="@funnelData" TData="Stage">
 <Funnel DataKey="count" NameKey="stage"
         Colors="@(new[]{"#6366f1","#8b5cf6","#a78bfa","#c4b5fd","#ddd6fe"})" />
</FunnelChart>
```
Sorts: `Descending` | `Ascending` | `None`
`Colors` cycles through the array for each segment; `null` = auto `--chart-1…5` palette.

### GaugeChart
```razor
@* Single KPI *@
<GaugeChart Data="@_kpi" TData="Metric">
 <Gauge DataKey="value" Name="Score" Min="0" Max="100" ShowPointer="true" ShowDetail="true" />
</GaugeChart>

@* Multi-tile: each Gauge series drives one tile *@
<GaugeChart Data="@_metrics" TData="Metric">
 <ChartTooltip />
 <Gauge DataKey="value" Name="CPU"    Min="0" Max="100" ShowProgress="true" ShowDetail="true" />
 <Gauge DataKey="value" Name="Memory" Min="0" Max="100" ShowProgress="true" ShowDetail="true" />
 <Gauge DataKey="value" Name="Disk"   Min="0" Max="100" ShowProgress="true" ShowDetail="true" />
</GaugeChart>

@* Progress ring *@
<GaugeChart Data="@_kpi" TData="Metric">
 <Gauge DataKey="value" Name="Progress" Min="0" Max="100"
        StartAngle="90" EndAngle="-270" ShowPointer="false" SplitNumber="0"
        ShowProgress="true" ShowDetail="true" DetailFormatter="{value}%" />
</GaugeChart>

@code { record Metric(string name, double value); }
```


### HeatmapChart
```razor
<HeatmapChart Data="@heatData" TData="Cell">
 <XAxis DataKey="hour"><AxisLabel Color="var(--muted-foreground)" /></XAxis>
 <YAxis DataKey="day"><AxisLabel Color="var(--muted-foreground)" /></YAxis>
 <VisualMap Min="0" Max="100" InRange='new[]{"var(--muted)","var(--primary)"}' ShowLegend="true" />
 <ChartTooltip />
 <Heatmap DataKey="value" XKey="hour" YKey="day" />
</HeatmapChart>

@code { record Cell(int hour, int day, int value); }
```

### RadialBarChart
```razor
<RadialBarChart Data="@radialData">
 <RadialBar DataKey="Value" NameKey="Category" InnerRadius="30%" OuterRadius="80%" />
 <ChartLegend />
 <ChartTooltip />
</RadialBarChart>
```


---

## New in 3.8 -- SelectionIndicator + Sortable

### SelectionIndicator

Spring-animated indicator that slides between active items (e.g. tabs, toggle groups).

```razor
<Tabs @bind-Value="tab">
    <TabsList>
        <SelectionIndicator />
        <TabsTrigger Value="a">Alpha</TabsTrigger>
        <TabsTrigger Value="b">Beta</TabsTrigger>
    </TabsList>
    ...
</Tabs>
```

Parameters: `Selector` (string, default `[data-state=active]`), `Hover` (bool), `Class` (string?).
CSS variables: `--si-duration`, `--si-easing`, `--si-height`.
Works with: Tabs, ToggleGroup, RadioGroup, Pagination, and any custom markup using `data-state=active`.

### Sortable + Cross-list Drag-and-Drop

```razor
<Sortable @bind-Items="items" TItem="MyItem">
    <SortableItem Context="item">
        <SortableContent>@item.Name</SortableContent>
    </SortableItem>
</Sortable>
```

Cross-list DnD: share `Group` name across multiple `Sortable` instances.

```razor
<Sortable @bind-Items="listA" TItem="MyItem" Group="shared"
          OnItemTransferredOut="HandleOut" OnItemTransferredIn="HandleIn">
    <SortableItem Context="item"><SortableContent>@item.Name</SortableContent></SortableItem>
</Sortable>
<Sortable @bind-Items="listB" TItem="MyItem" Group="shared"
          OnItemTransferredOut="HandleOut" OnItemTransferredIn="HandleIn">
    <SortableItem Context="item"><SortableContent>@item.Name</SortableContent></SortableItem>
</Sortable>
```

`SortableContent` exposes `data-[state=over]` attribute for visual drag-over feedback.

---

## New in 3.9 -- Mobile Components

### AppBar

Mobile top app bar with optional back button and right-side content slot.

```razor
<AppBar Title="Settings" OnBack="@GoBack">
    <RightContent><Button Size="ButtonSize.Icon" Variant="ButtonVariant.Ghost"><LucideIcon Name="ellipsis-vertical" /></Button></RightContent>
</AppBar>
```

### BottomNav + BottomNavItem

Persistent mobile tab bar pinned to the bottom of the screen.

```razor
<BottomNav @bind-ActiveTab="activeTab">
    <BottomNavItem Value="home" Icon="home" Label="Home" />
    <BottomNavItem Value="search" Icon="search" Label="Search" BadgeCount="3" />
    <BottomNavItem Value="profile" Icon="user" Label="Profile" />
</BottomNav>
```

### NotificationBadge

Wraps any element and overlays a count badge in the top-right corner.

```razor
<NotificationBadge Count="5" Variant="NotificationBadgeVariant.Destructive">
    <LucideIcon Name="bell" />
</NotificationBadge>
```

Use `Dot="true"` for a dot indicator without a count. `ShowZero="true"` displays the badge when Count is 0.

### QuantityStepper

Circular +/- quantity control. `DestructiveAtMin` replaces the minus button with a trash icon at the minimum value.

```razor
<QuantityStepper @bind-Value="qty" Min="1" Max="10"
                 DestructiveAtMin="true" OnDestructiveAction="@RemoveItem" />
```

### SectionHeader

Title row with an optional "view all" chevron and separator line.

```razor
<SectionHeader Title="Featured Items" OnViewAll="@ViewAll" ShowSeparator="true" />
```

### ScreenTransition

Animated wrapper for multi-screen navigation. Changing `Key` triggers the entrance animation.

```razor
<ScreenTransition Key="@currentScreen" Direction="ScreenTransitionDirection.Push">
    @* current screen content *@
</ScreenTransition>
```

`ScreenTransitionDirection` enum: `None` (no animation) | `Tab` (fade-in) | `Push` (slide from right) | `Pop` (slide from left)

---

## New in 3.9 -- Component Enhancements

- **Carousel:** `DotsPosition` (`CarouselDotsPosition`: Bottom/Top/Left/Right, default Bottom). Drag-click suppression prevents accidental navigation.
- **Drawer:** `DrawerContent` gains `SnapPoints` (float[]?), `SnapIndex` (@bind, int), `ShowHandle` (bool). Bottom direction only.
- **Select:** `Presentation` (`SelectPresentation`: Popover/BottomSheet) -- BottomSheet opens options in a bottom Drawer.
- **Separator:** `LineStyle` (`SeparatorStyle`: Solid/Dashed/Dotted, default Solid).
- **ToggleGroup:** `Scrollable` (bool, false -- horizontal scroll strip), `Required` (bool, false -- prevents deselecting the active item).
- **BadgeIcon:** New sub-component -- renders an icon inside a Badge chip.
  ```razor
  <BadgeIcon Variant="BadgeVariant.Destructive"><LucideIcon Name="x" /></BadgeIcon>
  ```
- **ScrollArea:** Non-horizontal instances no longer force `width:100%` on the inner container.

---

## New in 4.0 -- AppProvider + Theme v2

### AppProvider

Required wrapper in `MainLayout.razor` (v4.0.0+). Initializes ThemeService, restores the persisted theme from localStorage, and broadcasts the active `StyleVariant` as a CascadingValue to all child components.

```razor
@* MainLayout.razor *@
<AppProvider>
    @Body
    <ToastViewport />
    <SpotlightCommandPalette />
    <DialogHost />
</AppProvider>
```

Theme v2 adds 6 new dimensions on top of base/primary colors: **StyleVariant** (visual style preset), **RadiusPreset** (named radius override), **FontPreset** (font pairing), **MenuColor** (floating surface treatment), **MenuAccent** (hover intensity), and **ThemePreset** (bundles all 8 dimensions). BaseColor expands to 10 values (5 new chromatic neutrals). See `theming.txt` for the complete reference.

==================================================================
FILE: components-full.txt
URL:  https://neoui.io/llms/components-full.txt
==================================================================

# Comprehensive Component Reference

**NeoUI** - A comprehensive UI component library for Blazor inspired by shadcn/ui

Version: 3.6.7  
Target Framework: .NET 10+  
Last Updated: 2026-03-18

> **Import Note (NeoUI 3.x):** Add `@using NeoUI.Blazor` to `_Imports.razor` once to access all
> components globally. Chart components additionally require `@using NeoUI.Blazor.Charts`.
> Service interfaces (`IToastService`, `IDialogService`, etc.) require `@using NeoUI.Blazor.Services`.

---

## 📋 Table of Contents

### Styled Components (100+)

- [Accordion](#accordion)
- [Alert](#alert)
- [AlertDialog](#alertdialog)
- [AspectRatio](#aspectratio)
- [Avatar](#avatar)
- [Badge](#badge)
- [Breadcrumb](#breadcrumb)
- [Button](#button)
- [ButtonGroup](#buttongroup)
- [Calendar](#calendar)
- [Card](#card)
- [Carousel](#carousel)
- [Chart](#chart)
- [CandlestickChart](#candlestickchart)
- [Checkbox](#checkbox)
- [Collapsible](#collapsible)
- [ColorPicker](#colorpicker)
- [Combobox](#combobox)
- [Command](#command)
- [ContextMenu](#contextmenu)
- [CurrencyInput](#currencyinput)
- [DataGrid](#datagrid)
- [DataTable](#datatable)
- [DataView](#dataview)
- [DarkModeToggle](#darkmodetoggle)
- [DatePicker](#datepicker)
- [DateRangePicker](#daterangepicker)
- [Dialog](#dialog)
- [DialogHost](#dialoghost)
- [Drawer](#drawer)
- [DropdownMenu](#dropdownmenu)
- [DynamicForm](#dynamicform)
- [Empty](#empty)
- [Field](#field)
- [FileUpload](#fileupload)
- [FilterBuilder](#filterbuilder)
- [FunnelChart](#funnelchart)
- [GaugeChart](#gaugechart)
- [HeightAnimation](#heightanimation)
- [HeatmapChart](#heatmapchart)
- [HoverCard](#hovercard)
- [Input](#input)
- [InputGroup](#inputgroup)
- [InputOtp](#inputotp)
- [Item](#item)
- [Kbd](#kbd)
- [Label](#label)
- [MarkdownEditor](#markdowneditor)
- [MaskedInput](#maskedinput)
- [Menubar](#menubar)
- [Motion](#motion)
- [MultiSelect](#multiselect)
- [NativeSelect](#nativeselect)
- [NavigationMenu](#navigationmenu)
- [NumericInput](#numericinput)
- [Pagination](#pagination)
- [PageTransition](#pagetransition)
- [Popover](#popover)
- [Progress](#progress)
- [RadioGroup](#radiogroup)
- [RangeSlider](#rangeslider)
- [Rating](#rating)
- [Resizable](#resizable)
- [RenderStateProvider](#renderstateprovider)
- [ResponsiveNav](#responsivenav)
- [RichTextEditor](#richtexteditor)
- [ScrollArea](#scrollarea)
- [Select](#select)
- [Separator](#separator)
- [Sheet](#sheet)
- [Sidebar](#sidebar)
- [Skeleton](#skeleton)
- [Slider](#slider)
- [Spinner](#spinner)
- [SplitButton](#splitbutton)
- [Switch](#switch)
- [Tabs](#tabs)
- [TagInput](#taginput)
- [Textarea](#textarea)
- [ThemeSwitcher](#themeswitcher)
- [TimePicker](#timepicker)
- [Timeline](#timeline)
- [Toast](#toast)
- [Toggle](#toggle)
- [ToggleGroup](#togglegroup)
- [Tooltip](#tooltip)
- [TreeView](#treeview)
- [Typography](#typography)

---

## 🎨 Styled Components

Pre-styled components with shadcn/ui design, built on top of primitives.

### Accordion

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Vertically stacked collapsible content sections with smooth animations. Supports single or multiple panel expansion with keyboard navigation.

**Components & Parameters:**

#### `Accordion`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render within the accordion. Should include AccordionItem components. |
| `Value` | `HashSet<string>?` |  | Controls which items are open (controlled mode). |
| `ValueChanged` | `EventCallback<HashSet<string>>` |  | Event callback invoked when the open items change. |
| `DefaultValue` | `HashSet<string>?` |  | Default open items when in uncontrolled mode. |
| `OnValueChange` | `EventCallback<HashSet<string>>` |  | Event callback invoked when the open items change. |
| `Type` | `AccordionType` | `AccordionType.Single` | Type of accordion (single or multiple). |
| `Collapsible` | `bool` | `false` | Whether items can be collapsed when in single mode. |
| `Class` | `string?` |  | Additional CSS classes to apply to the accordion. |

#### `AccordionContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ForceMount` | `bool` | `true` | Whether to force mount the content even when closed. When true (default), enables smooth CSS animations. When false, content unmounts when closed (no animation, lower memory). |
| `ChildContent` | `RenderFragment?` |  | The child content to render when the item is open. |
| `Class` | `string?` |  | Additional CSS classes to apply to the content. |

#### `AccordionItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Disabled` | `bool` |  | Whether this accordion item is disabled. |
| `ChildContent` | `RenderFragment?` |  | The child content to render within the accordion item. |
| `Class` | `string?` |  | Additional CSS classes to apply to the accordion item. |

#### `AccordionTrigger`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render within the trigger. |
| `Class` | `string?` |  | Additional CSS classes to apply to the trigger. |

**Basic Usage:**
```razor
<Accordion>
 <AccordionItem Value="item-1">
  <AccordionTrigger>Is it accessible?</AccordionTrigger>
  <AccordionContent>
Yes. It adheres to WCAG 2.1 AA standards.
  </AccordionContent>
 </AccordionItem>
 
 <AccordionItem Value="item-2">
  <AccordionTrigger>Is it styled?</AccordionTrigger>
  <AccordionContent>
Yes. It comes with default shadcn/ui styles.
  </AccordionContent>
 </AccordionItem>
</Accordion>
```

---

### Alert

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Status messages and callouts with multiple variants (default, destructive). Used to display important information to users.

**Components & Parameters:**

#### `Alert`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Variant` | `AlertVariant` | `AlertVariant.Default` | Gets or sets the visual style variant of the alert. Controls the color scheme and visual appearance using CSS custom properties. Default value is . |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the alert. Custom classes are appended after the component's base classes, allowing for style overrides and extensions. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the alert. Typically contains AlertTitle, AlertDescription, and optionally an icon. For accessibility, ensure meaningful content is provided. |

#### `AlertDescription`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the alert description. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the alert description. |

#### `AlertTitle`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the alert title. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the alert title. |

**Basic Usage:**
```razor
@* Default alert *@
<Alert>
 <AlertTitle>Note</AlertTitle>
 <AlertDescription>This is an informational message.</AlertDescription>
</Alert>

@* Destructive alert *@
<Alert Variant="AlertVariant.Destructive">
 <AlertTitle>Error</AlertTitle>
 <AlertDescription>Something went wrong. Please try again.</AlertDescription>
</Alert>

@* With icon *@
<Alert>
 <LucideIcon Name="info" Size="16" />
 <AlertTitle>Information</AlertTitle>
 <AlertDescription>Check your email for confirmation.</AlertDescription>
</Alert>
```

---

### AlertDialog

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Modal dialog for critical confirmations requiring user action. Prevents accidental destructive actions with explicit confirm/cancel buttons.

**Components & Parameters:**

#### `AlertDialog`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render within the alert dialog. |
| `Open` | `bool?` |  | Controls whether the alert dialog is open (controlled mode). When null, the dialog manages its own state (uncontrolled mode). |
| `OpenChanged` | `EventCallback<bool>` |  | Event callback invoked when the open state changes. Use with @bind-Open for two-way binding. |
| `DefaultOpen` | `bool` | `false` | Default open state when in uncontrolled mode. |
| `OnOpenChange` | `EventCallback<bool>` |  | Event callback invoked when the dialog open state changes. |

#### `AlertDialogAction`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render as the action button. |

#### `AlertDialogCancel`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render as the cancel button. |

#### `AlertDialogContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render inside the alert dialog. |
| `Class` | `string?` |  | Additional CSS classes to apply to the alert dialog content. |
| `CloseOnEscape` | `bool` | `true` | Whether the alert dialog can be closed with the Escape key. Default is true for accessibility. |

#### `AlertDialogDescription`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  |  |
| `ChildContent` | `RenderFragment?` |  |  |

#### `AlertDialogFooter`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  |  |
| `ChildContent` | `RenderFragment?` |  |  |

#### `AlertDialogHeader`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  |  |
| `ChildContent` | `RenderFragment?` |  |  |

#### `AlertDialogTitle`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  |  |
| `ChildContent` | `RenderFragment?` |  |  |

#### `AlertDialogTrigger`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render as the trigger. |

**Basic Usage:**
```razor
<AlertDialog>
 <AlertDialogTrigger AsChild>
  <Button Variant="ButtonVariant.Destructive">Delete Account</Button>
 </AlertDialogTrigger>
 <AlertDialogContent>
  <AlertDialogHeader>
<AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
<AlertDialogDescription>
 This action cannot be undone. This will permanently delete your account.
</AlertDialogDescription>
  </AlertDialogHeader>
  <AlertDialogFooter>
<AlertDialogCancel AsChild>
 <Button Variant="ButtonVariant.Outline">Cancel</Button>
</AlertDialogCancel>
<AlertDialogAction AsChild>
 <Button Variant="ButtonVariant.Destructive">Delete</Button>
</AlertDialogAction>
  </AlertDialogFooter>
 </AlertDialogContent>
</AlertDialog>
```

---

### AspectRatio

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Display content within a desired width/height ratio. Maintains consistent proportions across different screen sizes.

**Components & Parameters:**

#### `AspectRatio`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render within the aspect ratio container. |
| `Ratio` | `double` | `1.0` | The desired aspect ratio (width / height). Default is 1 (square). Common values: 16/9 = 1.778, 4/3 = 1.333, 1/1 = 1. |
| `Class` | `string?` |  | Additional CSS classes to apply to the container. |

**Basic Usage:**
```razor
@* 16:9 video container *@
<AspectRatio Ratio="16.0 / 9.0">
 <img src="/images/placeholder.jpg" alt="Photo" class="rounded-md object-cover" />
</AspectRatio>

@* Square 1:1 *@
<AspectRatio Ratio="1">
 <img src="/images/avatar.jpg" alt="Avatar" class="rounded-md object-cover" />
</AspectRatio>

@* 4:3 classic *@
<AspectRatio Ratio="4.0 / 3.0">
 <iframe src="https://example.com" class="w-full h-full"></iframe>
</AspectRatio>
```

---

### Avatar

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
User avatars with image fallback support. Displays user profile pictures with automatic fallback to initials or placeholder.

**Components & Parameters:**

#### `Avatar`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to render inside the avatar. Typically contains AvatarImage and AvatarFallback components. The first successfully loaded content will be displayed. |
| `Size` | `AvatarSize` | `AvatarSize.Default` | Gets or sets the size variant of the avatar. Controls the dimensions and font-size of the avatar. Default value is . |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the avatar container. Custom classes are appended after the component's base classes, allowing for style overrides and extensions. |

#### `AvatarFallback`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to render as fallback. Typically contains: - User initials (e.g., "JD" for John Doe) - An icon component (e.g., LucideIcon with "user") - Custom markup or components Content is automatically centered within the avatar. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the fallback container. Custom classes are appended after the component's base classes, allowing for style overrides such as custom background colors. |

#### `AvatarImage`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Source` | `string?` |  | Gets or sets the URL of the image to display. Should be a valid image URL. If the image fails to load, the component will hide and defer to AvatarFallback. |
| `Alt` | `string?` |  | Gets or sets the alternative text for the image. Essential for accessibility. Screen readers use this to describe the image to visually impaired users. Should describe who the avatar represents (e.g., "John Doe", "User avatar"). |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the image. Custom classes are appended after the component's base classes. |

**Basic Usage:**
```razor
@* Avatar with image *@
<Avatar>
 <AvatarImage Src="/images/avatar.jpg" Alt="User Name" />
 <AvatarFallback>UN</AvatarFallback>
</Avatar>

@* Avatar with fallback initials *@
<Avatar>
 <AvatarFallback>JD</AvatarFallback>
</Avatar>

@* Avatar group *@
<div class="flex -space-x-4">
 <Avatar>
  <AvatarImage Src="/images/user1.jpg" Alt="User 1" />
  <AvatarFallback>U1</AvatarFallback>
 </Avatar>
 <Avatar>
  <AvatarImage Src="/images/user2.jpg" Alt="User 2" />
  <AvatarFallback>U2</AvatarFallback>
 </Avatar>
</div>
```

---

### Badge

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Status badges and labels with multiple variants. Used to highlight status, categories, or counts.

**Components & Parameters:**

#### `Badge`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Variant` | `BadgeVariant` | `BadgeVariant.Default` | Gets or sets the visual style variant of the badge. Controls the color scheme and visual appearance using CSS custom properties. Default value is . |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the badge. Custom classes are appended after the component's base classes, allowing for style overrides and extensions. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the badge. Typically contains short text (1-2 words) or a small number. For accessibility, ensure the content is meaningful. |

**Basic Usage:**
```razor
@* Default badge *@
<Badge>Default</Badge>

@* Variant badges *@
<Badge Variant="BadgeVariant.Secondary">Secondary</Badge>
<Badge Variant="BadgeVariant.Destructive">Destructive</Badge>
<Badge Variant="BadgeVariant.Outline">Outline</Badge>

@* With icon *@
<Badge>
 <LucideIcon Name="check" Size="12" />
 Verified
</Badge>
```

---

### Breadcrumb

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Hierarchical navigation with customizable separators. Shows current location within site hierarchy.

**Components & Parameters:**

#### `Breadcrumb`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `AriaLabel` | `string` | `"breadcrumb"` | Gets or sets the aria-label for the breadcrumb navigation. Provides accessible label for screen readers. Default value is "breadcrumb". |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the breadcrumb. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the breadcrumb. |

#### `BreadcrumbEllipsis`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the breadcrumb ellipsis. |

#### `BreadcrumbItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the breadcrumb item. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the breadcrumb item. |

#### `BreadcrumbLink`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Href` | `string?` |  | Gets or sets the href attribute for the link. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the breadcrumb link. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the breadcrumb link. |

#### `BreadcrumbList`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the breadcrumb list. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the breadcrumb list. |

#### `BreadcrumbPage`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the breadcrumb page. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the breadcrumb page. |

#### `BreadcrumbSeparator`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the breadcrumb separator. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets custom content for the separator. If not provided, a default chevron icon is used. |

**Basic Usage:**
```razor
<Breadcrumb>
 <BreadcrumbList>
  <BreadcrumbItem>
<BreadcrumbLink Href="/">Home</BreadcrumbLink>
  </BreadcrumbItem>
  <BreadcrumbSeparator />
  <BreadcrumbItem>
<BreadcrumbLink Href="/products">Products</BreadcrumbLink>
  </BreadcrumbItem>
  <BreadcrumbSeparator />
  <BreadcrumbItem>
<BreadcrumbPage>Product Details</BreadcrumbPage>
  </BreadcrumbItem>
 </BreadcrumbList>
</Breadcrumb>
```

---

### Button

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Interactive button component with multiple variants (default, destructive, outline, secondary, ghost, link) and sizes. Supports icons, disabled states, and full keyboard navigation.

**Components & Parameters:**

#### `Button`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Variant` | `ButtonVariant` | `ButtonVariant.Default` | Gets or sets the visual style variant of the button. Controls the color scheme and visual appearance using CSS custom properties. Default value is . |
| `Size` | `ButtonSize` | `ButtonSize.Default` | Gets or sets the size of the button. Controls padding, font size, and overall dimensions. Default value is . All sizes maintain minimum touch target sizes (44x44px) for accessibility. |
| `Type` | `ButtonType` | `ButtonType.Button` | Gets or sets the HTML button type attribute. Controls form submission behavior when button is inside a form. Default value is  to prevent accidental form submissions. |
| `Disabled` | `bool` |  | Gets or sets whether the button is disabled. When disabled: - Button cannot be clicked or focused - Opacity is reduced (via disabled:opacity-50 Tailwind class) - Pointer events are disabled (via disabled:pointer-events-none) - aria-disabled attribute is set to true |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the button. Custom classes are appended after the component's base classes, allowing for style overrides and extensions. |
| `OnClick` | `EventCallback<MouseEventArgs>` |  | Gets or sets the callback invoked when the button is clicked. The event handler receives a  parameter with click details. If the button is disabled, this callback will not be invoked. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the button. Can contain text, icons, or any other Blazor markup. For icon-only buttons, use  and provide an aria-label. |
| `AriaLabel` | `string?` |  | Gets or sets the ARIA label for the button. Required for icon-only buttons to provide accessible text for screen readers. Optional for buttons with text content. |
| `Icon` | `RenderFragment?` |  | Gets or sets the icon to display in the button. Can be any RenderFragment (SVG, icon font, image). Position is controlled by . Automatically adds RTL-aware spacing between icon and text. |
| `IconPosition` | `IconPosition` | `IconPosition.Start` | Gets or sets the position of the icon relative to the button text. Default value is  (before text in LTR). Automatically adapts to RTL layouts using Tailwind directional utilities. |

**Basic Usage:**
```razor
@* Simple button *@
<Button>Click me</Button>

@* With variant and size *@
<Button Variant="ButtonVariant.Destructive" Size="ButtonSize.Large">
 Delete
</Button>

@* With icon *@
<Button>
 <LucideIcon Name="download" Size="16" />
 Download
</Button>

@* Icon-only button *@
<Button Size="ButtonSize.Icon" AriaLabel="Settings">
 <LucideIcon Name="settings" Size="20" />
</Button>
```

---

### ButtonGroup

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Visually grouped related buttons with connected styling. Groups multiple buttons as a cohesive unit with shared borders.

**Components & Parameters:**

#### `ButtonGroup`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Orientation` | `ButtonGroupOrientation` | `ButtonGroupOrientation.Horizontal` | Gets or sets the orientation of the button group. Controls whether buttons are arranged horizontally (default) or vertically. Default value is . |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the button group. Custom classes are appended after the component's base classes, allowing for style overrides and extensions. |
| `AriaLabel` | `string?` |  | Gets or sets the ARIA label for the button group. Provides an accessible name for the group when role="group" is used. Important for screen reader users to understand the group's purpose. Recommended for button groups that perform a specific function (e.g., "Text formatting", "Email actions"). |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the button group. Typically contains Button components, but can also contain nested ButtonGroup components for creating complex layouts. |

#### `ButtonGroupSeparator`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Orientation` | `SeparatorOrientation` | `SeparatorOrientation.Vertical` | Gets or sets the orientation of the separator. Should match the parent ButtonGroup's orientation. Default value is  (for horizontal button groups). |
| `Decorative` | `bool` | `true` | Gets or sets whether the separator is purely decorative. When true (default), the separator is treated as decorative and hidden from assistive technologies. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the separator. Custom classes are appended after the component's base classes, allowing for style overrides and extensions. |

#### `ButtonGroupText`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the text container. Custom classes are appended after the component's base classes, allowing for style overrides and extensions. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the text container. Can contain text, icons, or any other markup. Icons will automatically be sized to match the button group's icon size. |

**Basic Usage:**
```razor
<ButtonGroup>
 <Button Variant="ButtonVariant.Outline">Left</Button>
 <Button Variant="ButtonVariant.Outline">Center</Button>
 <Button Variant="ButtonVariant.Outline">Right</Button>
</ButtonGroup>

@* With active state *@
<ButtonGroup>
 <Button Variant="ButtonVariant.Default">Bold</Button>
 <Button Variant="ButtonVariant.Outline">Italic</Button>
 <Button Variant="ButtonVariant.Outline">Underline</Button>
</ButtonGroup>
```

---

### Calendar

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Date selection grid with month navigation. Interactive calendar for selecting single dates or date ranges.

**Components & Parameters:**

#### `Calendar`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `SelectedDate` | `DateOnly?` |  | The currently selected date. |
| `SelectedDateChanged` | `EventCallback<DateOnly?>` |  | Event callback invoked when the selected date changes. |
| `MinDate` | `DateOnly?` |  | The minimum selectable date. |
| `MaxDate` | `DateOnly?` |  | The maximum selectable date. |
| `Culture` | `CultureInfo` | `CultureInfo.CurrentCulture` | The culture to use for formatting. Default is the current culture. |
| `InitialMonth` | `DateOnly?` |  | The initial month to display. Defaults to the selected date's month or current month. |
| `IsDateDisabled` | `Func<DateOnly, bool>?` |  | Function to determine if a specific date is disabled. |
| `Class` | `string?` |  | Additional CSS classes to apply to the calendar. |
| `RowClass` | `string?` |  | Additional CSS classes to apply to each week row in the day grid. |
| `CaptionLayout` | `CalendarCaptionLayout` | `CalendarCaptionLayout.Label` | The caption layout mode for month/year display. Default is Label (static text). Dropdown allows quick month/year selection. |
| `YearRange` | `int` | `20` | The number of years to show before and after the current year in dropdown mode. Default is 20 years in each direction. |
| `RangeStart` | `DateOnly?` |  | The start date of a range selection (for visual styling). |
| `RangeEnd` | `DateOnly?` |  | The end date of a range selection (for visual styling). |
| `DisplayedMonthChanged` | `EventCallback<DateOnly>` |  | Event callback invoked when the displayed month changes. This fires whenever the user navigates to a different month via buttons, keyboard, or dropdown. |

**Basic Usage:**
```razor
@* Simple calendar *@
<Calendar @bind-Value="selectedDate" />

@* Date range calendar *@
<Calendar @bind-Value="dateRange" Mode="CalendarMode.Range" />

@* With disabled dates *@
<Calendar @bind-Value="selectedDate" 
 DisabledDates="@disabledDates" />

@code {
 private DateTime? selectedDate = DateTime.Today;
 private DateRange? dateRange;
 private HashSet<DateTime> disabledDates = new() { DateTime.Today.AddDays(1) };
}
```

---

### Card

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Container for grouped content with header, body, and footer sections. Flexible component for displaying information, forms, or actions.

**Components & Parameters:**

#### `Card`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the card. Typically contains CardHeader, CardContent, and CardFooter components. Can contain any Blazor markup. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the card. Custom classes are appended after the component's base classes, allowing for style overrides and extensions. |

#### `CardAction`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered in the card action area. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the card action area. |

#### `CardContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the card content area. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the card content. |

#### `CardDescription`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered as the card description. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the card description. |

#### `CardFooter`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the card footer. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the card footer. |

#### `CardHeader`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the card header. Typically contains CardTitle, CardDescription, and optionally CardAction. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the card header. |

#### `CardTitle`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered as the card title. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the card title. |

**Basic Usage:**
```razor
<Card>
 <CardHeader>
  <CardTitle>Card Title</CardTitle>
  <CardDescription>Card description goes here</CardDescription>
 </CardHeader>
 <CardContent>
  <p>Main content of the card.</p>
 </CardContent>
 <CardFooter Class="flex justify-between">
  <Button Variant="ButtonVariant.Outline">Cancel</Button>
  <Button>Save</Button>
 </CardFooter>
</Card>
```

---

### Carousel

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Slideshow component with touch gestures and animations. Displays content in a rotating carousel with navigation controls.

**Components & Parameters:**

#### `Carousel`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content containing CarouselItem components. |
| `Orientation` | `CarouselOrientation` | `CarouselOrientation.Horizontal` | Orientation of the carousel. Default is Horizontal. |
| `ShowNavigation` | `bool` | `true` | Whether to show navigation arrows. Default is true. |
| `ShowIndicators` | `bool` | `false` | Whether to show dot indicators. Default is false. |
| `AutoPlay` | `bool` | `false` | Whether to enable auto-play. Default is false. |
| `AutoPlayInterval` | `int` | `3000` | Auto-play interval in milliseconds. Default is 3000. |
| `Loop` | `bool` | `false` | Whether to enable loop (infinite scroll). Default is false. |
| `SlidesPerView` | `int` | `1` | Number of slides to show at once. Default is 1. |
| `Gap` | `int` | `0` | Gap between slides in pixels. Default is 0. |
| `EnableDrag` | `bool` | `false` | Whether to enable drag gestures. Default is false. |
| `Class` | `string?` |  | Additional CSS classes for the carousel container. |
| `ContentClass` | `string?` |  | Additional CSS classes for the inner content container that holds the slides. |
| `OnSlideChange` | `EventCallback<int>` |  | Event callback invoked when the current slide index changes. |

#### `CarouselItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content of the carousel item. |
| `Class` | `string?` |  | Additional CSS classes for the item. |

**Basic Usage:**
```razor
<Carousel>
 <CarouselContent>
  <CarouselItem>
<Card>
 <CardContent Class="p-6">
  <h3>Slide 1</h3>
 </CardContent>
</Card>
  </CarouselItem>
  <CarouselItem>
<Card>
 <CardContent Class="p-6">
  <h3>Slide 2</h3>
 </CardContent>
</Card>
  </CarouselItem>
 </CarouselContent>
 <CarouselPrevious />
 <CarouselNext />
</Carousel>
```

---

### Chart

**Package:** `NeoUI.Blazor.Charts`  
**Namespace:** `NeoUI.Blazor.Charts`

**Installation:**
```bash
dotnet add package NeoUI.Blazor.Charts --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor.Charts
```

**Description:**
Beautiful data visualizations with multiple chart types including Area, Bar, Composed, Line, Pie, Radar, Radial Bar, and Scatter charts.

**Components & Parameters:**

#### `Area`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Color` | `string?` |  | Gets or sets the area color (legacy, use Fill instead). |
| `Emphasis` | `bool` | `false` | Gets or sets whether emphasis is enabled. |
| `Focus` | `Focus` | `Focus.None` | Gets or sets the focus behavior. |
| `ShowDots` | `bool` | `false` | Gets or sets whether to show dots at data points. |
| `LineWidth` | `int` | `1` | Gets or sets the line width in pixels. |
| `Opacity` | `double?` |  | Gets or sets the opacity for the area fill (0.0 to 1.0). Maps to series.areaStyle.opacity. If Fill.Opacity is also set, Fill.Opacity takes precedence. |
| `StackId` | `string?` |  | Gets or sets the stack group ID for stacked areas. |
| `Interpolation` | `InterpolationType` | `InterpolationType.Natural` | Gets or sets the interpolation type for the area. |

#### `AreaChart`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `StackOffset` | `StackOffset` | `StackOffset.None` | Gets or sets the stack offset mode for percentage stacking. |

#### `AxisLabel`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Show` | `bool?` |  | Gets or sets whether to show axis labels. |
| `Rotate` | `int?` |  | Gets or sets the rotation angle in degrees (clockwise). Common value: -45. |
| `Formatter` | `string?` |  | Gets or sets the formatter string. Can be an ECharts template string or JavaScript function. Examples: "{value}", "function(value) { return value + '%'; }" |
| `Interval` | `int?` |  | Gets or sets the interval for showing labels. Shows every Nth label. |
| `Inside` | `bool?` |  | Gets or sets whether to render labels inside the chart area. |
| `Margin` | `int?` |  | Gets or sets the distance to the axis line in pixels. |
| `HideOverlap` | `bool?` |  | Gets or sets whether to hide overlapping labels. |
| `Color` | `string?` |  | Gets or sets the label color. CSS variable or hex color. |
| `FontSize` | `int?` |  | Gets or sets the font size in pixels. |
| `FontFamily` | `string?` |  | Gets or sets the font family. |
| `FontWeight` | `string?` |  | Gets or sets the font weight. E.g., "normal", "bold", "600". |
| `LineHeight` | `int?` |  | Gets or sets the line height in pixels. |
| `Align` | `string?` |  | Gets or sets the horizontal text alignment. E.g., "left", "center", "right". |
| `VerticalAlign` | `string?` |  | Gets or sets the vertical text alignment. E.g., "top", "middle", "bottom". |
| `Overflow` | `string?` |  | Gets or sets the overflow behavior. E.g., "truncate", "break", "breakAll". |
| `Width` | `int?` |  | Gets or sets the maximum width for label text. |
| `Ellipsis` | `string?` |  | Gets or sets the ellipsis character for truncated text. |

#### `Bar`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Color` | `string?` |  | Gets or sets the bar color (legacy, use Fill instead). |
| `Emphasis` | `bool` | `false` | Gets or sets whether emphasis is enabled. |
| `Focus` | `Focus` | `Focus.None` | Gets or sets the focus behavior. |
| `StackId` | `string?` |  | Gets or sets the stack group ID for stacked bars. |
| `Radius` | `int?` |  | Gets or sets the border radius for bar corners. |
| `Opacity` | `double?` |  | Gets or sets the opacity for the bars (0.0 to 1.0). Maps to series.itemStyle.opacity. |

#### `BarChart`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Layout` | `BarLayout` | `BarLayout.Vertical` | Gets or sets the bar chart layout (vertical or horizontal). |
| `StackOffset` | `StackOffset` | `StackOffset.None` | Gets or sets the stack offset mode for percentage stacking. |

#### `CenterLabel`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Text` | `string?` |  | Gets or sets the text to display in the center. |
| `FontSize` | `double?` |  | Gets or sets the font size. |
| `Color` | `string?` |  | Gets or sets the text color. |
| `FontWeight` | `string?` |  | Gets or sets the font weight. |

#### `ChartContainer`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content. |

#### `ChartDescription`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content. |

#### `ChartEmptyState`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Height` | `int` | `350` | Gets or sets the height of the empty state in pixels. |
| `Title` | `string` | `"No data available"` | Gets or sets the title text to display. |
| `Description` | `string?` |  | Gets or sets the description text to display. |
| `ShowIcon` | `bool` | `true` | Gets or sets whether to show the chart icon. |
| `Content` | `RenderFragment?` |  | Gets or sets custom content to display instead of the default message. |
| `Class` | `string?` |  | Gets or sets additional CSS classes. |

#### `ChartHeader`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content. |

#### `ChartSkeleton`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Height` | `int` | `350` | Gets or sets the height of the skeleton in pixels. |
| `BarCount` | `int` | `8` | Gets or sets the number of skeleton bars to display. |
| `Class` | `string?` |  | Gets or sets additional CSS classes. |

#### `ChartTitle`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content. |

#### `ComposedChart`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| *(No parameters)* | | | |

#### `Fill`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Color` | `string?` |  | Gets or sets the fill color. |
| `Opacity` | `double?` |  | Gets or sets the fill opacity. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content (for LinearGradient). |

#### `Grid`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Show` | `bool` | `true` | Gets or sets whether to show grid lines. |
| `Horizontal` | `bool` | `true` | Gets or sets whether to show horizontal grid lines. |
| `Vertical` | `bool` | `true` | Gets or sets whether to show vertical grid lines. |
| `Stroke` | `string?` |  | Gets or sets the stroke color for grid lines. |
| `StrokeWidth` | `int?` |  | Gets or sets the stroke width for grid lines in pixels. Maps to grid line lineStyle.width. |
| `StrokeType` | `LineStyleType` | `LineStyleType.Solid` | Gets or sets the stroke/line type for grid lines. Maps to grid line lineStyle.type. |
| `Opacity` | `double?` |  | Gets or sets the opacity for grid lines (0.0 to 1.0). Maps to grid line lineStyle.opacity. |

#### `LabelLine`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Show` | `bool` | `true` | Whether to show the label line. |
| `Length` | `double?` |  | Length of the first segment (in pixels). |
| `Length2` | `double?` |  | Length of the second segment (in pixels). |
| `Smooth` | `bool?` |  | Whether to use smooth curved lines. When true, label lines will be smoothly curved. When false or null, label lines will be straight. |

#### `LabelList`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Position` | `LabelPosition` | `LabelPosition.Top` | Label position. |
| `Formatter` | `string?` |  | Label formatter (template string or JS function string). |
| `Color` | `string?` |  | Label text color. |
| `FontSize` | `double?` |  | Label font size. |
| `Offset` | `double?` |  | Label offset from data point. |
| `Show` | `bool` | `true` | Whether to show labels. |

#### `Legend`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Show` | `bool` | `true` | Gets or sets whether to show the legend. |
| `Layout` | `LegendLayout` | `LegendLayout.Horizontal` | Gets or sets the legend layout orientation. |
| `Align` | `LegendAlign` | `LegendAlign.Center` | Gets or sets the horizontal alignment of the legend. |
| `VerticalAlign` | `LegendVerticalAlign` | `LegendVerticalAlign.Top` | Gets or sets the vertical alignment of the legend. |
| `MarginTop` | `int` | `0` | Gets or sets the top margin in pixels (applies only when VerticalAlign is Top). |
| `Icon` | `LegendIcon` | `LegendIcon.Circle` | Gets or sets the icon type for legend items. Maps to ECharts legend.icon property. |
| `TextColor` | `string?` |  | Gets or sets the text color for legend labels. Supports CSS variables like 'var(--foreground)'. |

#### `Line`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Color` | `string?` |  | Gets or sets the line color (legacy, use Fill instead). |
| `Emphasis` | `bool` | `false` | Gets or sets whether emphasis is enabled. |
| `Focus` | `Focus` | `Focus.None` | Gets or sets the focus behavior. |
| `ShowDots` | `bool` | `false` | Gets or sets whether to show dots at data points. |
| `DotSize` | `int` | `4` | Gets or sets the size of dots/symbols at data points in pixels. Maps to series.symbolSize. |
| `DotShape` | `SymbolShape` | `SymbolShape.EmptyCircle` | Gets or sets the shape of dots/symbols at data points. Maps to series.symbol. |
| `LineWidth` | `int` | `1` | Gets or sets the line width in pixels. |
| `Opacity` | `double?` |  | Gets or sets the opacity for the line (0.0 to 1.0). Maps to series.lineStyle.opacity or itemStyle.opacity. |
| `Dashed` | `bool` | `false` | Gets or sets whether the line should be dashed. |
| `Interpolation` | `InterpolationType` | `InterpolationType.Natural` | Gets or sets the interpolation type for the line. |

#### `LineChart`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| *(No parameters)* | | | |

#### `LinearGradient`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Direction` | `GradientDirection` | `GradientDirection.Vertical` | Gets or sets the gradient direction. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content (for Stop components). |

#### `Pie`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `InnerRadius` | `string?` |  | Gets or sets the inner radius for donut charts (e.g., "60" or "60%"). |
| `OuterRadius` | `string` | `"75%"` | Gets or sets the outer radius (e.g., "75%", "80%", "200"). Controls the overall size of the pie chart. |
| `StartAngle` | `int` | `90` | Gets or sets the start angle in degrees (0-360). 90 = top, 0 = right, 180 = bottom, 270 = left. |
| `EndAngle` | `int` | `450` | Gets or sets the end angle in degrees. For full circle: StartAngle + 360. For semi-circle gauge: StartAngle + 180. |
| `RoseType` | `string?` |  | Gets or sets the rose chart type. "radius" - radius represents value (Nightingale rose chart). "area" - area represents value. null - normal pie chart. |
| `PadAngle` | `int` | `0` | Gets or sets the padding angle between slices in degrees. |
| `Center` | `string[]?` |  | Gets or sets the center position as [x, y] (e.g., ["50%", "50%"]). |
| `SelectedMode` | `string?` |  | Gets or sets the selection mode. "single" - single slice selection. "multiple" - multiple slice selection. null/false - no selection. |
| `SelectedOffset` | `int` | `10` | Gets or sets the offset distance when slice is selected (pixels). |
| `MinAngle` | `int` | `0` | Gets or sets the minimum angle for a slice to be visible (degrees). Small value slices below this threshold will be hidden. |
| `Colors` | `string[]?` |  | Custom color palette for slices. Colors are distributed by index and wrap automatically. `null` = auto CSS-variable palette (`--chart-1` … `--chart-5`). |
| `ShowLabelLine` | `bool` | `true` | Gets or sets whether to show label lines. |
| `EmphasisScale` | `bool?` |  | Gets or sets whether to enable emphasis (hover) scaling. |
| `EmphasisScaleSize` | `int?` |  | Gets or sets the emphasis scale size in pixels (default 5-10). |
| `EmphasisFocus` | `string?` |  | Gets or sets the emphasis focus mode ("self", "series", "none"). |
| `EmphasisShowLabel` | `bool?` |  | Gets or sets whether to show labels on hover (emphasis). |
| `EmphasisLabelFormatter` | `string?` |  | Gets or sets the label formatter for emphasis state. |

#### `PieChart`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| *(No parameters)* | | | |

#### `PolarGrid`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Type` | `PolarGridType` | `PolarGridType.Circle` | Gets or sets the grid type (Circle or Polygon). |
| `Show` | `bool` | `true` | Gets or sets whether to show the grid. |
| `Stroke` | `string?` |  | Gets or sets the grid line color. |
| `StrokeWidth` | `int?` |  | Gets or sets the grid line width. |
| `SplitNumber` | `int` | `5` | Gets or sets the number of split levels (concentric rings). |
| `ShowAxisLine` | `bool` | `true` | Gets or sets whether to show the angle axis line. |
| `ShowSplitLine` | `bool` | `true` | Gets or sets whether to show split lines. |

#### `Radar`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Color` | `string?` |  | Gets or sets the series color (legacy, use Fill instead). |
| `Emphasis` | `bool` | `false` | Gets or sets whether emphasis is enabled. |
| `Focus` | `Focus` | `Focus.None` | Gets or sets the focus behavior. |
| `FillArea` | `bool` | `false` | Gets or sets whether to fill the radar area. |
| `AreaOpacity` | `double?` |  | Gets or sets the area fill opacity (0.0 to 1.0). Only applies when FillArea is true. |
| `LineWidth` | `int` | `2` | Gets or sets the line width in pixels. |

#### `RadarChart`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| *(No parameters)* | | | |

#### `RadarGrid`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Shape` | `RadarShape` | `RadarShape.Polygon` | Gets or sets the radar grid shape. |
| `SplitNumber` | `int` | `5` | Gets or sets the number of split levels (concentric grid lines). |
| `Radius` | `string` | `"75%"` | Gets or sets the radar radius relative to container (e.g., "75%", "200"). |
| `Center` | `string[]?` |  | Gets or sets the center position [x, y] (e.g., ["50%", "50%"]). |
| `ShowAxisLine` | `bool` | `true` | Gets or sets whether to show axis lines (spokes). |
| `ShowSplitLine` | `bool` | `true` | Gets or sets whether to show split lines (rings). |
| `AxisLineColor` | `string?` |  | Gets or sets the axis line color. |
| `AxisLineWidth` | `int?` |  | Gets or sets the axis line width. |
| `SplitLineColor` | `string?` |  | Gets or sets the split line color. |
| `SplitLineWidth` | `int?` |  | Gets or sets the split line width. |
| `ShowIndicatorLabels` | `bool` | `true` | Gets or sets whether to show radar indicator labels (axis names like "Coding", "Design", etc.). |
| `IndicatorColor` | `string?` |  | Gets or sets the text color for radar indicator labels. Supports CSS variables like 'var(--foreground)'. |
| `IndicatorFontSize` | `int?` |  | Gets or sets the font size for radar indicator labels. |
| `IndicatorFontWeight` | `string?` |  | Gets or sets the font weight for radar indicator labels (e.g., "normal", "bold"). |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content. |

#### `RadialBar`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Color` | `string?` |  | Gets or sets the series color (legacy, use Fill instead). |
| `InnerRadius` | `string?` |  | Gets or sets the inner radius (e.g., "60%" or "60"). |
| `OuterRadius` | `string?` |  | Gets or sets the outer radius (e.g., "80%" or "80"). |
| `CornerRadius` | `int?` |  | Gets or sets the corner radius for rounded bars. |
| `StackId` | `string?` |  | Gets or sets the stack group ID for stacked radial bars. |
| `ShowBackground` | `bool` | `false` | Gets or sets whether to show a background track. |
| `BackgroundColor` | `string?` |  | Gets or sets the background track color. |
| `BackgroundOpacity` | `double?` | `0.1` | Gets or sets the background track opacity (0.0 to 1.0). |

#### `RadialBarChart`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `StartAngle` | `int` | `90` | Gets or sets the start angle in degrees (0-360). 90 = top, 0 = right, 180 = bottom, 270 = left. |
| `EndAngle` | `int` | `450` | Gets or sets the end angle in degrees. For full circle: 450 (90 + 360). For semi-circle gauge: 270 (90 + 180). |
| `Clockwise` | `bool` | `true` | Gets or sets whether angle axis runs clockwise. |
| `RadiusMin` | `double?` | `0` | Gets or sets the minimum value for the radius axis. |
| `RadiusMax` | `double?` |  | Gets or sets the maximum value for the radius axis. |

#### `Scatter`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Color` | `string?` |  | Gets or sets the marker color (legacy, use Fill instead). Note: Scatter uses XAxis.DataKey and YAxis.DataKey for X/Y coordinates. |
| `SymbolSize` | `int` | `10` | Gets or sets the size of scatter symbols in pixels. Maps to series.symbolSize. |
| `Symbol` | `SymbolShape` | `SymbolShape.Circle` | Gets or sets the shape of scatter symbols. Maps to series.symbol. |
| `Emphasis` | `bool` | `false` | Gets or sets whether emphasis is enabled. |
| `Focus` | `Focus` | `Focus.None` | Gets or sets the focus behavior. |
| `SymbolSizeFunction` | `string?` |  | Gets or sets a JavaScript function string to dynamically calculate symbol size. Example: "function(data) { return data[2] / 100; }" for bubble charts. If set, overrides SymbolSize parameter. |
| `SymbolRotate` | `int?` |  | Gets or sets the symbol rotation in degrees. |
| `BorderColor` | `string?` |  | Gets or sets the border color for scatter symbols. |
| `BorderWidth` | `int?` |  | Gets or sets the border width for scatter symbols in pixels. |
| `Large` | `bool` | `false` | Gets or sets whether to enable large dataset optimization (10K+ points). |
| `LargeThreshold` | `int?` | `2000` | Gets or sets the threshold for enabling large mode automatically. |
| `Progressive` | `int?` |  | Gets or sets the progressive rendering chunk size for huge datasets. |
| `Clip` | `bool` | `true` | Gets or sets whether to clip points outside axis range. |

#### `ScatterChart`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| *(No parameters)* | | | |

#### `Stop`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Opacity` | `double?` |  | Gets or sets the opacity at this stop. |

#### `Tooltip`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Show` | `bool` | `true` | Gets or sets whether to show the tooltip. |
| `Mode` | `TooltipMode?` |  | Gets or sets the tooltip trigger mode. Default depends on chart type (see spec section 4.4). |
| `Cursor` | `TooltipCursor` | `TooltipCursor.None` | Gets or sets the cursor/axis pointer type. |
| `Formatter` | `string?` |  | Gets or sets the formatter string. Can be either an ECharts template string or a JavaScript function as a string. Examples: - Template: "{b}: {c}" - Function: "function(params) { return params.name + ': ' + params.value; }" |
| `BackgroundColor` | `string?` |  | Gets or sets the background color for the tooltip. Maps to tooltip.backgroundColor. |
| `BorderColor` | `string?` |  | Gets or sets the border color for the tooltip. Maps to tooltip.borderColor. |
| `BorderWidth` | `int?` |  | Gets or sets the border width for the tooltip in pixels. Maps to tooltip.borderWidth. |
| `TextColor` | `string?` |  | Gets or sets the text color for the tooltip. Maps to tooltip.textStyle.color. |
| `AppendToBody` | `bool?` |  | When `true`, appends the tooltip DOM to `document.body` instead of nesting inside the chart container. Prevents clipping inside `overflow:hidden` ancestors. Maps to ECharts `tooltip.appendToBody`. |

#### `XAxis`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Show` | `bool` | `true` | Gets or sets whether to show the X axis. |
| `DataKey` | `string?` |  | Gets or sets the data key for X axis values. |
| `Scale` | `AxisScale` | `AxisScale.Auto` | Gets or sets the scale type for the axis. |
| `Min` | `double?` |  | Gets or sets the minimum value for the axis. Maps to xAxis.min. |
| `Max` | `double?` |  | Gets or sets the maximum value for the axis. Maps to xAxis.max. |
| `Interval` | `double?` |  | Gets or sets the interval of axis ticks. Maps to xAxis.interval. |
| `AxisLine` | `bool` | `true` | Gets or sets whether to show the axis line. |
| `TickLine` | `bool` | `true` | Gets or sets whether to show tick lines. |
| `Color` | `string?` |  | Gets or sets the color of the axis line. Maps to axisLine.lineStyle.color. |
| `Width` | `int?` |  | Gets or sets the width of the axis line in pixels. Maps to axisLine.lineStyle.width. |
| `TickColor` | `string?` |  | Gets or sets the color of the tick lines. Maps to axisTick.lineStyle.color. |
| `TickWidth` | `int?` |  | Gets or sets the width of the tick lines in pixels. Maps to axisTick.lineStyle.width. |
| `BoundaryGap` | `bool?` |  | Gets or sets whether there is a gap on both sides of the axis. Default is null (auto). For bar charts, this leaves space on both sides. For line charts, this is typically set to false to have data points at the edges. Maps to xAxis.boundaryGap. |
| `IndicatorMin` | `double?` |  | Gets or sets the minimum value for this radar indicator. Only applies to RadarChart. |
| `IndicatorMax` | `double?` |  | Gets or sets the maximum value for this radar indicator. Only applies to RadarChart. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content for nested components (e.g., AxisLabel). |

#### `YAxis`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Show` | `bool` | `true` | Gets or sets whether to show the Y axis. |
| `DataKey` | `string?` |  | Gets or sets the data key for Y axis values. |
| `Scale` | `AxisScale` | `AxisScale.Auto` | Gets or sets the scale type for the axis. |
| `Position` | `YAxisPosition` | `YAxisPosition.Left` | Gets or sets the position of the Y axis (left or right). Maps to yAxis.position. |
| `Min` | `double?` |  | Gets or sets the minimum value for the axis. Maps to yAxis.min. |
| `Max` | `double?` |  | Gets or sets the maximum value for the axis. Maps to yAxis.max. |
| `Interval` | `double?` |  | Gets or sets the interval of axis ticks. Maps to yAxis.interval. |
| `AxisLine` | `bool` | `true` | Gets or sets whether to show the axis line. |
| `TickLine` | `bool` | `true` | Gets or sets whether to show tick lines. |
| `Color` | `string?` |  | Gets or sets the color of the axis line. Maps to axisLine.lineStyle.color. |
| `Width` | `int?` |  | Gets or sets the width of the axis line in pixels. Maps to axisLine.lineStyle.width. |
| `TickColor` | `string?` |  | Gets or sets the color of the tick lines. Maps to axisTick.lineStyle.color. |
| `TickWidth` | `int?` |  | Gets or sets the width of the tick lines in pixels. Maps to axisTick.lineStyle.width. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content for nested components (e.g., AxisLabel). |

**Basic Usage:**
```razor
@* Line Chart *@
<ChartContainer Config="chartConfig">
 <LineChart Data="chartData">
  <CartesianGrid StrokeDasharray="3 3" />
  <XAxis DataKey="name" />
  <YAxis />
  <ChartTooltip />
  <Line DataKey="value" Stroke="#8884d8" />
 </LineChart>
</ChartContainer>

@* Bar Chart *@
<ChartContainer Config="chartConfig">
 <BarChart Data="chartData">
  <CartesianGrid StrokeDasharray="3 3" />
  <XAxis DataKey="name" />
  <YAxis />
  <ChartTooltip />
  <Bar DataKey="value" Fill="#8884d8" />
 </BarChart>
</ChartContainer>

@code {
 private List<ChartDataItem> chartData = new()
 {
  new() { Name = "Jan", Value = 100 },
  new() { Name = "Feb", Value = 200 }
 };
}
```

---

### Checkbox

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Accessible checkbox with indeterminate state support. Binary selection control with support for partial selections.

**Components & Parameters:**

#### `Checkbox`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Checked` | `bool` |  | Gets or sets whether the checkbox is checked. This property supports two-way binding using the @bind-Checked directive. Changes to this property trigger the CheckedChanged event callback. |
| `CheckedChanged` | `EventCallback<bool>` |  | Gets or sets the callback invoked when the checked state changes. This event callback enables two-way binding with @bind-Checked. It is invoked whenever the user toggles the checkbox state. Also notifies EditContext for form validation. |
| `Indeterminate` | `bool` |  | Gets or sets whether the checkbox is in an indeterminate state. The indeterminate state is typically used for "select all" checkboxes when only some child items are selected. When indeterminate is true, a dash icon is displayed instead of a checkmark. |
| `IndeterminateChanged` | `EventCallback<bool>` |  | Gets or sets the callback invoked when the indeterminate state changes. |
| `Disabled` | `bool` |  | Gets or sets whether the checkbox is disabled. When disabled: - Checkbox cannot be clicked or focused - Opacity is reduced - Pointer events are disabled - aria-disabled attribute is set to true |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the checkbox. Custom classes are appended after the component's base classes, allowing for style overrides and extensions. |
| `AriaLabel` | `string?` |  | Gets or sets the ARIA label for the checkbox. Provides accessible text for screen readers when the checkbox doesn't have associated label text. |
| `Id` | `string?` |  | Gets or sets the ID attribute for the checkbox element. Used for associating the checkbox with label elements via htmlFor attribute. |
| `Name` | `string?` |  | Gets or sets the name of the checkbox for form submission. This is critical for form submission. The name/value pair is submitted to the server. If not specified, falls back to the Id value. |
| `Required` | `bool` |  | Gets or sets whether the checkbox is required. When true, the checkbox must be checked for form submission. Works with form validation. |
| `CheckedExpression` | `Expression<Func<bool>>?` |  | Gets or sets an expression that identifies the bound value. Used for form validation integration. When provided, the checkbox registers with the EditContext and participates in form validation. |

**Basic Usage:**
```razor
@* Simple checkbox *@
<Checkbox @bind-Checked="isAccepted" />

@* With label *@
<div class="flex items-center space-x-2">
 <Checkbox Id="terms" @bind-Checked="acceptTerms" />
 <Label For="terms">I accept the terms and conditions</Label>
</div>

@* Indeterminate state *@
<Checkbox Checked="false" Indeterminate="true" />

@code {
 private bool isAccepted = false;
 private bool acceptTerms = false;
}
```

---

### ColorPicker

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Canvas-based color picker with popover. Supports Hex, RGB, and HSL output formats, hue/saturation/lightness canvas selection, alpha/opacity control, and preset color swatches.

**Components & Parameters:**

#### `ColorPicker`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Color` | `string?` |  | The selected color value in the configured format. Use `@bind-Color` for two-way binding. |
| `ColorChanged` | `EventCallback<string?>` |  | Callback invoked when the color changes. |
| `Format` | `ColorFormat` | `ColorFormat.Hex` | Output format: `Hex`, `RGB`, or `HSL`. |
| `Size` | `ColorPickerSize` | `ColorPickerSize.Compact` | Size of the picker: `Compact` or `Large`. |
| `ShowAlpha` | `bool` | `false` | Show alpha/opacity slider. |
| `ShowInputs` | `bool` | `true` | Show RGB/HSL text input fields. |
| `ShowPresets` | `bool` | `true` | Show preset color swatches. |
| `Disabled` | `bool` | `false` | Disable the picker. |
| `Required` | `bool` | `false` | Mark as required for form validation. |
| `Class` | `string?` |  | Additional CSS classes for the trigger button. |
| `Id` | `string?` |  | HTML id attribute. |


**Basic Usage:**
```razor
<ColorPicker @bind-Color="hexColor" />
<ColorPicker @bind-Color="rgbColor" Format="ColorFormat.RGB" Size="ColorPickerSize.Large" />
<ColorPicker @bind-Color="color" ShowAlpha="true" ShowInputs="false" />

@code {
    private string? hexColor;
    private string? rgbColor;
    private string? color;
}
```

---

### Collapsible

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Expandable/collapsible content panels. Shows or hides content with smooth animations.

**Components & Parameters:**

#### `Collapsible`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Open` | `bool` |  | Gets or sets a value indicating whether the collapsible is currently expanded. true if the collapsible is open (content visible); otherwise, false. Default is false. Supports two-way binding via @bind-Open syntax. |
| `OpenChanged` | `EventCallback<bool>` |  | Gets or sets the callback invoked when the open state changes. An  that receives the new open state, or null if no callback is provided. |
| `Disabled` | `bool` |  | Gets or sets a value indicating whether the collapsible is disabled. true if the collapsible is disabled and cannot be toggled; otherwise, false. Default is false. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the container element. A string containing one or more CSS class names, or null. Use this parameter to customize the container's appearance and layout. Common Tailwind utilities include: Borders: border rounded-lg Padding: p-4, px-6 Background: bg-muted, bg-card Spacing: space-y-2, mb-4 |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content to be rendered inside the collapsible container. A  containing the child components, or null. Typically contains:  - The button/trigger element  - The expandable content area |

#### `CollapsibleContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the content container element. A string containing one or more CSS class names, or null. Use this parameter to style the content area and add animations. Common Tailwind utilities include: Padding: p-4, px-6 py-4 Borders: border-t, border-x Background: bg-muted, bg-card Transitions: transition-all duration-300 Animation: animate-in slide-in-from-top Overflow: overflow-hidden (for smooth height transitions) |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered when the collapsible is expanded. A  containing the collapsible content, or null. |

#### `CollapsibleTrigger`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the trigger button element. A string containing one or more CSS class names, or null. Common Tailwind utilities for styling triggers: Flex layout: flex items-center gap-2 Padding: px-4 py-2 Hover states: hover:bg-accent Transitions: transition-all duration-200 |
| `AsChild` | `bool` | `false` | When true, the trigger does not render its own button element. Instead, it passes trigger behavior via TriggerContext to child components. Use this when you want a custom component (like Button) to act as the trigger. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the trigger. A  containing the trigger content, or null. |

**Basic Usage:**
```razor
<Collapsible>
 <CollapsibleTrigger AsChild>
  <Button Variant="ButtonVariant.Ghost">
<LucideIcon Name="chevron-down" Size="16" />
Toggle Content
  </Button>
 </CollapsibleTrigger>
 <CollapsibleContent>
  <p>This content can be shown or hidden.</p>
 </CollapsibleContent>
</Collapsible>

@* Controlled mode *@
<Collapsible @bind-Open="isOpen">
 <CollapsibleTrigger AsChild>
  <Button>@(isOpen ? "Hide" : "Show") Details</Button>
 </CollapsibleTrigger>
 <CollapsibleContent>
  <p>Detailed information here.</p>
 </CollapsibleContent>
</Collapsible>

@code {
 private bool isOpen = false;
}
```

---

### Combobox

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Searchable autocomplete dropdown with keyboard navigation. Combines text input with dropdown selection.

**Components & Parameters:**

#### `Combobox`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Value` | `string?` |  | Gets or sets the currently selected value. |
| `ValueChanged` | `EventCallback<string?>` |  | Gets or sets the callback that is invoked when the selected value changes. |
| `Placeholder` | `string` | `"Select an option..."` | Gets or sets the placeholder text shown in the button when no item is selected. |
| `SearchPlaceholder` | `string` | `"Search..."` | Gets or sets the placeholder text shown in the search input. |
| `EmptyMessage` | `string` | `"No results found."` | Gets or sets the message displayed when no items match the search. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the combobox container. |
| `Disabled` | `bool` |  | Gets or sets whether the combobox is disabled. |
| `PopoverWidth` | `string` | `"w-[200px]"` | Gets or sets the width of the popover content. Defaults to "w-[200px]". Can be overridden with Tailwind classes. |

**Basic Usage:**
```razor
<Combobox @bind-Value="selectedValue" 
 Placeholder="Select item...">
 <ComboboxItem Value="item1">Item 1</ComboboxItem>
 <ComboboxItem Value="item2">Item 2</ComboboxItem>
 <ComboboxItem Value="item3">Item 3</ComboboxItem>
</Combobox>

@code {
 private string? selectedValue;
}
```

---

### Command

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Command palette with keyboard navigation and search. Quick access to actions and navigation via keyboard shortcuts.

**Components & Parameters:**

#### `Command`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the command container. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the command. |
| `OnSelect` | `EventCallback<string>` |  | Event callback invoked when a command item is selected. Receives the selected value as a parameter. |

#### `CommandEmpty`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the empty state container. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered when there are no results. |

#### `CommandGroup`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the group container. |
| `Heading` | `string?` |  | Gets or sets the heading text for this group (optional). |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the group. |

#### `CommandInput`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the input container. |
| `Placeholder` | `string` | `"Type a command or search..."` | Gets or sets the placeholder text for the input. |
| `Disabled` | `bool` |  | Gets or sets whether the input is disabled. |
| `AutoFocus` | `bool` |  | Gets or sets whether the input should auto-focus when rendered. |
| `SearchInterval` | `int` | `0` | Gets or sets the debounce interval in milliseconds before triggering search. Default is 0 (no debouncing). Set to 150-300ms for better performance with large datasets. |

#### `CommandItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the item. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the item. |
| `Value` | `string?` |  | Gets or sets the value associated with this item. |
| `Disabled` | `bool` |  | Gets or sets whether this item is disabled. |
| `OnSelect` | `EventCallback` |  | Gets or sets the callback invoked when this item is selected. |
| `SearchText` | `string?` |  | Gets or sets the text used for search filtering. If not provided, uses Value. |

#### `CommandList`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the list container. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the list. |

#### `CommandSeparator`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the separator. |

#### `CommandShortcut`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the shortcut. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the shortcut (e.g., "⌘K", "Ctrl+S"). |

**Basic Usage:**
```razor
<Command>
 <CommandInput Placeholder="Type a command..." />
 <CommandList>
  <CommandEmpty>No results found.</CommandEmpty>
  <CommandGroup Heading="Suggestions">
<CommandItem>Calendar</CommandItem>
<CommandItem>Search Emoji</CommandItem>
<CommandItem>Calculator</CommandItem>
  </CommandGroup>
  <CommandSeparator />
  <CommandGroup Heading="Settings">
<CommandItem>Profile</CommandItem>
<CommandItem>Settings</CommandItem>
  </CommandGroup>
 </CommandList>
</Command>
```

---

### ContextMenu

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Right-click context menus with actions and keyboard shortcuts. Displays contextual actions on right-click.

**Components & Parameters:**

#### `ContextMenu`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render. |
| `Open` | `bool?` |  | Controls whether the context menu is open. |
| `OpenChanged` | `EventCallback<bool>` |  | Event callback invoked when the open state changes. |
| `X` | `double` |  | Viewport X coordinate for programmatic positioning. Use with `OpenAt()`. |
| `Y` | `double` |  | Viewport Y coordinate for programmatic positioning. Use with `OpenAt()`. |
| `OnOpen` | `EventCallback<(double X, double Y)>` |  | Event callback invoked when the context menu opens. |
| `OnClose` | `EventCallback` |  | Event callback invoked when the context menu closes. |

> **Programmatic positioning:** Call `contextMenuRef.OpenAt(x, y)` to open and position the menu at specific viewport coordinates without a `ContextMenuTrigger`. Used by `DataTable` row context menus.

#### `ContextMenuCheckboxItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display inside the checkbox item. |
| `Disabled` | `bool` | `false` | Whether the checkbox item is disabled. |
| `Checked` | `bool` | `false` | Whether the checkbox is checked. |
| `CheckedChanged` | `EventCallback<bool>` |  | Event callback invoked when the checked state changes (for two-way binding). |
| `OnCheckedChange` | `EventCallback<bool>` |  | Event callback invoked when the checkbox state changes. |
| `CloseOnSelect` | `bool` | `false` | Whether to close the context menu when this item is selected. Default is false for checkbox items. |
| `Class` | `string?` |  | Additional CSS classes to apply. |

#### `ContextMenuContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render inside the menu. |
| `CloseOnEscape` | `bool` | `true` | Whether pressing Escape should close the menu. |
| `CloseOnClickOutside` | `bool` | `true` | Whether clicking outside should close the menu. |
| `ZIndex` | `int` | `50` | Z-index value for the menu content. |
| `LockScroll` | `bool` | `true` | Whether to lock body scroll when menu is open. Default is true. |
| `Class` | `string?` |  | Additional CSS classes to apply. |

#### `ContextMenuGroup`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the group. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the group. |

#### `ContextMenuItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render within the item. |
| `Disabled` | `bool` | `false` | Whether the item is disabled. |
| `OnClick` | `EventCallback` |  | Event callback invoked when the item is clicked. |
| `Inset` | `bool` | `false` | Whether to show the item with inset padding. |
| `Class` | `string?` |  | Additional CSS classes to apply. |

#### `ContextMenuLabel`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The label content. |
| `Inset` | `bool` | `false` | Whether to show the label with inset padding. |
| `Class` | `string?` |  | Additional CSS classes to apply. |

#### `ContextMenuRadioGroup`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render inside the radio group. Typically contains ContextMenuRadioItem components. |
| `Class` | `string?` |  | Additional CSS classes to apply to the radio group. |
| `Value` | `TValue?` |  | The currently selected value. |
| `ValueChanged` | `EventCallback<TValue?>` |  | Event callback invoked when the selected value changes (for two-way binding). |
| `OnValueChange` | `EventCallback<TValue?>` |  | Event callback invoked when the selection changes. |

#### `ContextMenuRadioItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display inside the radio item. |
| `Disabled` | `bool` | `false` | Whether the radio item is disabled. |
| `Value` | `TValue?` |  | The value associated with this radio item. |
| `CloseOnSelect` | `bool` | `true` | Whether to close the context menu when this item is selected. Default is true for radio items. |
| `Class` | `string?` |  | Additional CSS classes to apply. |

#### `ContextMenuSeparator`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Additional CSS classes to apply. |

#### `ContextMenuShortcut`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The shortcut text (e.g., "⌘C" or "Ctrl+C"). |
| `Class` | `string?` |  | Additional CSS classes to apply. |

#### `ContextMenuSub`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render inside the submenu. Typically contains ContextMenuSubTrigger and ContextMenuSubContent. |
| `Open` | `bool?` |  | Controls whether the submenu is open (controlled mode). |
| `OpenChanged` | `EventCallback<bool>` |  | Event callback invoked when the open state changes (for two-way binding). |
| `OnOpenChange` | `EventCallback<bool>` |  | Event callback invoked when the submenu open state changes. |

#### `ContextMenuSubContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render inside the submenu. |
| `CloseOnEscape` | `bool` | `true` | Whether pressing Escape should close the submenu. |
| `Offset` | `int` | `-4` | Offset distance from the trigger in pixels. |
| `ZIndex` | `int` | `50` | Z-index for the submenu content. |
| `Class` | `string?` |  | Additional CSS classes to apply. |

#### `ContextMenuSubTrigger`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display inside the trigger. |
| `Disabled` | `bool` | `false` | Whether the trigger is disabled. |
| `Inset` | `bool` | `false` | Whether to show the item with inset padding. |
| `Class` | `string?` |  | Additional CSS classes to apply. |

#### `ContextMenuTrigger`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content that triggers the context menu. |
| `Disabled` | `bool` | `false` | Whether the trigger is disabled. |

**Basic Usage:**
```razor
<ContextMenu>
 <ContextMenuTrigger>
  <div class="border rounded p-4">
Right-click me
  </div>
 </ContextMenuTrigger>
 <ContextMenuContent>
  <ContextMenuItem>Edit</ContextMenuItem>
  <ContextMenuItem>Copy</ContextMenuItem>
  <ContextMenuSeparator />
  <ContextMenuItem>Delete</ContextMenuItem>
 </ContextMenuContent>
</ContextMenu>
```

---

### CurrencyInput

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Culture-aware currency input with automatic symbol and decimal formatting. Generic over `decimal` or `double`. Integrates with EditForm validation.

**Components & Parameters:**

#### `CurrencyInput<TValue>`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Value` | `TValue?` |  | The bound currency value. Use `@bind-Value` for two-way binding. |
| `ValueChanged` | `EventCallback<TValue?>` |  | Callback invoked when the value changes. |
| `Currency` | `string` | `"USD"` | ISO currency code (e.g., USD, EUR, GBP, JPY). |
| `Culture` | `string?` |  | Culture code for formatting (e.g., "en-US", "de-DE"). Defaults to current culture. |
| `ShowCurrencySymbol` | `bool` | `true` | Show the currency symbol (e.g., $, €, £). |
| `Placeholder` | `string?` |  | Placeholder text. |
| `Disabled` | `bool` | `false` | Disable the input. |
| `Required` | `bool` | `false` | Mark as required. |
| `Name` | `string?` |  | Input name for form submission. |
| `Readonly` | `bool` | `false` | Make input read-only. |
| `Class` | `string?` |  | Additional CSS classes. |
| `Id` | `string?` |  | HTML id attribute. |
| `UpdateOn` | `InputUpdateMode` | `Change` | `Input` (every keystroke) or `Change` (on blur). |


**Basic Usage:**
```razor
<CurrencyInput TValue="decimal" @bind-Value="price" Currency="USD" />
<CurrencyInput TValue="decimal" @bind-Value="amount" Currency="EUR" Culture="de-DE" />
<CurrencyInput TValue="double" @bind-Value="cost" Currency="GBP" ShowCurrencySymbol="false" />

@code {
    private decimal price;
    private decimal amount;
    private double cost;
}
```

---

### DataTable

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Powerful tables with sorting, filtering, pagination, and row selection. Enterprise-grade data table component.

**Components & Parameters:**

#### `DataTable`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Data` | `IEnumerable<TData>` | `Array.Empty<TData>()` | The client-side collection of items to display. For server-side loading use `ServerData` instead. |
| `Columns` | `RenderFragment?` |  | Gets or sets the column definitions as child content. Use DataTableColumn components to define columns declaratively. |
| `SelectionMode` | `DataTableSelectionMode` | `DataTableSelectionMode.None` | Gets or sets the row selection mode. Default is None (no selection). |
| `ShowToolbar` | `bool` | `true` | Gets or sets whether to show the toolbar with global search and column visibility. Default is true. |
| `ShowPagination` | `bool` | `true` | Gets or sets whether to show pagination controls. Default is true. |
| `IsLoading` | `bool` |  | Gets or sets whether the table is in a loading state. Default is false. |
| `PageSizes` | `int[]` | `{ 5, 10, 20, 50, 100 }` | Gets or sets the available page size options. |
| `InitialPageSize` | `int` | `5` | Gets or sets the initial page size. Default is 5. |
| `ToolbarActions` | `RenderFragment?` |  | Gets or sets custom toolbar actions (buttons, etc.). |
| `EmptyTemplate` | `RenderFragment?` |  | Gets or sets a custom template for the empty state. If null, displays default "No results found" message. |
| `LoadingTemplate` | `RenderFragment?` |  | Gets or sets a custom template for the loading state. If null, displays default "Loading..." message. |
| `Class` | `string?` |  | Gets or sets additional CSS classes for the container div. |
| `AriaLabel` | `string?` |  | Gets or sets the ARIA label for the table. |
| `Dense` | `bool` | `true` | Compact cell padding. Set to `false` for a spacious layout. |
| `HeaderBackground` | `bool` | `true` | Applies `bg-muted/50` to the header row. |
| `HeaderBorder` | `bool` | `false` | Adds vertical dividers between header cells. |
| `CellBorder` | `bool` | `false` | Adds vertical dividers between body cells. |
| `ColumnsVisibility` | `bool` | `true` | Shows/hides the column visibility toggle button in the toolbar. |
| `HeaderClass` | `string?` |  | Extra CSS classes applied to `<thead>`. |
| `HeaderRowClass` | `string?` |  | Extra CSS classes applied to the header `<tr>`. |
| `BodyRowClass` | `string?` |  | Extra CSS classes applied to each body `<tr>`. |
| `SelectedItems` | `IReadOnlyCollection<TData>` | `Array.Empty<TData>()` | Gets or sets the selected items. Use @bind-SelectedItems for two-way binding. |
| `SelectedItemsChanged` | `EventCallback<IReadOnlyCollection<TData>>` |  | Event callback invoked when the selected items change. |
| `OnSort` | `EventCallback<(string ColumnId, SortDirection Direction)>` |  | Event callback invoked when sorting changes. Use for custom sorting logic (hybrid mode). |
| `OnFilter` | `EventCallback<string?>` |  | Event callback invoked when the global search text changes. |
| `ServerData` | `Func<DataTableRequest, Task<DataTableResult<TData>>>?` |  | Server-side data callback. When set, the table passes current page/sort/search state and renders the returned page. Mutually exclusive with `Data`. |
| `ItemsProvider` | `DataTableVirtualProvider<TData>?` | `null` | Activates server-side virtualised infinite-scroll mode (Blazor `<Virtualize>`). Set instead of `ServerData`. |
| `ItemHeight` | `float` | `40` | Approximate row height in pixels passed to the virtualizer as `ItemSize`. Must match your actual row height. Required when either virtualisation mode is active. |
| `Height` | `string` | `"400px"` | CSS height of the scrollable table container. Required when either virtualisation mode is active. |
| `VirtualizeOverscanCount` | `int` | `3` | Extra rows rendered beyond the visible viewport to reduce blank-row flicker during fast scrolling. |
| `Virtualize` | `bool` | `false` | Enables Blazor `<Virtualize>` for large in-memory datasets (client-side DOM windowing). Requires `ItemHeight` and `Height`. |
| `Resizable` | `bool` | `false` | Enables drag-resize handles on all column headers. Activates `table-layout: fixed` automatically. |
| `MinColumnWidth` | `int` | `80` | Minimum column width in pixels enforced during drag-resize. |
| `OnColumnResize` | `EventCallback<(string ColumnId, string Width)>` |  | Raised once when the user releases a resize handle. |
| `Reorderable` | `bool` | `false` | Enables drag-to-reorder on all eligible columns. Pinned and selection columns are always excluded. |
| `OnColumnReorder` | `EventCallback<(string ColumnId, int NewIndex)>` |  | Raised when a column is dropped into a new position. |
| `RowContextMenu` | `RenderFragment<DataTableRowMenuContext<TData>>?` |  | Template for a right-click context menu scoped to each row. |
| `SyncWidthOnResize` | `bool` | `false` | Keeps `<table>` total width equal to the sum of all column widths during and after resize. Pair with `TableContainerClass="border-0"`. |
| `TableContainerClass` | `string?` |  | Additional CSS classes on the inner table container div (wraps the `<table>`). Use `border-0` to remove the border. |
| `Striped` | `bool` | `false` | Enables alternating row background colours (zebra striping). |
| `StripeClass` | `string?` | `even:bg-muted/30 even:hover:bg-muted/70` | Tailwind class for the stripe. Override to change colour or swap odd/even. |
| `ChildrenProperty` | `Func<TData, IEnumerable<TData>?>?` |  | Returns child items for a row. Setting this activates tree/hierarchical mode; pagination is hidden. |
| `LoadChildrenAsync` | `Func<TData, Task<IEnumerable<TData>>>?` |  | Lazy-loads children on first expand. Used when children are not pre-populated. |
| `HasChildrenField` | `Func<TData, bool>?` |  | Determines whether an expand toggle is shown before children are loaded. |
| `ValueField` | `Func<TData, object>?` |  | Unique key per row, used to track expanded state in tree mode. |
| `ExpandedValues` | `IEnumerable<object>?` |  | Externally controlled set of expanded row keys. |
| `ExpandedValuesChanged` | `EventCallback<IEnumerable<object>>` |  | Notifies when expanded state changes. |
| `PreprocessData` | `Func<IEnumerable<TData>, Task<IEnumerable<TData>>>?` |  | Gets or sets a function to preprocess data before automatic processing. Use for custom transformations. |

#### Server-Side Types

| Type | Properties |
|---|---|
| `DataTableRequest` | `Page` (int, 1-based), `PageSize` (int), `SortDescriptors` (IReadOnlyList&lt;SortDescriptor&gt;), `SearchText` (string?) |
| `DataTableResult<TData>` | `Items` (IEnumerable&lt;TData&gt;), `TotalCount` (int) |
| `DataTableVirtualProvider<TData>` | Delegate: `Func<DataTableVirtualRequest, Task<DataTableVirtualResult<TData>>>` |
| `DataTableVirtualRequest` | `StartIndex` (int), `Count` (int), `SortDescriptors` (IReadOnlyList&lt;SortDescriptor&gt;), `SearchText` (string?), `CancellationToken` |
| `SortDescriptor` | `Column` (string), `Direction` (SortDirection) |
| `DataTableRowMenuContext<TData>` | `Item` (TData), `SelectedItems` (IReadOnlyList&lt;TData&gt;), `VisibleColumns` (IReadOnlyList&lt;string&gt;) |

> ⚠️ **Breaking (3.6.1):** `DataTableRequest.SortColumn` and `SortDirection` are removed. Use `SortDescriptors.FirstOrDefault()` instead.

#### `DataTableColumn`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Id` | `string?` |  | Gets or sets the unique identifier for this column. If not provided, it will be auto-generated from the Header. |
| `Sortable` | `bool` |  | Gets or sets whether this column can be sorted. Default is false. |
| `Filterable` | `bool` |  | Gets or sets whether this column can be filtered. Default is false. |
| `Visible` | `bool` | `true` | Gets or sets whether this column is currently visible. Default is true. |
| `Width` | `string?` |  | Gets or sets the width of the column (e.g., "200px", "20%", "auto"). Null means the column will size automatically. |
| `MinWidth` | `string?` |  | Gets or sets the minimum width of the column (e.g., "100px"). Useful for responsive layouts. |
| `MaxWidth` | `string?` |  | Gets or sets the maximum width of the column (e.g., "400px"). Useful for preventing excessively wide columns. |
| `Pinned` | `ColumnPinnedSide` | `ColumnPinnedSide.None` | Pins the column to the left or right edge of the table. Pinned columns stay fixed during horizontal scroll with a frosted-glass treatment. |
| `Resizable` | `bool?` |  | Per-column resize override. `null` inherits the table-level `Resizable` setting. |
| `Reorderable` | `bool?` |  | Per-column reorder override. `null` inherits the table-level `Reorderable` setting. Pinned columns are always excluded. |
| `CellTemplate` | `RenderFragment<TData>?` |  | Gets or sets a custom template for rendering cell values. If null, the value is rendered using ToString(). The context parameter provides the data item (TData) for the row. &lt;DataTableColumn Property="@(p => p.Status)" Header="Status"&gt; &lt;CellTemplate Context="person"&gt; &lt;Badge Variant="@(person.Status == "Active" ? BadgeVariant.Default : BadgeVariant.Destructive)"&gt; @person.Status &lt;/Badge&gt; &lt;/CellTemplate&gt; &lt;/DataTableColumn&gt; |
| `CellClass` | `string?` |  | Gets or sets additional CSS classes to apply to cells in this column. |
| `HeaderClass` | `string?` |  | Gets or sets additional CSS classes to apply to the header cell. |

**New enums:** `ColumnPinnedSide` — `None`, `Left`, `Right`

#### `DataTablePagination`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `PageSizes` | `int[]` | `{ 10, 20, 50, 100 }` |  |
| `OnPageChanged` | `EventCallback<int>` |  |  |
| `OnPageSizeChanged` | `EventCallback<int>` |  |  |

#### `DataTableToolbar`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `GlobalSearchValue` | `string` | `string.Empty` |  |
| `OnGlobalSearchChanged` | `EventCallback<string>` |  |  |
| `Columns` | `List<DataTable<TData>.ColumnData>` | `new()` |  |
| `OnColumnVisibilityChanged` | `Action<string, bool>` | `null!` |  |
| `ChildContent` | `RenderFragment?` |  |  |

**Basic Usage:**
```razor
<DataTable Data="@users" TData="User">
 <Columns>
  <DataTableColumn TData="User" Property="u => u.Name" Header="Name" />
  <DataTableColumn TData="User" Property="u => u.Email" Header="Email" Sortable="true" />
  <DataTableColumn TData="User" Property="u => u.Role" Header="Role" />
 </Columns>
</DataTable>

@* Server-side *@
<DataTable TData="Order" ServerData="@LoadOrdersAsync">
 <Columns>
  <DataTableColumn TData="Order" Property="o => o.Id" Header="ID" />
  <DataTableColumn TData="Order" Property="o => o.Total" Header="Total" DataFormatString="C" Sortable="true" />
 </Columns>
</DataTable>

@code {
 private List<User> users = new()
 {
  new User { Name = "John", Email = "john@example.com", Role = "Admin" },
  new User { Name = "Jane", Email = "jane@example.com", Role = "User" }
 };

 private async Task<DataTableResult<Order>> LoadOrdersAsync(DataTableRequest req)
 {
  var result = await _orderService.GetPagedAsync(req.Page, req.PageSize, req.SortDescriptors.FirstOrDefault()?.Column, req.SearchText);
  return new DataTableResult<Order> { Items = result.Items, TotalCount = result.Total };
 }
}
```

---

### DarkModeToggle

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
A sun/moon toggle switch that controls the application's dark mode via the injected `ThemeService`. Automatically synchronizes with external theme changes.

**Components & Parameters:**

#### `DarkModeToggle`

No configurable parameters. Uses the injected `ThemeService` to get and set dark mode state.


**Basic Usage:**
```razor
<DarkModeToggle />
```

---

### DatePicker

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Date selection with calendar in popover. Includes support for single dates and date ranges.

**Components & Parameters:**

#### `DatePicker`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `SelectedDateChanged` | `EventCallback<DateOnly?>` |  | Event callback invoked when the selected date changes. Use with @bind-SelectedDate for two-way binding. |
| `MinDate` | `DateOnly?` |  | Minimum selectable date. |
| `MaxDate` | `DateOnly?` |  | Maximum selectable date. |
| `IsDateDisabled` | `Func<DateOnly, bool>?` |  | Function to determine if a specific date should be disabled. |
| `Culture` | `System.Globalization.CultureInfo?` |  | Culture for date formatting. |
| `CaptionLayout` | `CalendarCaptionLayout` | `CalendarCaptionLayout.Label` | Calendar caption layout (label or dropdown). |
| `ButtonVariant` | `ButtonVariant` | `ButtonVariant.Outline` | Button variant for the trigger button. |
| `ButtonSize` | `ButtonSize` | `ButtonSize.Default` | Button size for the trigger button. |
| `ShowIcon` | `bool` | `true` | Whether to show the calendar icon in the button. |
| `ShowDropdownIcon` | `bool` | `false` | Whether to show the chevron-down icon on the right side of the button. |
| `Placeholder` | `string` | `"Pick a date"` | Placeholder text when no date is selected. |
| `DateFormat` | `string?` |  | Date format string for displaying the selected date. |
| `Disabled` | `bool` |  | Whether the date picker is disabled. |
| `Align` | `PopoverAlign` | `PopoverAlign.Start` | Alignment of the popover content. |
| `Class` | `string?` |  | Additional CSS classes for the button. |
| `CalendarClass` | `string?` |  | Additional CSS classes for the calendar. |
| `AriaLabel` | `string?` |  | ARIA label for the button. |

#### `DateRangePicker`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `StartDateChanged` | `EventCallback<DateOnly?>` |  | Event callback invoked when the start date changes. |
| `EndDateChanged` | `EventCallback<DateOnly?>` |  | Event callback invoked when the end date changes. |
| `MinDate` | `DateOnly?` |  | Minimum selectable date. |
| `MaxDate` | `DateOnly?` |  | Maximum selectable date. |
| `IsDateDisabled` | `Func<DateOnly, bool>?` |  | Function to determine if a specific date should be disabled. |
| `Culture` | `System.Globalization.CultureInfo?` |  | Culture for date formatting. |
| `CaptionLayout` | `CalendarCaptionLayout` | `CalendarCaptionLayout.Label` | Calendar caption layout (label or dropdown). |
| `ButtonVariant` | `ButtonVariant` | `ButtonVariant.Outline` | Button variant for the trigger button. |
| `ButtonSize` | `ButtonSize` | `ButtonSize.Default` | Button size for the trigger button. |
| `ShowIcon` | `bool` | `true` | Whether to show the calendar icon in the button. |
| `ShowDropdownIcon` | `bool` | `false` | Whether to show the chevron-down icon on the right side of the button. |
| `Placeholder` | `string` | `"Pick a date range"` | Placeholder text when no date range is selected. |
| `DateFormat` | `string?` |  | Date format string for displaying dates. |
| `Disabled` | `bool` |  | Whether the date range picker is disabled. |
| `Align` | `PopoverAlign` | `PopoverAlign.Start` | Alignment of the popover content. |
| `StartDateLabel` | `string?` |  | Label for the start date calendar. |
| `EndDateLabel` | `string?` |  | Label for the end date calendar. |
| `Class` | `string?` |  | Additional CSS classes for the button. |
| `CalendarClass` | `string?` |  | Additional CSS classes for the calendars. |
| `AriaLabel` | `string?` |  | ARIA label for the button. |

**Basic Usage:**
```razor
@* Simple date picker *@
<DatePicker @bind-Value="selectedDate" />

@* Date range picker *@
<DateRangePicker @bind-Value="dateRange" />

@* With placeholder *@
<DatePicker @bind-Value="selectedDate" 
Placeholder="Pick a date" />

@code {
 private DateTime? selectedDate;
 private DateRange? dateRange;
}
```

---

### DateRangePicker

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Date range selector with dual side-by-side calendars for picking start and end dates. Supports quick-select presets sidebar, Clear/Apply buttons, min/max date constraints, and culture-aware formatting.

**Components & Parameters:**

#### `DateRangePicker`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Start` | `DateOnly?` |  | The selected start date. Use `@bind-Start` for two-way binding. |
| `StartChanged` | `EventCallback<DateOnly?>` |  | Callback invoked when the start date changes. |
| `End` | `DateOnly?` |  | The selected end date. Use `@bind-End` for two-way binding. |
| `EndChanged` | `EventCallback<DateOnly?>` |  | Callback invoked when the end date changes. |
| `ShowPresets` | `bool` | `false` | Show a quick-select preset sidebar (Today, This Week, This Month, etc.). |
| `ShowButtons` | `bool` | `true` | Show Clear and Apply buttons at the bottom. |
| `ShowIcon` | `bool` | `true` | Show calendar icon in the trigger. |
| `ShowDropdownIcon` | `bool` | `true` | Show chevron icon in the trigger. |
| `StartDateLabel` | `string?` | `"From"` | Label above the start calendar. |
| `EndDateLabel` | `string?` | `"To"` | Label above the end calendar. |
| `MinDate` | `DateOnly?` |  | Minimum selectable date. |
| `MaxDate` | `DateOnly?` |  | Maximum selectable date. |
| `Format` | `string?` |  | Date display format string. |
| `Culture` | `string?` |  | Culture for date formatting. |
| `Disabled` | `bool` | `false` | Disable the picker. |
| `Placeholder` | `string?` |  | Placeholder text when no range is selected. |
| `Class` | `string?` |  | Additional CSS classes. |


**Basic Usage:**
```razor
<DateRangePicker @bind-Start="startDate" @bind-End="endDate" ShowPresets="true" />

@code {
    private DateOnly? startDate;
    private DateOnly? endDate;
}
```

---

### Dialog

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Modal dialogs for focused interactions. Displays content in an overlay that requires user interaction.

**Components & Parameters:**

#### `Dialog`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render within the dialog. |
| `Open` | `bool?` |  | Controls whether the dialog is open (controlled mode). When null, the dialog manages its own state (uncontrolled mode). |
| `OpenChanged` | `EventCallback<bool>` |  | Event callback invoked when the open state changes. Use with @bind-Open for two-way binding. |
| `DefaultOpen` | `bool` | `false` | Default open state when in uncontrolled mode. |
| `OnOpenChange` | `EventCallback<bool>` |  | Event callback invoked when the dialog open state changes. |
| `Modal` | `bool` | `true` | Whether the dialog can be dismissed by clicking outside or pressing Escape. Default is true. |

#### `DialogClose`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display inside the close button. |
| `AsChild` | `bool` | `false` | When true, the close does not render its own button element. Instead, it passes trigger behavior via TriggerContext to child components. Use this when you want a custom component (like Button) to act as the close button. |
| `OnClick` | `EventCallback<MouseEventArgs>` |  | Custom click handler. Called after the dialog is closed. |
| `PreventClose` | `bool` | `false` | Whether to prevent the default close behavior. When true, only the OnClick handler is invoked. Default is false (dialog closes on click). |

#### `DialogContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render inside the dialog. |
| `Class` | `string?` |  | Additional CSS classes to apply to the dialog content. |
| `OverlayClass` | `string?` |  | Additional CSS classes to apply to the dialog overlay/backdrop. Merged with built-in defaults using ClassNames.cn. |
| `UseCustomAnimations` | `bool` | `false` | When true, do not include default animation-related classes so consumers can provide completely custom animations. |
| `ShowClose` | `bool` | `true` | Whether to show the close button (X icon). Default is true. |
| `CloseOnEscape` | `bool` | `true` | Whether pressing Escape should close the dialog. Default is true. |
| `TrapFocus` | `bool` | `true` | Whether to trap focus within the dialog. Default is true for modal dialogs. |
| `LockScroll` | `bool` | `true` | Whether to lock body scroll when dialog is open. Default is true for modal dialogs. |
| `OnEscapeKeyDown` | `EventCallback<KeyboardEventArgs>` |  | Event callback invoked when Escape key is pressed. |

#### `DialogDescription`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The description content to display. |
| `Class` | `string?` |  | Additional CSS classes to apply to the description. |

#### `DialogFooter`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display in the dialog footer (typically action buttons). |
| `Class` | `string?` |  | Additional CSS classes to apply to the footer container. |

#### `DialogHeader`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display in the dialog header (typically DialogTitle and DialogDescription). |
| `Class` | `string?` |  | Additional CSS classes to apply to the header container. |

#### `DialogTitle`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The title content to display. |
| `Class` | `string?` |  | Additional CSS classes to apply to the title. |

#### `DialogTrigger`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display inside the trigger button. |
| `AsChild` | `bool` | `false` | When true, the trigger does not render its own button element. Instead, it passes trigger behavior via TriggerContext to child components. Use this when you want a custom component (like Button) to act as the trigger. |

**Basic Usage:**
```razor
<Dialog>
 <DialogTrigger AsChild>
  <Button>Open Dialog</Button>
 </DialogTrigger>
 <DialogContent>
  <DialogHeader>
<DialogTitle>Edit Profile</DialogTitle>
<DialogDescription>
 Make changes to your profile here.
</DialogDescription>
  </DialogHeader>
  <div class="space-y-4">
<Field>
 <FieldLabel>Name</FieldLabel>
 <Input @bind-Value="name" />
</Field>
  </div>
  <DialogFooter>
<Button>Save Changes</Button>
  </DialogFooter>
 </DialogContent>
</Dialog>

@code {
 private string name = "";
}
```

---

### DialogHost

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Host component that renders dialogs triggered by `IDialogService`. Place once in your layout (e.g., `MainLayout.razor`). Uses `DialogService` to show confirmation, warning, info, and destructive dialogs programmatically with configurable buttons, icons, and variants.

**Components & Parameters:**

#### `DialogHost`

No configurable parameters. Registers itself with the injected `DialogService` on initialization.

**Service types used with `IDialogService`:**

| Type | Description |
|------|-------------|
| `DialogOptions` | Configuration for the dialog: `Title`, `Message`, `Buttons`, `Variant`, `Icon`, `ConfirmText`, `CancelText`, `AlternateText` |
| `DialogButtons` | `OkOnly`, `OkCancel`, `YesNo`, `YesNoCancel` |
| `DialogVariant` | `Default`, `Destructive`, `Warning`, `Success`, `Info` |
| `DialogResult` | `Confirmed`, `Cancelled`, `Alternate` |


**Basic Usage:**
```razor
@* In MainLayout.razor *@
<DialogHost />

@* In a page/component *@
@inject IDialogService DialogService

@code {
    private async Task ConfirmDelete()
    {
        var result = await DialogService.ShowAsync(new DialogOptions
        {
            Title = "Delete Item",
            Message = "Are you sure you want to delete this item?",
            Buttons = DialogButtons.YesNo,
            Variant = DialogVariant.Destructive,
            Icon = "trash-2"
        });
        if (result == DialogResult.Confirmed)
            await DeleteAsync();
    }
}
```

---

### Drawer

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Mobile-friendly slide-in panel that can emerge from any edge (Bottom, Top, Left, Right). Includes a backdrop overlay, keyboard/click-to-dismiss, focus trap, and body scroll lock.

**Components & Parameters:**

#### `Drawer`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Content including trigger, content, and other drawer sub-components. |
| `Open` | `bool?` |  | Controlled open state. Use `@bind-Open` for two-way binding. |
| `OpenChanged` | `EventCallback<bool>` |  | Callback invoked when open state changes. |
| `DefaultOpen` | `bool` | `false` | Initial open state in uncontrolled mode. |
| `Direction` | `DrawerDirection` | `DrawerDirection.Bottom` | Slide direction: `Bottom`, `Top`, `Left`, `Right`. |

#### `DrawerContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The drawer body content. |
| `Class` | `string?` |  | Additional CSS classes. |
| `ShowHandle` | `bool` | `true` | Show drag handle indicator. |
| `TrapFocus` | `bool` | `true` | Trap focus inside the drawer while open. |
| `LockScroll` | `bool` | `true` | Lock body scroll while open. |
| `CloseOnEscape` | `bool` | `true` | Close when Escape key is pressed. |

#### `DrawerTrigger`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The trigger element content. |
| `Class` | `string?` |  | Additional CSS classes. |


**Basic Usage:**
```razor
<Drawer>
    <DrawerTrigger>
        <Button>Open Drawer</Button>
    </DrawerTrigger>
    <DrawerContent>
        <DrawerHeader>
            <DrawerTitle>Edit Profile</DrawerTitle>
            <DrawerDescription>Make changes to your profile here.</DrawerDescription>
        </DrawerHeader>
        <div class="p-4">Content goes here.</div>
        <DrawerFooter>
            <DrawerClose>
                <Button Variant="ButtonVariant.Outline">Cancel</Button>
            </DrawerClose>
        </DrawerFooter>
    </DrawerContent>
</Drawer>
```

---

### DropdownMenu

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Context menus with nested submenus and keyboard navigation. Displays a menu of actions triggered by a button.

**Components & Parameters:**

#### `DropdownMenu`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render within the dropdown menu. Typically includes DropdownMenuTrigger and DropdownMenuContent. |
| `Open` | `bool?` |  | Controls whether the dropdown menu is open (controlled mode). When null, the dropdown menu manages its own state (uncontrolled mode). |
| `OpenChanged` | `EventCallback<bool>` |  | Event callback invoked when the open state changes. Use with @bind-Open for two-way binding. |
| `DefaultOpen` | `bool` | `false` | Default open state when in uncontrolled mode. |
| `OnOpenChange` | `EventCallback<bool>` |  | Event callback invoked when the dropdown menu open state changes. |
| `Modal` | `bool` | `true` | Whether the dropdown menu can be dismissed by clicking outside or pressing Escape. Default is true. |
| `Dir` | `string` | `"ltr"` | Direction for the menu content layout ("ltr" or "rtl"). Default is "ltr". |

#### `DropdownMenuCheckboxItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display inside the checkbox item. |
| `Class` | `string?` |  | Additional CSS classes to apply to the checkbox item. |
| `Disabled` | `bool` | `false` | Whether the checkbox item is disabled. |
| `Checked` | `bool` | `false` | Whether the checkbox is checked. |
| `CheckedChanged` | `EventCallback<bool>` |  | Event callback invoked when the checked state changes (for two-way binding). |
| `OnCheckedChange` | `EventCallback<bool>` |  | Event callback invoked when the checkbox state changes. |
| `CloseOnSelect` | `bool` | `false` | Whether to close the dropdown menu when this item is selected. Default is false for checkbox items. |

#### `DropdownMenuContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render inside the dropdown menu. |
| `Class` | `string?` |  | Additional CSS classes to apply to the content container. |
| `CloseOnEscape` | `bool` | `true` | Whether pressing Escape should close the dropdown menu. |
| `CloseOnClickOutside` | `bool` | `true` | Whether clicking outside should close the dropdown menu. |
| `Side` | `PopoverSide` | `PopoverSide.Bottom` | Preferred side for positioning. |
| `Align` | `PopoverAlign` | `PopoverAlign.Start` | Alignment relative to trigger. |
| `Offset` | `int` | `4` | Offset distance from the trigger in pixels. |
| `OnEscapeKeyDown` | `EventCallback<KeyboardEventArgs>` |  | Event callback invoked when Escape key is pressed. |
| `OnClickOutside` | `EventCallback` |  | Event callback invoked when clicking outside. |
| `Loop` | `bool` | `true` | Whether to enable keyboard loop navigation. |
| `Strategy` | `PositioningStrategy` | `PositioningStrategy.Absolute` | Positioning strategy: "absolute" or "fixed". Use "fixed" when dropdown needs to escape stacking contexts (e.g., in sidebars). Default is "absolute". |
| `MatchTriggerWidth` | `bool` | `false` | Whether to match the trigger element's width. Default is false. |
| `ZIndex` | `int` | `50` | Z-index for the dropdown content. Default is 50. |
| `Style` | `string?` |  | Inline styles to apply to the dropdown content. |

#### `DropdownMenuGroup`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the group. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the group. |

#### `DropdownMenuItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display inside the menu item. |
| `Class` | `string?` |  | Additional CSS classes to apply to the menu item. |
| `Disabled` | `bool` | `false` | Whether the menu item is disabled. |
| `OnClick` | `EventCallback<MouseEventArgs>` |  | Custom click handler. |
| `CloseOnSelect` | `bool` | `true` | Whether to close the dropdown menu when this item is selected. |

#### `DropdownMenuLabel`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the label. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the label. |

#### `DropdownMenuRadioGroup`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render inside the radio group. Typically contains DropdownMenuRadioItem components. |
| `Class` | `string?` |  | Additional CSS classes to apply to the radio group. |
| `Value` | `TValue?` |  | The currently selected value. |
| `ValueChanged` | `EventCallback<TValue?>` |  | Event callback invoked when the selected value changes (for two-way binding). |
| `OnValueChange` | `EventCallback<TValue?>` |  | Event callback invoked when the selection changes. |

#### `DropdownMenuRadioItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display inside the radio item. |
| `Class` | `string?` |  | Additional CSS classes to apply to the radio item. |
| `Disabled` | `bool` | `false` | Whether the radio item is disabled. |
| `Value` | `TValue?` |  | The value associated with this radio item. |
| `CloseOnSelect` | `bool` | `true` | Whether to close the dropdown menu when this item is selected. Default is true for radio items. |

#### `DropdownMenuSeparator`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the separator. |

#### `DropdownMenuShortcut`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the shortcut. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the shortcut (e.g., "⌘K", "Ctrl+S"). |

#### `DropdownMenuSub`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render inside the submenu. Typically contains DropdownMenuSubTrigger and DropdownMenuSubContent. |
| `Open` | `bool?` |  | Controls whether the submenu is open (controlled mode). |
| `OpenChanged` | `EventCallback<bool>` |  | Event callback invoked when the open state changes (for two-way binding). |
| `OnOpenChange` | `EventCallback<bool>` |  | Event callback invoked when the submenu open state changes. |

#### `DropdownMenuSubContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render inside the submenu. |
| `Class` | `string?` |  | Additional CSS classes to apply to the content container. |
| `CloseOnEscape` | `bool` | `true` | Whether pressing Escape should close the submenu. |
| `Offset` | `int` | `-4` | Offset distance from the trigger in pixels. |
| `ZIndex` | `int` | `50` | Z-index for the submenu content. |

#### `DropdownMenuSubTrigger`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display inside the trigger. |
| `Class` | `string?` |  | Additional CSS classes to apply to the trigger. |
| `Disabled` | `bool` | `false` | Whether the trigger is disabled. |
| `Inset` | `bool` | `false` | Whether this trigger is an inset item (has additional left padding). |

#### `DropdownMenuTrigger`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display inside the trigger button. |
| `Class` | `string?` |  | Additional CSS classes to apply to the wrapper. |
| `AsChild` | `bool` | `false` | When true, the trigger does not render its own button element. Instead, it passes trigger behavior via TriggerContext to child components. Use this when you want a custom component (like Button) to act as the trigger. |
| `Disabled` | `bool` | `false` | Whether the trigger is disabled. |
| `OnClick` | `EventCallback<MouseEventArgs>` |  | Custom click handler. |
| `CustomClickHandling` | `bool` | `false` | Whether to use custom click handling only. |

**Basic Usage:**
```razor
<DropdownMenu>
 <DropdownMenuTrigger AsChild>
  <Button Variant="ButtonVariant.Outline">
Options
<LucideIcon Name="chevron-down" Size="16" />
  </Button>
 </DropdownMenuTrigger>
 <DropdownMenuContent>
  <DropdownMenuLabel>My Account</DropdownMenuLabel>
  <DropdownMenuSeparator />
  <DropdownMenuItem>Profile</DropdownMenuItem>
  <DropdownMenuItem>Settings</DropdownMenuItem>
  <DropdownMenuSeparator />
  <DropdownMenuItem>Logout</DropdownMenuItem>
 </DropdownMenuContent>
</DropdownMenu>
```

---

### Empty

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Empty state displays with customizable icons and messages. Shows when there's no data or content to display.

**Components & Parameters:**

#### `Empty`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the empty state. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the empty state. |

#### `EmptyActions`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  |  |
| `ChildContent` | `RenderFragment?` |  |  |

#### `EmptyDescription`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  |  |
| `ChildContent` | `RenderFragment?` |  |  |

#### `EmptyIcon`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  |  |
| `ChildContent` | `RenderFragment?` |  |  |

#### `EmptyTitle`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  |  |
| `ChildContent` | `RenderFragment?` |  |  |

**Basic Usage:**
```razor
@* Simple empty state *@
<Empty />

@* Custom empty state *@
<Empty>
 <EmptyIcon>
  <LucideIcon Name="inbox" Size="48" />
 </EmptyIcon>
 <EmptyTitle>No messages</EmptyTitle>
 <EmptyDescription>You don't have any messages yet.</EmptyDescription>
 <EmptyAction>
  <Button>Create Message</Button>
 </EmptyAction>
</Empty>
```

---

### Field

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Combine labels, controls, help text, and validation messages for accessible forms. Complete form field wrapper with proper ARIA attributes.

**Components & Parameters:**

#### `Field`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Orientation` | `FieldOrientation` | `FieldOrientation.Vertical` | Gets or sets the orientation of the field layout. Controls the layout direction and behavior: - Vertical: Stacks label above control (default, mobile-first) - Horizontal: Places label beside control with aligned items - Responsive: Automatically switches from vertical to horizontal at medium breakpoint Default value is . |
| `IsInvalid` | `bool` |  | Gets or sets whether the field is in an invalid/error state. When true, applies error styling via the data-invalid attribute. This enables conditional styling for validation errors. Default value is false. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the field. Custom classes are merged with the component's base classes, allowing for style overrides and extensions. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the field. Typically contains FieldLabel, FieldContent, FieldDescription, and FieldError components for a complete form field. |

#### `FieldContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the field content container. Custom classes are merged with the component's base classes, allowing for style overrides and extensions. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the field content container. Typically contains an input control, followed by optional FieldDescription and FieldError components. |

#### `FieldDescription`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Id` | `string?` |  | Gets or sets the ID for aria-describedby association. When set, this ID should be referenced by the associated input's aria-describedby attribute for proper accessibility. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the description. Custom classes are merged with the component's base classes, allowing for style overrides and extensions. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the description. Typically contains helpful text explaining the purpose or format of the associated form field. |

#### `FieldError`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Errors` | `IEnumerable<string>?` |  | Gets or sets the array of error messages to display. When provided, each error is rendered as a bulleted list item. If both Errors and ChildContent are provided, Errors takes precedence. Component only renders when errors are present or ChildContent is not null. |
| `Id` | `string?` |  | Gets or sets the ID for aria-describedby association. When set, this ID should be referenced by the associated input's aria-describedby attribute for proper accessibility. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the error container. Custom classes are merged with the component's base classes, allowing for style overrides and extensions. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets custom error content to be rendered. Used when you need custom error rendering beyond simple text messages. If both Errors and ChildContent are provided, Errors takes precedence. |

#### `FieldGroup`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Orientation` | `FieldGroupOrientation` | `FieldGroupOrientation.Vertical` | Gets or sets the orientation of the field group layout. Controls the layout direction: - Vertical: Stacks fields vertically (default) - Horizontal: Places fields horizontally with wrap support - Responsive: Uses container queries to adapt layout based on available space Default value is . |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the field group. Custom classes are merged with the component's base classes, allowing for style overrides and extensions. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the field group. Typically contains multiple Field components. |

#### `FieldLabel`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `For` | `string?` |  | Gets or sets the ID of the form control this label is associated with. Should match the ID of the input element for proper accessibility. Enables clicking the label to focus the associated input. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the label. Custom classes are merged with the component's base classes, allowing for style overrides and extensions. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the label. Typically contains text describing the associated form control. Can also include required indicators, tooltips, etc. |

#### `FieldLegend`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Variant` | `FieldLegendVariant` | `FieldLegendVariant.Legend` | Gets or sets the variant of the legend element. Controls the HTML element used: - Legend: Renders a semantic legend element (use with FieldSet) - Label: Renders a div with role="group" (use with FieldGroup) Default value is . |
| `AriaLabel` | `string?` |  | Gets or sets the ARIA label when using Label variant. Provides an accessible name for the group when variant is Label. Only applicable when Variant is FieldLegendVariant.Label. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the legend. Custom classes are merged with the component's base classes, allowing for style overrides and extensions. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the legend. Typically contains text describing the grouped form fields. |

#### `FieldSeparator`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the separator. Custom classes are merged with the component's base classes, allowing for style overrides and extensions. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to display in the center of the separator. When provided, the content appears centered on top of the separator line with background color to create a visual break in the line. Typically used for text like "Or" or "Or continue with". |

#### `FieldSet`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the fieldset. Custom classes are merged with the component's base classes, allowing for style overrides and extensions. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the fieldset. Typically contains a FieldLegend followed by multiple Field components for grouped form controls. |

#### `FieldTitle`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the title. Custom classes are merged with the component's base classes, allowing for style overrides and extensions. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the title. Typically contains text describing the field or group of controls. |

**Basic Usage:**
```razor
<Field>
 <FieldLabel>Email</FieldLabel>
 <FieldContent>
  <Input Type="InputType.Email" @bind-Value="email" />
 </FieldContent>
 <FieldHelpText>We'll never share your email.</FieldHelpText>
</Field>

@* With validation *@
<EditForm Model="model">
 <DataAnnotationsValidator />
 <Field>
  <FieldLabel>Username</FieldLabel>
  <FieldContent>
<Input @bind-Value="model.Username" />
  </FieldContent>
  <FieldValidationMessage For="() => model.Username" />
 </Field>
</EditForm>

@code {
 private string email = "";
 private FormModel model = new();
 
 public class FormModel 
 {
  [Required]
  public string Username { get; set; } = "";
 }
}
```

---

### FileUpload

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Drag-and-drop file upload with image previews, upload progress indicator, file type/size validation, and EditForm integration.

**Components & Parameters:**

#### `FileUpload`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Files` | `List<IBrowserFile>?` |  | The bound file list. Use `@bind-Files` for two-way binding. |
| `FilesChanged` | `EventCallback<List<IBrowserFile>?>` |  | Callback invoked when files change. |
| `Multiple` | `bool` | `false` | Allow selecting multiple files. |
| `Accept` | `string?` |  | Accepted file types (e.g., `"image/*"`, `".pdf,.docx"`). |
| `MaxFileSize` | `long` | `10485760` | Maximum file size in bytes (default: 10 MB). |
| `MaxFiles` | `int?` |  | Maximum number of files. |
| `ShowPreview` | `bool` | `true` | Show image thumbnail previews. |
| `ShowProgress` | `bool` | `true` | Show upload progress bar. |
| `Disabled` | `bool` | `false` | Disable the upload area. |
| `Required` | `bool` | `false` | Mark as required. |
| `ShowValidationError` | `bool` | `false` | Show validation error from EditContext. |
| `Class` | `string?` |  | Additional CSS classes. |
| `Id` | `string?` |  | HTML id attribute. |


**Basic Usage:**
```razor
<FileUpload @bind-Files="uploadedFiles"
            Multiple="true"
            Accept="image/*"
            MaxFileSize="5242880" />

@code {
    private List<IBrowserFile> uploadedFiles = new();
}
```

---

### FilterBuilder

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Inline filter canvas that renders chip-based filter conditions in a toolbar. Supports 8 field types (Text, Number, Date, DateRange, Boolean, Select, MultiSelect, Custom), a preset system for saving named filter sets, and LINQ `.ApplyFilter()` / `.ApplyFilters()` extension methods for filtering any `IEnumerable<T>` or `IQueryable<T>`.

**Components & Parameters:**

#### `FilterBuilder<TData>`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Filters` | `FilterGroup?` |  | Two-way bound filter state. Use `@bind-Filters`. |
| `FiltersChanged` | `EventCallback<FilterGroup>` |  | Callback invoked on filter change. |
| `OnFilterChange` | `EventCallback<FilterGroup>` |  | Fires on every condition change (use for live filtering). |
| `FilterFields` | `RenderFragment?` |  | Slot for `FilterField` declarations. |
| `FilterPresets` | `RenderFragment?` |  | Slot for `FilterPreset` declarations. |
| `ButtonText` | `string` | `"Filter"` | Label on the add-filter button. |
| `PresetsVariant` | `FilterPresetsVariant` | `Dropdown` | Preset display style: `Dropdown` or `Tabs`. |
| `ChipSize` | `FilterChipSize` | `Small` | Filter chip size: `Small`, `Medium`, `Large`. |
| `Class` | `string?` |  | Additional CSS classes. |

#### `FilterField`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Field` | `string` |  | **Required.** Property name on the data model. |
| `Label` | `string` |  | **Required.** Display label for the field. |
| `Type` | `FilterFieldType` | `Text` | Field type: `Text`, `Number`, `Date`, `DateRange`, `Boolean`, `Select`, `MultiSelect`, `Custom`. |
| `EditorType` | `FilterEditorType` | `Auto` | Editor override (e.g., `Currency`, `Slider`, `Custom`). |
| `Icon` | `string?` |  | Lucide icon name for the filter chip. |
| `Operators` | `IEnumerable<FilterOperator>?` |  | Override allowed operators for this field. |
| `DefaultOperator` | `FilterOperator?` |  | Default operator when adding a condition. |
| `Options` | `IEnumerable<SelectOption>?` |  | Options for Select/MultiSelect fields. |
| `Placeholder` | `string?` |  | Placeholder text for the filter input. |
| `Min` / `Max` / `Step` | `object?` |  | Range constraints for Number fields. |
| `ChildContent` | `RenderFragment<FilterCustomContext>?` |  | Custom editor slot (requires `EditorType.Custom`). |

#### `FilterPreset`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Name` | `string` |  | **Required.** Display name of the preset. |
| `Filters` | `FilterGroup` |  | **Required.** The preset filter conditions. |
| `Icon` | `string?` |  | Lucide icon name. |
| `Description` | `string?` |  | Tooltip/description for the preset. |

**LINQ extension methods** (from `FilterExtensions`):
```csharp
// Works on IEnumerable<T> and IQueryable<T>
filteredList = allItems.ApplyFilter(activeFilters);
filteredList = allItems.ApplyFilters(activeFilters);
```


**Basic Usage:**
```razor
<FilterBuilder TData="Product"
               @bind-Filters="activeFilters"
               OnFilterChange="HandleFilterChange">
    <FilterFields>
        <FilterField Field="Name"
                     Label="Product Name"
                     Icon="tag"
                     Type="FilterFieldType.Text"
                     Placeholder="Search by name..." />
        <FilterField Field="Category"
                     Label="Category"
                     Icon="layers"
                     Type="FilterFieldType.Select"
                     Options="@categoryOptions" />
        <FilterField Field="Price"
                     Label="Price"
                     Icon="dollar-sign"
                     Type="FilterFieldType.Number"
                     EditorType="FilterEditorType.Currency"
                     Min="0"
                     Step="0.01" />
        <FilterField Field="InStock"
                     Label="In Stock"
                     Icon="package"
                     Type="FilterFieldType.Boolean" />
    </FilterFields>
</FilterBuilder>

@code {
    private FilterGroup activeFilters = new();
    private List<Product> filteredProducts = new();

    private readonly List<SelectOption> categoryOptions =
    [
        new("Electronics", "Electronics"),
        new("Clothing", "Clothing"),
        new("Books", "Books"),
    ];

    private void HandleFilterChange(FilterGroup filters)
    {
        filteredProducts = allProducts.ApplyFilters(filters).ToList();
    }
}
```

---

### DataGrid

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@* DataGrid<TItem> is in the root NeoUI.Blazor namespace — no extra @using needed *@
```

**Description:**
High-performance AG Grid wrapper for Blazor. Supports client-side, server-side (`BlazorServerSide`), infinite-scroll, and virtualized row models. Features include column sorting/filtering/resizing/reordering/pinning, multi-row selection, inline cell editing, custom cell templates, and deep theming. `BlazorServerSide` row model delivers full server-side paging, sorting, and filtering without an AG Grid Enterprise license.

> **See also:** [`datagrid.txt`](datagrid.txt), [`grid-quick-reference.txt`](../blazor-shadcn-ui/llms/grid-quick-reference.txt) for advanced theming and configuration details.

**Components & Parameters:**

#### `DataGrid<TItem>`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ActionHost` | `object?` |  | Gets or sets the host component that contains grid action methods. Set this to 'this' to enable auto-discovery of methods marked with [DataGridAction]. |
| `Items` | `IEnumerable<TItem>` | `Array.Empty<TItem>()` | Gets or sets the collection of items to display in the grid. |
| `SelectionMode` | `DataGridSelectionMode` | `DataGridSelectionMode.None` | Gets or sets the selection mode for the grid. |
| `PagingMode` | `DataGridPagingMode` | `DataGridPagingMode.None` | Gets or sets the paging mode for the grid. |
| `PageSize` | `int` | `25` | Gets or sets the number of items per page. Must be greater than 0. Default is 25. |
| `IdField` | `string` | `"Id"` | Gets or sets the property name to use as the unique row identifier. Required for `BlazorServerSide` row model. Default is "Id". |
| `VirtualizationMode` | `DataGridVirtualizationMode` | `DataGridVirtualizationMode.Auto` | Gets or sets the virtualization mode for the grid. |
| `Theme` | `DataGridTheme` | `DataGridTheme.Shadcn` | Gets or sets the AG DataGrid theme to use (Shadcn, Alpine, Balham, Material, Quartz). |
| `VisualStyle` | `DataGridStyle` | `DataGridStyle.Default` | Gets or sets the visual style modifiers (Default, Striped, Bordered, Minimal). |
| `Density` | `DataGridDensity` | `DataGridDensity.Compact` | Gets or sets the spacing density. Values: `Compact`, `Medium`, `Spacious`. `DataGridDensity.Comfortable` is an `[Obsolete]` alias for `Medium`. |
| `SuppressHeaderMenus` | `bool` | `false` | Gets or sets whether to suppress the header menus (filter/column menu). |
| `State` | `DataGridState?` |  | Gets or sets the current state of the grid. Supports `@bind-State`. |
| `StateChanged` | `EventCallback<DataGridState>` |  | Gets or sets the callback invoked when the grid state changes. |
| `IsLoading` | `bool` |  | Gets or sets whether the grid is in a loading state. |
| `Columns` | `RenderFragment?` |  | Gets or sets the child content containing DataGridColumn definitions. |
| `LoadingTemplate` | `RenderFragment?` |  | Gets or sets the template to display while the grid is loading. |
| `InitializingTemplate` | `RenderFragment?` |  | Shown during first-time grid initialization (distinct from `IsLoading`). |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the grid container. |
| `Height` | `string?` |  | Gets or sets the height of the grid (e.g., "500px", "100%"). Defaults to "300px". |
| `Width` | `string?` |  | Gets or sets the width of the grid. Defaults to "100%". |
| `FillWidth` | `bool` | `false` | When true, columns without an explicit Width receive `flex:1` and fill all available horizontal space. |
| `AutoSizeColumns` | `bool` | `false` | Automatically sizes all columns to fit their content after data loads. |
| `InlineStyle` | `string?` |  | Gets or sets inline styles to apply to the grid container. |
| `LocalizationKeyPrefix` | `string?` |  | Gets or sets the localization key prefix for grid text resources. |
| `OnStateChanged` | `EventCallback<DataGridState>` |  | Gets or sets the callback invoked when the grid state changes. |
| `RowModelType` | `DataGridRowModelType` | `DataGridRowModelType.ClientSide` | Gets or sets the row model type. Use `BlazorServerSide` for license-free server-side data. |
| `OnServerDataRequest` | `Func<DataGridDataRequest<TItem>, Task<DataGridDataResponse<TItem>>>?` |  | Callback for server-side data. Required when RowModelType is `ServerSide`, `Infinite`, or `BlazorServerSide`. |
| `ServerDataProvider` | `IDataGridServerDataProvider<TItem>?` |  | External provider for `BlazorServerSide` row model. Takes priority over `OnServerDataRequest`. |
| `TotalServerRowCount` | `int` | `0` | Two-way bindable total row count. Auto-updated after each `BlazorServerSide` fetch. Use `@bind-TotalServerRowCount`. |
| `TotalServerRowCountChanged` | `EventCallback<int>` |  | Raised when `TotalServerRowCount` changes. Supports `@bind-TotalServerRowCount`. |
| `OnDataRequest` | `EventCallback<DataGridDataRequest<TItem>>` |  | Legacy EventCallback version of server data request. Prefer `OnServerDataRequest` for new code. |
| `OnSelectionChanged` | `EventCallback<IReadOnlyCollection<TItem>>` |  | Gets or sets the callback invoked when the selection changes. |
| `OnGridReady` | `Action?` |  | Callback fired once when the AG Grid instance is fully initialized. |
| `SelectedItems` | `IReadOnlyCollection<TItem>` | `Array.Empty<TItem>()` | Gets or sets the selected items in the grid. |
| `SelectedItemsChanged` | `EventCallback<IReadOnlyCollection<TItem>>` |  | Gets or sets the callback invoked when the selected items change (for two-way binding). |

#### `DataGridRowModelType` enum

| Value | Description |
|---|---|
| `ClientSide` | All data loaded client-side (default). |
| `ServerSide` | AG Grid Enterprise ServerSide row model. |
| `Infinite` | Infinite scroll with server requests per block. |
| `BlazorServerSide` | **License-free** Blazor-native server-side model. Paging/sorting/filtering orchestrated from C#. No Enterprise license required. Requires `IdField`. |

#### Server-side data providers

```csharp
// Implement for any async data source
public interface IDataGridServerDataProvider<TItem>
{
    Task<DataGridDataResponse<TItem>> GetDataAsync(DataGridDataRequest<TItem> request, CancellationToken ct = default);
}

// Abstract base for HTTP endpoints
public abstract class HttpDataGridProvider<TItem> : IDataGridServerDataProvider<TItem> { }
```

#### Public API methods

| Method | Description |
|---|---|
| `AutoSizeColumnsAsync()` | Programmatically trigger column auto-sizing after load. |
| `OnFetchServerDataAsync(DataGridDataRequest<TItem>)` | Virtual — override in a subclass to provide data (code-behind pattern). |

#### `DataGridColumn`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Id` | `string?` |  | Gets or sets the unique identifier for this column. If not specified, it will be generated from Field or Header. |
| `Field` | `string?` |  | Gets or sets the field name for data binding (e.g., "CustomerName"). This is a string field name, NOT a lambda expression. |
| `Sortable` | `bool` |  | Gets or sets whether the column is sortable. |
| `Filterable` | `bool` |  | Gets or sets whether the column is filterable. |
| `Width` | `string?` |  | Gets or sets the column width (e.g., "100px", "20%"). |
| `MinWidth` | `string?` |  | Gets or sets the minimum column width. |
| `MaxWidth` | `string?` |  | Gets or sets the maximum column width. |
| `Pinned` | `DataDataGridColumnPinPosition` | `DataDataGridColumnPinPosition.None` | Gets or sets the column pinning position. |
| `AllowResize` | `bool` | `true` | Gets or sets whether the column can be resized. |
| `AllowReorder` | `bool` | `true` | Gets or sets whether the column can be reordered. |
| `IsVisible` | `bool` | `true` | Gets or sets whether the column is visible. |
| `CellTemplate` | `RenderFragment<TItem>?` |  | Gets or sets the cell template for rendering cell content. |
| `HeaderTemplate` | `RenderFragment?` |  | Gets or sets the header template for custom header rendering. |
| `FilterTemplate` | `RenderFragment?` |  | Gets or sets the filter template for custom filter UI. |
| `CellEditTemplate` | `RenderFragment<TItem>?` |  | Gets or sets the cell edit template for inline editing. |
| `ValueSelector` | `Func<TItem, object?>?` |  | Gets or sets the value selector function for extracting cell values. |
| `CellClass` | `string?` |  | Gets or sets the CSS class to apply to cells in this column. |
| `HeaderClass` | `string?` |  | Gets or sets the CSS class to apply to the column header. |
| `DataFormatString` | `string?` |  | Gets or sets the format string for displaying cell values. Supports standard .NET format strings (e.g., "C" for currency, "N2" for numbers with 2 decimals, "d" for dates). Can also use composite format strings (e.g., "{0:C}", "{0:N2}"). This is a simpler alternative to CellTemplate for basic formatting scenarios. &lt;DataGridColumn Field="Price" Header="Price" DataFormatString="C" /&gt;  // $1,234.56 &lt;DataGridColumn Field="Quantity" Header="Quantity" DataFormatString="N0" /&gt;  // 1,234 &lt;DataGridColumn Field="Date" Header="Date" DataFormatString="d" /&gt;  // 12/31/2024 &lt;DataGridColumn Field="Percentage" Header="%" DataFormatString="P2" /&gt;  // 45.67% |

#### `DataGridImportMap`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| *(No parameters)* | | | |

#### `DataDataGridThemeParameters`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Spacing` | `int?` |  | Base spacing unit (px). Default by density: Compact=3, Medium=4, Spacious=6. |
| `RowHeight` | `int?` |  | Row height (px). Default by density: Compact=28, Medium=42, Spacious=56. |
| `HeaderHeight` | `int?` |  | Header height (px). Default by density: Compact=32, Medium=48, Spacious=64. |
| `IconSize` | `int?` |  | Icon size (px). Default by density: Compact=14, Medium=16, Spacious=20. |
| `InputHeight` | `int?` |  | Input element height (px). Default by density: Compact=28, Medium=32, Spacious=40. |
| `FontSize` | `int?` |  | Base font size (px). Default by density: Compact=12, Medium=14, Spacious=16. |

**Basic Usage:**
```razor
@* Client-side DataGrid *@
<DataGrid TItem="Product" Items="@products" Height="500px" Density="DataGridDensity.Compact">
 <Columns>
  <DataGridColumn Field="Name" Header="Product" Sortable="true" Filterable="true" />
  <DataGridColumn Field="Price" Header="Price" DataFormatString="C" Sortable="true" />
  <DataGridColumn Field="Stock" Header="Stock" />
 </Columns>
</DataGrid>

@* BlazorServerSide (license-free server-side paging/sorting/filtering) *@
<DataGrid TItem="Order"
          RowModelType="DataGridRowModelType.BlazorServerSide"
          ServerDataProvider="@_orderProvider"
          @bind-TotalServerRowCount="_total"
          Height="600px">
 <Columns>
  <DataGridColumn Field="Id" Header="Order #" Sortable="true" />
  <DataGridColumn Field="Total" Header="Total" DataFormatString="C" Sortable="true" />
  <DataGridColumn Field="Status" Header="Status" Filterable="true" />
 </Columns>
</DataGrid>
```

---

### HeightAnimation

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Smooth height transition animation component. Animates content height changes for expand/collapse effects.

**Components & Parameters:**

#### `HeightAnimation`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to be rendered inside the animated container. |
| `Config` | `HeightAnimationConfig?` |  | Configuration for the height animation behavior. |
| `Class` | `string?` |  | Additional CSS classes to apply to the container element. |
| `Style` | `string?` |  | Additional inline styles to apply to the container element. |
| `Enabled` | `bool` | `true` | Whether the animation is currently enabled. When false, no animation setup will occur. |

**Basic Usage:**
```razor
<HeightAnimation>
 @if (isExpanded)
 {
  <div>
<p>This content animates when shown/hidden.</p>
<p>Height transitions smoothly.</p>
  </div>
 }
</HeightAnimation>

<Button OnClick="() => isExpanded = !isExpanded">
 Toggle
</Button>

@code {
 private bool isExpanded = false;
}
```

---

### HoverCard

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Rich hover previews with delay support. Displays detailed information on hover with smooth transitions.

**Components & Parameters:**

#### `HoverCard`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render within the hover card. Should include HoverCardTrigger and HoverCardContent components. |
| `Open` | `bool?` |  | Controls whether the hover card is open (controlled mode). |
| `OpenChanged` | `EventCallback<bool>` |  | Event callback invoked when the open state changes. |
| `DefaultOpen` | `bool` | `false` | Default open state when in uncontrolled mode. |
| `OnOpenChange` | `EventCallback<bool>` |  | Event callback invoked when the hover card open state changes. |
| `OpenDelay` | `int` | `700` | Delay in milliseconds before opening the hover card. Default is 700ms. |
| `CloseDelay` | `int` | `300` | Delay in milliseconds before closing the hover card. Default is 300ms. |

#### `HoverCardContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render inside the hover card. |
| `Side` | `PopoverSide` | `PopoverSide.Bottom` | Preferred side for positioning. |
| `Align` | `PopoverAlign` | `PopoverAlign.Center` | Alignment relative to trigger. |
| `Offset` | `int` | `4` | Offset distance from trigger in pixels. |
| `Class` | `string?` |  | Additional CSS classes to apply to the content. |

#### `HoverCardTrigger`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render within the trigger. |
| `AsChild` | `bool` | `false` | When true, the trigger does not render its own div element. Instead, it passes trigger behavior via TriggerContext to child components. Use this when you want a custom component to act as the trigger. |
| `Class` | `string?` |  | Additional CSS classes to apply to the trigger. |

**Basic Usage:**
```razor
<HoverCard>
 <HoverCardTrigger AsChild>
  <Button Variant="ButtonVariant.Link">johndoe</Button>
 </HoverCardTrigger>
 <HoverCardContent>
  <div class="space-y-2">
<h4 class="font-semibold">John Doe</h4>
<p class="text-sm">Full stack developer</p>
<div class="flex gap-2 text-sm text-muted-foreground">
 <span>Joined March 2024</span>
</div>
  </div>
 </HoverCardContent>
</HoverCard>
```

---

### Input

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Text input with multiple types (text, email, password, number, etc.) and validation support. Full-featured form input component.

**Components & Parameters:**

#### `Input`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Type` | `InputType` | `InputType.Text` | Gets or sets the type of input. Determines the HTML input type attribute. Default value is . |
| `Value` | `string?` |  | Gets or sets the current value of the input. Supports two-way binding via @bind-Value syntax. |
| `ValueChanged` | `EventCallback<string?>` |  | Gets or sets the callback invoked when the input value changes. This event is fired on every keystroke (oninput event). Use with Value parameter for two-way binding. |
| `Placeholder` | `string?` |  | Gets or sets the placeholder text displayed when the input is empty. Provides a hint to the user about what to enter. Should not be used as a replacement for a label. |
| `Disabled` | `bool` |  | Gets or sets whether the input is disabled. When disabled: - Input cannot be focused or edited - Cursor is set to not-allowed - Opacity is reduced for visual feedback |
| `Required` | `bool` |  | Gets or sets whether the input is required. When true, the HTML5 required attribute is set. Works with form validation and :invalid CSS pseudo-class. |
| `Name` | `string?` |  | Gets or sets the name of the input for form submission. This is critical for form submission. The name/value pair is submitted to the server. Should be unique within the form. |
| `Autocomplete` | `string?` |  | Gets or sets the autocomplete hint for the browser. Examples: "email", "username", "current-password", "new-password", "name", "tel", "off". Helps browsers provide appropriate autofill suggestions. |
| `Readonly` | `bool` |  | Gets or sets whether the input is read-only. When true, the user cannot modify the value, but it's still focusable and submitted with forms. Different from Disabled - readonly inputs are still submitted with forms. |
| `MaxLength` | `int?` |  | Gets or sets the maximum number of characters allowed. When set, the browser will prevent users from entering more characters. Applies to text, email, password, tel, url, and search types. |
| `MinLength` | `int?` |  | Gets or sets the minimum number of characters required. Works with form validation. Applies to text, email, password, tel, url, and search types. |
| `Min` | `string?` |  | Gets or sets the minimum value for number, date, or time inputs. Applies to number, date, time inputs. Works with form validation and :invalid pseudo-class. |
| `Max` | `string?` |  | Gets or sets the maximum value for number, date, or time inputs. Applies to number, date, time inputs. Works with form validation and :invalid pseudo-class. |
| `Step` | `string?` |  | Gets or sets the step interval for number inputs. Defines the granularity of values (e.g., "0.01" for currency, "1" for integers). Applies to number, date, time inputs. |
| `Pattern` | `string?` |  | Gets or sets the regex pattern for validation. Validates input against the specified regular expression. Works with form validation and :invalid pseudo-class. |
| `InputMode` | `string?` |  | Gets or sets the input mode hint for mobile keyboards. Examples: "none", "text", "decimal", "numeric", "tel", "search", "email", "url". Helps mobile devices show the appropriate keyboard. |
| `Autofocus` | `bool` |  | Gets or sets whether the input should be auto-focused when the page loads. Only one element per page should have autofocus. Improves accessibility when used appropriately. |
| `Spellcheck` | `bool?` |  | Gets or sets whether spell checking is enabled. Can be true, false, or null (browser default). Useful for controlling spell checking on email addresses, usernames, etc. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the input. Custom classes are appended after the component's base classes, allowing for style overrides and extensions. |
| `Id` | `string?` |  | Gets or sets the HTML id attribute for the input element. Used to associate the input with a label element via the label's 'for' attribute. This is essential for accessibility and allows clicking the label to focus the input. |
| `AriaLabel` | `string?` |  | Gets or sets the ARIA label for the input. Provides an accessible name for screen readers. Use when there is no visible label element. |
| `AriaDescribedBy` | `string?` |  | Gets or sets the ID of the element that describes the input. References the id of an element containing help text or error messages. Improves screen reader experience by associating descriptive text. |
| `AriaInvalid` | `bool?` |  | Gets or sets whether the input value is invalid. When true, aria-invalid="true" is set. Should be set based on validation state. |

**Basic Usage:**
```razor
@* Text input *@
<Input @bind-Value="name" Placeholder="Enter name" />

@* Email input *@
<Input Type="InputType.Email" @bind-Value="email" />

@* Password input *@
<Input Type="InputType.Password" @bind-Value="password" />

@* Disabled input *@
<Input Value="Disabled" Disabled="true" />

@code {
 private string name = "";
 private string email = "";
 private string password = "";
}
```

---

### InputGroup

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Enhanced inputs with icons, buttons, and addons. Combines input with prefix/suffix elements.

**Components & Parameters:**

#### `InputGroup`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content to be rendered inside the input group. Typically contains InputGroupInput/InputGroupTextarea and InputGroupAddon components. The order of child components affects the visual layout and keyboard navigation. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the input group container. Custom classes are merged with the component's base classes using TailwindMerge, allowing for intelligent conflict resolution. |

#### `InputGroupAddon`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Align` | `InputGroupAlign` | `InputGroupAlign.InlineStart` | Gets or sets the alignment position of the addon. Determines where the addon content appears relative to the input: - InlineStart: Left side (or right in RTL) - InlineEnd: Right side (or left in RTL) - BlockStart: Above the input - BlockEnd: Below the input |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content to be rendered inside the addon. Can contain icons, buttons, text, or any other content. The component automatically adjusts padding based on content type. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the addon container. |

#### `InputGroupButton`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Type` | `ButtonType` | `ButtonType.Button` | Gets or sets the button type (submit, button, reset). |
| `Variant` | `ButtonVariant` | `ButtonVariant.Default` | Gets or sets the button visual variant. |
| `Size` | `ButtonSize` | `ButtonSize.Small` | Gets or sets the button size. Default is Small for better proportions within input groups. |
| `Disabled` | `bool` |  | Gets or sets whether the button is disabled. |
| `AriaLabel` | `string?` |  | Gets or sets the ARIA label for accessibility. |
| `OnClick` | `EventCallback` |  | Gets or sets the click event handler. |
| `Icon` | `RenderFragment?` |  | Gets or sets the icon to display in the button. |
| `IconPosition` | `IconPosition` | `IconPosition.Start` | Gets or sets the position of the icon relative to button text. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content (button text). |
| `Class` | `string?` |  | Gets or sets additional CSS classes. |

#### `InputGroupInput`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Type` | `InputType` | `InputType.Text` | Gets or sets the type of input. |
| `Value` | `string?` |  | Gets or sets the current value of the input. |
| `ValueChanged` | `EventCallback<string?>` |  | Gets or sets the callback invoked when the input value changes. |
| `Placeholder` | `string?` |  | Gets or sets the placeholder text. |
| `Disabled` | `bool` |  | Gets or sets whether the input is disabled. |
| `Required` | `bool` |  | Gets or sets whether the input is required. |
| `Class` | `string?` |  | Gets or sets additional CSS classes. |
| `Id` | `string?` |  | Gets or sets the HTML id attribute. |
| `AriaLabel` | `string?` |  | Gets or sets the ARIA label. |
| `AriaDescribedBy` | `string?` |  | Gets or sets the ARIA described-by attribute. |
| `AriaInvalid` | `bool?` |  | Gets or sets whether the input value is invalid. |

#### `InputGroupText`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content (text or icons). |
| `Class` | `string?` |  | Gets or sets additional CSS classes. |

#### `InputGroupTextarea`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Value` | `string?` |  | Gets or sets the current value of the textarea. |
| `ValueChanged` | `EventCallback<string?>` |  | Gets or sets the callback invoked when the textarea value changes. |
| `Rows` | `int` | `3` | Gets or sets the number of visible text rows. Default is 3 rows. The textarea can grow beyond this if resize is enabled. |
| `Placeholder` | `string?` |  | Gets or sets the placeholder text. |
| `Disabled` | `bool` |  | Gets or sets whether the textarea is disabled. |
| `Required` | `bool` |  | Gets or sets whether the textarea is required. |
| `Class` | `string?` |  | Gets or sets additional CSS classes. |
| `Id` | `string?` |  | Gets or sets the HTML id attribute. |
| `AriaLabel` | `string?` |  | Gets or sets the ARIA label. |
| `AriaDescribedBy` | `string?` |  | Gets or sets the ARIA described-by attribute. |
| `AriaInvalid` | `bool?` |  | Gets or sets whether the textarea value is invalid. |

**Basic Usage:**
```razor
@* With prefix icon *@
<InputGroup>
 <InputGroupPrefix>
  <LucideIcon Name="search" Size="16" />
 </InputGroupPrefix>
 <Input @bind-Value="searchTerm" Placeholder="Search..." />
</InputGroup>

@* With suffix button *@
<InputGroup>
 <Input @bind-Value="email" Type="InputType.Email" />
 <InputGroupSuffix>
  <Button Size="ButtonSize.Small">Subscribe</Button>
 </InputGroupSuffix>
</InputGroup>

@code {
 private string searchTerm = "";
 private string email = "";
}
```

---

### InputOtp

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
One-time password input with individual character slots. Specialized input for OTP/PIN entry with auto-focus.

**Components & Parameters:**

#### `InputOtp`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render within the OTP input. Typically includes InputOtpSlot components or InputOtpGroup with slots. |
| `Class` | `string?` |  | Additional CSS classes to apply to the container. |
| `Length` | `int` | `6` | The number of OTP slots. Default is 6. |
| `Value` | `string?` |  | Controls the OTP value (controlled mode). |
| `ValueChanged` | `EventCallback<string>` |  | Event callback invoked when the OTP value changes. Use with @bind-Value for two-way binding. |
| `DefaultValue` | `string` | `""` | Default value when in uncontrolled mode. |
| `OnValueChange` | `EventCallback<string>` |  | Event callback invoked when the OTP value changes. |
| `OnComplete` | `EventCallback<string>` |  | Event callback invoked when the OTP is complete. |
| `Pattern` | `string` | `"[0-9]"` | Pattern for input validation (e.g., "[0-9]" for digits only). Default is digits only. |
| `Disabled` | `bool` | `false` | Whether the OTP input is disabled. |
| `AriaLabel` | `string` | `"One-time password"` | ARIA label for the OTP input group. |
| `AriaInvalid` | `bool` | `false` | Whether the OTP input is in an invalid/error state. When true, aria-invalid="true" is set on the slots, applying error styling. |

#### `InputOtpGroup`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content, typically InputOtpSlot components. |
| `Class` | `string?` |  | Additional CSS classes to apply to the group. |

#### `InputOtpSeparator`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Optional custom content for the separator. If not provided, displays a minus/dash icon. |
| `Class` | `string?` |  | Additional CSS classes to apply to the separator. |

#### `InputOtpSlot`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Index` | `int` |  | The index of this slot (0-based). |
| `Class` | `string?` |  | Additional CSS classes to apply to the slot. |

**Basic Usage:**
```razor
<InputOtp @bind-Value="otpCode" Length="6" />

@* With custom pattern *@
<InputOtp @bind-Value="otpCode" 
 Length="6" 
 Pattern="[0-9]*" />

@code {
 private string otpCode = "";
}
```

---

### Item

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Flexible list items with media, content, and action slots. Reusable component for building lists and menus.

**Components & Parameters:**

#### `Item`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Variant` | `ItemVariant` | `ItemVariant.Default` | Gets or sets the visual style variant of the item. |
| `Size` | `ItemSize` | `ItemSize.Default` | Gets or sets the size of the item. |
| `AsChild` | `string?` |  | Gets or sets the element type to render as (e.g., "a", "button"). When set, the component renders as that element instead of a div. |
| `Href` | `string?` |  | Gets or sets the href attribute when rendering as an anchor. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the item. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the item. |
| `DataSlot` | `string?` |  |  |
| `ChildContent` | `RenderFragment?` |  |  |
| `DataSlot` | `string?` |  |  |
| `href` | `string?` |  |  |
| `ChildContent` | `RenderFragment?` |  |  |
| `DataSlot` | `string?` |  |  |
| `ChildContent` | `RenderFragment?` |  |  |

#### `ItemActions`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the actions container. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the actions container. |

#### `ItemContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the content container. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the container. |

#### `ItemDescription`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the description. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered as the description. |

#### `ItemFooter`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the footer. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered in the footer. |

#### `ItemGroup`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the container. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the group. |

#### `ItemHeader`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the header. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered in the header. |

#### `ItemMedia`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Variant` | `ItemMediaVariant` | `ItemMediaVariant.Default` | Gets or sets the visual style variant of the media. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the media container. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the media container. |

#### `ItemSeparator`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the separator. |

#### `ItemTitle`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the title. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered as the title. |

**Basic Usage:**
```razor
<Item>
 <ItemMedia>
  <Avatar>
<AvatarFallback>JD</AvatarFallback>
  </Avatar>
 </ItemMedia>
 <ItemContent>
  <ItemTitle>John Doe</ItemTitle>
  <ItemDescription>john@example.com</ItemDescription>
 </ItemContent>
 <ItemAction>
  <Button Size="ButtonSize.Icon" Variant="ButtonVariant.Ghost">
<LucideIcon Name="more-vertical" Size="16" />
  </Button>
 </ItemAction>
</Item>
```

---

### Kbd

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Keyboard shortcut badges for displaying key combinations. Shows keyboard shortcuts in styled format.

**Components & Parameters:**

#### `Kbd`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the kbd element. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the kbd element. Typically contains a single key name (e.g., "Ctrl", "Shift", "Enter") or a key symbol (e.g., "⌘", "⌥", "⇧"). |

**Basic Usage:**
```razor
@* Single key *@
<Kbd>Ctrl</Kbd>

@* Key combination *@
<div class="flex gap-1">
 <Kbd>Ctrl</Kbd>
 <span>+</span>
 <Kbd>C</Kbd>
</div>

@* In text *@
<p>Press <Kbd>Enter</Kbd> to submit</p>
```

---

### Label

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Accessible form labels with proper for/id association. Connects labels to form controls for accessibility.

**Components & Parameters:**

#### `Label`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `For` | `string?` |  | Gets or sets the ID of the form element this label is associated with. A string containing the ID of the target form control, or null. This parameter maps to the HTML for attribute (htmlFor in JSX). When set, clicking the label will focus or activate the associated form control. Best practices: Always provide a For value for explicit label-control association Ensure the For value matches the Id of the target form control Use meaningful IDs that describe the field's purpose |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the label element. A string containing one or more CSS class names, or null. Use this parameter to customize the label's appearance beyond default styling. Common Tailwind utilities include: Text size: text-lg, text-sm Font weight: font-bold, font-normal Color: text-muted-foreground, text-destructive Spacing: mb-2, mr-2 |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the label element. A  containing the label's content, or null. Typically contains the label text, but can include additional elements such as: Required field indicators (asterisks, badges) Help text or tooltips Icons or visual indicators Nested spans for styling portions of text |

**Basic Usage:**
```razor
<Label For="email">Email Address</Label>
<Input Id="email" Type="InputType.Email" @bind-Value="email" />

@code {
 private string email = "";
}
```

---

### MarkdownEditor

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Rich text editor with toolbar formatting and live preview. Full-featured markdown editing with syntax highlighting.

**Components & Parameters:**

#### `MarkdownEditor`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Value` | `string?` |  | Gets or sets the markdown content value. |
| `ValueChanged` | `EventCallback<string?>` |  | Gets or sets the callback invoked when the value changes. |
| `Placeholder` | `string?` |  | Gets or sets the placeholder text displayed when the editor is empty. |
| `Disabled` | `bool` |  | Gets or sets whether the editor is disabled. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the editor container. |
| `Id` | `string?` |  | Gets or sets the HTML id attribute for the textarea element. |
| `AriaLabel` | `string?` |  | Gets or sets the ARIA label for the textarea. |
| `AriaDescribedBy` | `string?` |  | Gets or sets the ID of the element that describes the textarea. |
| `AriaInvalid` | `bool?` |  | Gets or sets whether the textarea value is invalid. |

**Basic Usage:**
```razor
<MarkdownEditor @bind-Value="markdownContent" 
 Placeholder="Write your markdown here..." />

@* With preview *@
<MarkdownEditor @bind-Value="markdownContent" 
 ShowPreview="true" />

@code {
 private string markdownContent = "# Hello World";
}
```

---

### MaskedInput

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Text input with real-time pattern masking. Auto-skips literal characters, manages cursor position, supports paste with auto-formatting, and provides common built-in masks via `MaskedInput.Masks`.

**Mask pattern characters:** `0` = digit, `9` = digit or space, `A` = uppercase letter, `a` = letter or space, `*` = alphanumeric. All other characters are treated as literals.

**Components & Parameters:**

#### `MaskedInput`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Value` | `string?` |  | The unmasked input value. Use `@bind-Value` for two-way binding. |
| `ValueChanged` | `EventCallback<string?>` |  | Callback invoked when the value changes. |
| `Mask` | `string` | `""` | The mask pattern (e.g., `"(000) 000-0000"`). |
| `MaskChar` | `char` | `'_'` | Placeholder character for unfilled mask positions. |
| `ShowMask` | `bool` | `true` | Show the mask template when input is empty. |
| `Placeholder` | `string?` |  | HTML placeholder text. |
| `Disabled` | `bool` | `false` | Disable the input. |
| `Required` | `bool` | `false` | Mark as required. |
| `Name` | `string?` |  | Input name for form submission. |
| `Readonly` | `bool` | `false` | Make input read-only. |
| `InputMode` | `string?` | `"text"` | Mobile keyboard hint (e.g., `"numeric"`, `"tel"`). |
| `Class` | `string?` |  | Additional CSS classes. |
| `Id` | `string?` |  | HTML id attribute. |
| `UpdateOn` | `InputUpdateMode` | `Change` | `Input` (every keystroke) or `Change` (on blur). |

**Built-in mask constants:**
- `MaskedInput.Masks.Phone` — `"(000) 000-0000"`
- `MaskedInput.Masks.SSN` — `"000-00-0000"`
- `MaskedInput.Masks.CreditCard` — `"0000 0000 0000 0000"`
- `MaskedInput.Masks.ZipCode` — `"00000"`
- `MaskedInput.Masks.Date` — `"00/00/0000"`


**Basic Usage:**
```razor
<MaskedInput @bind-Value="phone" Mask="(000) 000-0000" Placeholder="Enter phone number" />
<MaskedInput @bind-Value="ssn" Mask="@MaskedInput.Masks.SSN" ShowMask="true" />
<MaskedInput @bind-Value="card" Mask="@MaskedInput.Masks.CreditCard" />
```

---

### Menubar

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Desktop application-style horizontal menu bar with dropdown menus. Top-level navigation with nested submenus.

**Components & Parameters:**

#### `Menubar`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render within the menubar. Typically includes MenubarMenu components. |
| `Class` | `string?` |  | Additional CSS classes to apply to the menubar. |
| `ActiveIndex` | `int?` |  | Controls which menu is active/open (controlled mode). When null, the menubar manages its own state. |
| `ActiveIndexChanged` | `EventCallback<int>` |  | Event callback invoked when the active index changes. Use with @bind-ActiveIndex for two-way binding. |
| `DefaultActiveIndex` | `int` | `-1` | Default active index when in uncontrolled mode. |
| `OnActiveIndexChange` | `EventCallback<int>` |  | Event callback invoked when the active menu changes. |
| `Loop` | `bool` | `true` | Whether keyboard loop navigation is enabled. Default is true. |

#### `MenubarCheckboxItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display inside the checkbox item. |
| `Class` | `string?` |  | Additional CSS classes to apply to the checkbox item. |
| `Disabled` | `bool` | `false` | Whether the checkbox item is disabled. |
| `Checked` | `bool` | `false` | Whether the checkbox is checked. |
| `CheckedChanged` | `EventCallback<bool>` |  | Event callback invoked when the checked state changes (for two-way binding). |
| `OnCheckedChange` | `EventCallback<bool>` |  | Event callback invoked when the checkbox state changes. |
| `CloseOnSelect` | `bool` | `false` | Whether to close the menu when this item is selected. Default is false for checkbox items. |

#### `MenubarContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render inside the menu. |
| `Class` | `string?` |  | Additional CSS classes to apply to the content container. |
| `CloseOnEscape` | `bool` | `true` | Whether pressing Escape should close the menu. |
| `CloseOnClickOutside` | `bool` | `true` | Whether clicking outside should close the menu. |
| `Side` | `PopoverSide` | `PopoverSide.Bottom` | Preferred side for positioning. |
| `Align` | `PopoverAlign` | `PopoverAlign.Start` | Alignment relative to trigger. |
| `Offset` | `int` | `4` | Offset distance from the trigger in pixels. |
| `Loop` | `bool` | `true` | Whether to enable keyboard loop navigation. |
| `ZIndex` | `int` | `50` | Z-index for the menu content. |

#### `MenubarGroup`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the group. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the group. |

#### `MenubarItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display inside the menu item. |
| `Class` | `string?` |  | Additional CSS classes to apply to the menu item. |
| `Disabled` | `bool` | `false` | Whether the menu item is disabled. |
| `OnClick` | `EventCallback<MouseEventArgs>` |  | Custom click handler. |
| `CloseOnSelect` | `bool` | `true` | Whether to close the menu when this item is selected. |
| `Inset` | `bool` | `false` | Whether this menu item represents an inset item (has additional left padding). |

#### `MenubarLabel`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the label. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the label. |
| `Inset` | `bool` | `false` | Whether to show the label with inset padding to align with items that have icons. |

#### `MenubarMenu`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content, typically MenubarTrigger and MenubarContent. |

#### `MenubarRadioGroup`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render inside the radio group. Typically contains MenubarRadioItem components. |
| `Class` | `string?` |  | Additional CSS classes to apply to the radio group. |
| `Value` | `TValue?` |  | The currently selected value. |
| `ValueChanged` | `EventCallback<TValue?>` |  | Event callback invoked when the selected value changes (for two-way binding). |
| `OnValueChange` | `EventCallback<TValue?>` |  | Event callback invoked when the selection changes. |

#### `MenubarRadioItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display inside the radio item. |
| `Class` | `string?` |  | Additional CSS classes to apply to the radio item. |
| `Disabled` | `bool` | `false` | Whether the radio item is disabled. |
| `Value` | `TValue?` |  | The value associated with this radio item. |
| `CloseOnSelect` | `bool` | `true` | Whether to close the menu when this item is selected. Default is true for radio items. |

#### `MenubarSeparator`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Additional CSS classes to apply to the separator. |

#### `MenubarShortcut`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Additional CSS classes to apply to the shortcut. |
| `ChildContent` | `RenderFragment?` |  | The content to be rendered inside the shortcut (e.g., "⌘K", "Ctrl+S"). |

#### `MenubarSub`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render inside the submenu. Typically contains MenubarSubTrigger and MenubarSubContent. |
| `Open` | `bool?` |  | Controls whether the submenu is open (controlled mode). |
| `OpenChanged` | `EventCallback<bool>` |  | Event callback invoked when the open state changes (for two-way binding). |
| `OnOpenChange` | `EventCallback<bool>` |  | Event callback invoked when the submenu open state changes. |

#### `MenubarSubContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render inside the submenu. |
| `Class` | `string?` |  | Additional CSS classes to apply to the content container. |
| `CloseOnEscape` | `bool` | `true` | Whether pressing Escape should close the submenu. |
| `Offset` | `int` | `-4` | Offset distance from the trigger in pixels. |
| `ZIndex` | `int` | `50` | Z-index for the submenu content. |

#### `MenubarSubTrigger`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display inside the trigger. |
| `Class` | `string?` |  | Additional CSS classes to apply to the trigger. |
| `Disabled` | `bool` | `false` | Whether the trigger is disabled. |
| `Inset` | `bool` | `false` | Whether this trigger is an inset item (has additional left padding). |

#### `MenubarTrigger`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display inside the trigger button. |
| `Class` | `string?` |  | Additional CSS classes to apply to the trigger. |
| `Disabled` | `bool` | `false` | Whether the trigger is disabled. |

**Basic Usage:**
```razor
<Menubar>
 <MenubarMenu>
  <MenubarTrigger>File</MenubarTrigger>
  <MenubarContent>
<MenubarItem>New File</MenubarItem>
<MenubarItem>Open</MenubarItem>
<MenubarSeparator />
<MenubarItem>Save</MenubarItem>
  </MenubarContent>
 </MenubarMenu>
 
 <MenubarMenu>
  <MenubarTrigger>Edit</MenubarTrigger>
  <MenubarContent>
<MenubarItem>Cut</MenubarItem>
<MenubarItem>Copy</MenubarItem>
<MenubarItem>Paste</MenubarItem>
  </MenubarContent>
 </MenubarMenu>
</Menubar>
```

---

### Motion

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Declarative animation system powered by Motion.dev with 20+ presets including fade, scale, slide, shake, bounce, pulse, spring physics, scroll-triggered animations, and staggered list/grid animations.

**Components & Parameters:**

#### `BounceOnce`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Height` | `string` | `"-30px"` | Bounce height (pixels or percentage). Default: "-30px" |
| `Duration` | `double` | `0.6` | Duration in seconds. Default: 0.6 |

#### `ExpandOnScroll`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `From` | `double` | `0.8` | Starting scale (0-1). Default: 0.8 |
| `To` | `double` | `1` | Ending scale (0-1+). Default: 1 |
| `Duration` | `double` | `0.6` | Duration in seconds. Default: 0.6 |

#### `FadeIn`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `From` | `double` | `0` | Starting opacity (0-1). Default: 0 |
| `To` | `double` | `1` | Ending opacity (0-1). Default: 1 |
| `Duration` | `double` | `0.3` | Duration in seconds. Default: 0.3 |

#### `FadeInOnScroll`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `From` | `double` | `0` | Starting opacity (0-1). Default: 0 |
| `To` | `double` | `1` | Ending opacity (0-1). Default: 1 |
| `Duration` | `double` | `0.6` | Duration in seconds. Default: 0.6 |

#### `FadeOut`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `From` | `double` | `1` | Starting opacity (0-1). Default: 1 |
| `To` | `double` | `0` | Ending opacity (0-1). Default: 0 |
| `Duration` | `double` | `0.2` | Duration in seconds. Default: 0.2 |

#### `GridItemEnter`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Duration` | `double` | `0.4` | Duration in seconds. Default: 0.4 |

#### `ListItemEnter`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Duration` | `double` | `0.3` | Duration in seconds. Default: 0.3 |

#### `ListItemExit`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Duration` | `double` | `0.2` | Duration in seconds. Default: 0.2 |

#### `Motion`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render and animate. |
| `Presets` | `RenderFragment?` |  | Preset animations to apply (FadeIn, ScaleIn, Spring, etc.). |
| `Trigger` | `MotionTrigger` | `MotionTrigger.OnAppear` | When the animation should trigger. |
| `Class` | `string?` |  | Additional CSS classes to apply. |
| `Style` | `string?` |  | Additional inline styles to apply. |
| `InViewOptions` | `InViewOptions?` |  | Options for IntersectionObserver when Trigger is OnInView. |
| `StaggerChildren` | `double?` |  | Stagger delay for child animations in seconds. |
| `RespectReducedMotion` | `bool` | `true` | Whether to respect user's reduced motion preference. Default: true |
| `Keyframes` | `List<MotionKeyframe>?` |  | Custom keyframes to animate (alternative to using presets). |
| `Options` | `MotionOptions?` |  | Animation options (duration, delay, easing, etc.). |
| `Spring` | `SpringOptions?` |  | Spring physics options (overrides standard easing). |

#### `Presets`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Preset components to apply (FadeIn, ScaleIn, Spring, etc.). |

#### `Pulse`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Scale` | `double` | `1.05` | Scale amplitude. Default: 1.05 |
| `Duration` | `double` | `0.6` | Duration in seconds. Default: 0.6 |
| `Repeat` | `double` | `-1` | Number of pulses. Default: infinite |

#### `ScaleIn`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `From` | `double` | `0.8` | Starting scale (0-1+). Default: 0.8 |
| `To` | `double` | `1` | Ending scale (0-1+). Default: 1 |
| `Duration` | `double` | `0.3` | Duration in seconds. Default: 0.3 |

#### `ScaleOut`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `From` | `double` | `1` | Starting scale (0-1+). Default: 1 |
| `To` | `double` | `0.8` | Ending scale (0-1+). Default: 0.8 |
| `Duration` | `double` | `0.2` | Duration in seconds. Default: 0.2 |

#### `ShakeX`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Intensity` | `int` | `10` | Shake intensity (pixels). Default: 10 |
| `Duration` | `double` | `0.4` | Duration in seconds. Default: 0.4 |

#### `ShakeY`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Intensity` | `int` | `10` | Shake intensity (pixels). Default: 10 |
| `Duration` | `double` | `0.4` | Duration in seconds. Default: 0.4 |

#### `SlideInFromBottom`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `From` | `double` | `100` | Distance to slide from in pixels. Default: 100 |
| `Duration` | `double` | `0.3` | Duration in seconds. Default: 0.3 |

#### `SlideInFromLeft`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `From` | `double` | `-100` | Distance to slide from in pixels (negative value). Default: -100 |
| `Duration` | `double` | `0.3` | Duration in seconds. Default: 0.3 |

#### `SlideInFromRight`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `From` | `double` | `100` | Distance to slide from in pixels. Default: 100 |
| `Duration` | `double` | `0.3` | Duration in seconds. Default: 0.3 |

#### `SlideInFromTop`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `From` | `double` | `-100` | Distance to slide from in pixels (negative value). Default: -100 |
| `Duration` | `double` | `0.3` | Duration in seconds. Default: 0.3 |

#### `SlideInOnScroll`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `From` | `double` | `50` | Starting Y position in pixels. Default: 50 |
| `Duration` | `double` | `0.6` | Duration in seconds. Default: 0.6 |

#### `Spring`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Mass` | `double` | `1.0` | Mass of the spring. Higher = slower. Default: 1.0 |
| `Stiffness` | `double` | `100` | Stiffness of the spring. Higher = snappier. Default: 100 |
| `Damping` | `double` | `10` | Damping ratio. Higher = less oscillation. Default: 10 |
| `Velocity` | `double` | `0` | Initial velocity. Default: 0 |
| `Bounce` | `double?` |  | Bounce amount (0-1). Alternative to stiffness/damping. |

**Basic Usage:**
```razor
@* Fade in animation *@
<Motion Preset="MotionPreset.Fade">
 <div>This content fades in</div>
</Motion>

@* Slide up animation *@
<Motion Preset="MotionPreset.SlideUp" Duration="0.5">
 <Card>Slides up on mount</Card>
</Motion>

@* Stagger children *@
<Motion Preset="MotionPreset.StaggerList">
 <div>Item 1</div>
 <div>Item 2</div>
 <div>Item 3</div>
</Motion>
```

---

### MultiSelect

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Searchable multi-selection with tags and checkboxes. Select multiple options from a dropdown list.

**Components & Parameters:**

#### `MultiSelect`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Values` | `IEnumerable<string>?` |  | Gets or sets the currently selected values. |
| `ValuesChanged` | `EventCallback<IEnumerable<string>?>` |  | Gets or sets the callback that is invoked when the selected values change. |
| `Placeholder` | `string` | `"Select items..."` | Gets or sets the placeholder text shown when no items are selected. |
| `SearchPlaceholder` | `string` | `"Search..."` | Gets or sets the placeholder text shown in the search input. |
| `EmptyMessage` | `string` | `"No results found."` | Gets or sets the message displayed when no items match the search. |
| `SelectAllLabel` | `string` | `"Select All"` | Gets or sets the label for the Select All option. |
| `ShowSelectAll` | `bool` | `true` | Gets or sets whether to show the Select All option. |
| `ClearLabel` | `string` | `"Clear"` | Gets or sets the label for the Clear button. |
| `CloseLabel` | `string` | `"Close"` | Gets or sets the label for the Close button. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the multiselect container. |
| `Disabled` | `bool` |  | Gets or sets whether the multiselect is disabled. |
| `MaxDisplayTags` | `int` | `3` | Gets or sets the maximum number of tags to display before showing "+N more". |
| `PopoverWidth` | `string` | `"w-[300px]"` | Gets or sets the width of the popover content. |
| `ValuesExpression` | `Expression<Func<IEnumerable<string>?>>?` |  | Gets or sets an expression that identifies the bound values. Used for form validation integration. |
| `MatchTriggerWidth` | `bool` | `false` | When true, the dropdown popover matches the width of the trigger button. |
| `AutoClose` | `bool` | `true` | When false, the popover stays open after selecting an item (useful for multi-step selection). |

**Basic Usage:**
```razor
<MultiSelect @bind-Values="selectedItems" 
 Placeholder="Select items...">
 <MultiSelectItem Value="option1">Option 1</MultiSelectItem>
 <MultiSelectItem Value="option2">Option 2</MultiSelectItem>
 <MultiSelectItem Value="option3">Option 3</MultiSelectItem>
</MultiSelect>

@code {
 private HashSet<string> selectedItems = new();
}
```

---

### NativeSelect

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Styled native HTML select dropdown. Enhanced styling for standard select element.

**Components & Parameters:**

#### `NativeSelect`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Value` | `string?` |  | Gets or sets the selected value. |
| `ValueChanged` | `EventCallback<string?>` |  | Gets or sets the callback that is invoked when the value changes. |
| `Id` | `string?` |  | Gets or sets the id attribute for the select element. |
| `Name` | `string?` |  | Gets or sets the name attribute for the select element. |
| `Placeholder` | `string?` |  | Gets or sets the placeholder text when no option is selected. |
| `Disabled` | `bool` |  | Gets or sets whether the select is disabled. |
| `Required` | `bool` |  | Gets or sets whether the select is required. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the select. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the select (options). |

#### `NativeSelectOption`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Value` | `string?` |  |  |
| `Disabled` | `bool` |  |  |
| `ChildContent` | `RenderFragment?` |  |  |

**Basic Usage:**
```razor
<NativeSelect @bind-Value="selectedValue">
 <option value="">Select an option</option>
 <option value="option1">Option 1</option>
 <option value="option2">Option 2</option>
 <option value="option3">Option 3</option>
</NativeSelect>

@code {
 private string selectedValue = "";
}
```

---

### NavigationMenu

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Horizontal navigation with dropdown panels. Main site navigation with mega menu support.

**Components & Parameters:**

#### `NavigationMenu`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render within the navigation menu. |
| `Value` | `string?` |  | Controls which item is active/open. |
| `ValueChanged` | `EventCallback<string>` |  | Event callback invoked when the active item changes. |
| `Orientation` | `NavigationMenuOrientation` | `NavigationMenuOrientation.Horizontal` | The orientation of the navigation menu. |
| `AriaLabel` | `string` | `"Main"` | The accessible label for the navigation. |
| `Class` | `string?` |  | Additional CSS classes to apply. |

#### `NavigationMenuContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render within the content panel. |
| `ForceMount` | `bool` | `true` | When true, the content is always mounted in the DOM (for animations). Default is true for proper animation support. |
| `Class` | `string?` |  | Additional CSS classes to apply. |

#### `NavigationMenuIndicator`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Additional CSS classes to apply. |

#### `NavigationMenuItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Value` | `string` | `string.Empty` | The unique value for this item. |
| `ChildContent` | `RenderFragment?` |  | The child content to render within the item. |

#### `NavigationMenuLink`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Href` | `string` | `"#"` | The href for the link. |
| `Active` | `bool?` |  | Whether the link is currently active. If not set, active state will be auto-detected based on the current URL when AutoActive is true. |
| `AutoActive` | `bool` | `false` | Whether to automatically detect active state based on the current URL. Similar to NavLink behavior. Default is false. |
| `Match` | `NavLinkMatch` | `NavLinkMatch.Prefix` | How to match the URL when AutoActive is true. NavLinkMatch.All requires an exact match, NavLinkMatch.Prefix requires the URL to start with Href. Default is NavLinkMatch.Prefix. |
| `ChildContent` | `RenderFragment?` |  | The child content to render within the link. |
| `OnClick` | `EventCallback` |  | Event callback invoked when the link is clicked. |
| `Class` | `string?` |  | Additional CSS classes to apply. |

#### `NavigationMenuList`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render within the list. |
| `Class` | `string?` |  | Additional CSS classes to apply. |

#### `NavigationMenuTrigger`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render within the trigger. |
| `Class` | `string?` |  | Additional CSS classes to apply. |

#### `NavigationMenuViewport`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render within the viewport. |
| `Class` | `string?` |  | Additional CSS classes to apply. |

**Basic Usage:**
```razor
<NavigationMenu>
 <NavigationMenuList>
  <NavigationMenuItem>
<NavigationMenuTrigger>Products</NavigationMenuTrigger>
<NavigationMenuContent>
 <NavigationMenuLink Href="/products/all">All Products</NavigationMenuLink>
 <NavigationMenuLink Href="/products/new">New Arrivals</NavigationMenuLink>
</NavigationMenuContent>
  </NavigationMenuItem>
  
  <NavigationMenuItem>
<NavigationMenuLink Href="/about">About</NavigationMenuLink>
  </NavigationMenuItem>
 </NavigationMenuList>
</NavigationMenu>
```

---

### NumericInput

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Numeric input with generic type support (`int`, `decimal`, `double`, `float`), min/max/step enforcement, mobile keyboard hints, and EditForm validation integration.

**Components & Parameters:**

#### `NumericInput<TValue>`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Value` | `TValue?` |  | The numeric value. Use `@bind-Value` for two-way binding. |
| `ValueChanged` | `EventCallback<TValue?>` |  | Callback invoked when the value changes. |
| `Placeholder` | `string?` |  | Placeholder text. |
| `Disabled` | `bool` | `false` | Disable the input. |
| `Required` | `bool` | `false` | Mark as required. |
| `Name` | `string?` |  | Input name for form submission. |
| `Readonly` | `bool` | `false` | Make input read-only. |
| `Min` | `string?` |  | Minimum value (e.g., `"0"`, `"-100"`). |
| `Max` | `string?` |  | Maximum value (e.g., `"1000"`). |
| `Step` | `string?` |  | Step increment (e.g., `"0.01"` for currency, `"1"` for integers). |
| `MaxLength` | `int?` |  | Maximum number of characters allowed. |
| `Class` | `string?` |  | Additional CSS classes. |
| `Id` | `string?` |  | HTML id attribute. |
| `UpdateOn` | `InputUpdateMode` | `Change` | `Input` (every keystroke) or `Change` (on blur). |
| `DebounceDelay` | `int` | `0` | Debounce delay in milliseconds (used with `UpdateOn=Input`). |


**Basic Usage:**
```razor
<NumericInput TValue="int" @bind-Value="quantity" Placeholder="Quantity" Min="0" />
<NumericInput TValue="decimal" @bind-Value="price" Min="0" Max="1000" Step="0.01" />
<NumericInput TValue="double" @bind-Value="percentage" Min="0" Max="100" Step="0.1" />

@code {
    private int quantity;
    private decimal price;
    private double percentage;
}
```

---

### Pagination

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Page navigation with Previous/Next/Ellipsis support. Navigate through paginated content.

**Components & Parameters:**

#### `Pagination`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `AriaLabel` | `string` | `"pagination"` | Gets or sets the aria-label for the pagination navigation. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the pagination. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the pagination. |

#### `PaginationContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  |  |
| `ChildContent` | `RenderFragment?` |  |  |

#### `PaginationEllipsis`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  |  |

#### `PaginationItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  |  |
| `ChildContent` | `RenderFragment?` |  |  |

#### `PaginationLink`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Href` | `string?` |  |  |
| `IsActive` | `bool` |  |  |
| `Class` | `string?` |  |  |
| `ChildContent` | `RenderFragment?` |  |  |

#### `PaginationNext`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Href` | `string?` |  |  |
| `Class` | `string?` |  |  |

#### `PaginationPrevious`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Href` | `string?` |  |  |
| `Class` | `string?` |  |  |

**Basic Usage:**
```razor
<Pagination CurrentPage="currentPage" 
TotalPages="10" 
OnPageChanged="HandlePageChange">
 <PaginationContent>
  <PaginationPrevious />
  <PaginationItem PageNumber="1" />
  <PaginationEllipsis />
  <PaginationItem PageNumber="currentPage" />
  <PaginationEllipsis />
  <PaginationItem PageNumber="10" />
  <PaginationNext />
 </PaginationContent>
</Pagination>

@code {
 private int currentPage = 1;
 
 private void HandlePageChange(int page)
 {
  currentPage = page;
 }
}
```

---

### PageTransition

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Wraps page content with smooth fade (and optional slide-from-bottom) animations on navigation. Respects SSR/prerender — no animations during initial server-side render or hydration. Requires `RenderStateProvider` as an ancestor to detect interactive state.

**Components & Parameters:**

#### `PageTransition`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The page content to wrap with transitions. |
| `DisableAnimation` | `bool` | `false` | Disable all transition animations. |
| `Duration` | `double` | `0.25` | Transition duration in seconds. |
| `FromOpacity` | `double` | `0` | Starting opacity for the fade-in animation. |
| `ToOpacity` | `double` | `1` | Ending opacity for the fade-in animation. |
| `EnableSlide` | `bool` | `false` | Add a slide-from-bottom animation in addition to fade. |
| `SlideDistance` | `int` | `10` | Slide distance in pixels when `EnableSlide` is true. |
| `Class` | `string?` |  | Additional CSS classes for the transition container. |


**Basic Usage:**
```razor
@* In MainLayout.razor — wrap @Body with RenderStateProvider + PageTransition *@
<RenderStateProvider>
    <PageTransition>
        @Body
    </PageTransition>
</RenderStateProvider>

@* With slide animation *@
<RenderStateProvider>
    <PageTransition EnableSlide="true" Duration="0.3" SlideDistance="15">
        @Body
    </PageTransition>
</RenderStateProvider>
```

---

### Popover

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Floating content containers triggered by user interaction. Displays rich content in an overlay.

**Components & Parameters:**

#### `Popover`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render within the popover. Should include PopoverTrigger and PopoverContent. |
| `Open` | `bool?` |  | Controls whether the popover is open (controlled mode). When null, the popover manages its own state (uncontrolled mode). |
| `OpenChanged` | `EventCallback<bool>` |  | Event callback invoked when the open state changes. Use with @bind-Open for two-way binding. |
| `DefaultOpen` | `bool` | `false` | Default open state when in uncontrolled mode. |
| `OnOpenChange` | `EventCallback<bool>` |  | Event callback invoked when the popover open state changes. |
| `Modal` | `bool` | `true` | Whether the popover can be dismissed by clicking outside or pressing Escape. Default is true. |

#### `PopoverContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  |  |
| `CloseOnEscape` | `bool` | `true` |  |
| `CloseOnClickOutside` | `bool` | `true` |  |
| `Side` | `PopoverSide` | `PopoverSide.Bottom` |  |
| `Align` | `PopoverAlign` | `PopoverAlign.Center` |  |
| `Offset` | `int` | `4` |  |
| `OnEscapeKeyDown` | `EventCallback<KeyboardEventArgs>` |  |  |
| `OnClickOutside` | `EventCallback` |  |  |
| `Class` | `string?` |  |  |

#### `PopoverTrigger`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  |  |
| `AsChild` | `bool` | `false` | When true, the trigger does not render its own button element. Instead, it passes trigger behavior via TriggerContext to child components. Use this when you want a custom component (like Button) to act as the trigger. |
| `OnClick` | `EventCallback<MouseEventArgs>` |  |  |
| `CustomClickHandling` | `bool` | `false` |  |

**Basic Usage:**
```razor
<Popover>
 <PopoverTrigger AsChild>
  <Button Variant="ButtonVariant.Outline">Open Popover</Button>
 </PopoverTrigger>
 <PopoverContent>
  <div class="space-y-2">
<h4 class="font-medium">Dimensions</h4>
<p class="text-sm">Set the dimensions for the layer.</p>
  </div>
 </PopoverContent>
</Popover>
```

---

### Progress

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Progress bars with animations and indeterminate state. Visual indicator for task completion.

**Components & Parameters:**

#### `Progress`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Value` | `double` |  | Gets or sets the current progress value. |
| `Max` | `double` | `100` | Gets or sets the maximum value for the progress bar. Default value is 100. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the progress bar. |

**Basic Usage:**
```razor
@* Determinate progress *@
<Progress Value="progressValue" />

@* Indeterminate progress *@
<Progress Indeterminate="true" />

@* With custom color *@
<Progress Value="75" Class="[&>div]:bg-green-500" />

@code {
 private int progressValue = 60;
}
```

---

### RadioGroup

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Radio button groups with keyboard navigation. Mutually exclusive selection from multiple options.

**Components & Parameters:**

#### `RadioGroup`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Value` | `TValue` |  | Gets or sets the currently selected value. This property supports two-way binding using the @bind-Value directive. Changes to this property trigger the ValueChanged event callback. |
| `ValueChanged` | `EventCallback<TValue>` |  | Gets or sets the callback invoked when the selected value changes. This event callback enables two-way binding with @bind-Value. It is invoked whenever a radio button is selected. |
| `Disabled` | `bool` |  | Gets or sets whether the entire radio group is disabled. When disabled, all radio items in the group cannot be selected. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the radio group container. |
| `AriaLabel` | `string?` |  | Gets or sets the ARIA label for the radio group. Provides accessible text for screen readers to describe the purpose of the radio group. |
| `Name` | `string?` |  | Gets or sets the name for all radio items in this group. This name is shared by all radio items in the group, making them mutually exclusive. Critical for form submission - the selected value will be submitted with this name. |
| `Required` | `bool` |  | Gets or sets whether a selection is required in this radio group. When true, the user must select one of the radio items for form submission. Works with form validation. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the radio group. Should contain RadioGroupItem components. |
| `ValueExpression` | `Expression<Func<TValue>>?` |  | Gets or sets an expression that identifies the bound value. Used for form validation integration. When provided, the radio group registers with the EditContext and participates in form validation. |

#### `RadioGroupItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Disabled` | `bool` |  | Gets or sets whether this individual radio item is disabled. When disabled, the item cannot be selected and appears with reduced opacity. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the radio item. |
| `AriaLabel` | `string?` |  | Gets or sets the ARIA label for the radio item. Provides accessible text for screen readers when the radio item doesn't have an associated label element. |
| `Id` | `string?` |  | Gets or sets the ID attribute for the radio item element. Used for associating the radio item with label elements via htmlFor attribute. |

**Basic Usage:**
```razor
<RadioGroup @bind-Value="selectedOption">
 <div class="flex items-center space-x-2">
  <RadioGroupItem Value="option1" Id="option1" />
  <Label For="option1">Option 1</Label>
 </div>
 <div class="flex items-center space-x-2">
  <RadioGroupItem Value="option2" Id="option2" />
  <Label For="option2">Option 2</Label>
 </div>
 <div class="flex items-center space-x-2">
  <RadioGroupItem Value="option3" Id="option3" />
  <Label For="option3">Option 3</Label>
 </div>
</RadioGroup>

@code {
 private string selectedOption = "option1";
}
```

---

### RangeSlider

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Dual-handle range slider for selecting a minimum and maximum value. Supports keyboard navigation (arrow keys, Page Up/Down, Home/End), touch, optional tick marks, value tooltips on handles, and EditForm validation.

**Components & Parameters:**

#### `RangeSlider`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `MinValue` | `double` | `0` | The lower bound of the selected range. Use `@bind-MinValue`. |
| `MinValueChanged` | `EventCallback<double>` |  | Callback invoked when the minimum value changes. |
| `MaxValue` | `double` | `100` | The upper bound of the selected range. Use `@bind-MaxValue`. |
| `MaxValueChanged` | `EventCallback<double>` |  | Callback invoked when the maximum value changes. |
| `Min` | `double` | `0` | Minimum allowed value. |
| `Max` | `double` | `100` | Maximum allowed value. |
| `Step` | `double` | `1` | Step increment. |
| `ShowLabels` | `bool` | `true` | Show min/max value labels. |
| `ShowTooltips` | `bool` | `true` | Show value tooltips on drag handles. |
| `Disabled` | `bool` | `false` | Disable the slider. |
| `Class` | `string?` |  | Additional CSS classes. |


**Basic Usage:**
```razor
<RangeSlider @bind-MinValue="minPrice" @bind-MaxValue="maxPrice"
             Min="0" Max="1000" Step="10" ShowTooltips="true" />

@code {
    private double minPrice = 0;
    private double maxPrice = 500;
}
```

---

### Rating

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Star/heart/circle rating input with optional half-star support, read-only mode, multiple sizes, and EditForm validation integration.

**Components & Parameters:**

#### `Rating`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Value` | `double` |  | The current rating value. Use `@bind-Value`. |
| `ValueChanged` | `EventCallback<double>` |  | Callback invoked when the value changes. |
| `MaxRating` | `int` | `5` | Maximum rating value (number of icons). |
| `AllowHalf` | `bool` | `false` | Enable half-star selection. |
| `AllowClear` | `bool` | `true` | Allow clicking the same value to clear the rating. |
| `Disabled` | `bool` | `false` | Disable the rating. |
| `ReadOnly` | `bool` | `false` | Show rating without interaction. |
| `Size` | `RatingSize` | `RatingSize.Medium` | Icon size: `Small`, `Medium`, `Large`. |
| `IconType` | `RatingIconType` | `RatingIconType.Star` | Icon style: `Star`, `Heart`, `Circle`. |
| `ShowValidationError` | `bool` | `false` | Show validation error from EditContext. |
| `Class` | `string?` |  | Additional CSS classes. |
| `Id` | `string?` |  | HTML id attribute. |
| `Name` | `string?` |  | Input name for form submission. |


**Basic Usage:**
```razor
<Rating @bind-Value="rating" MaxRating="5" AllowHalf="true" />
<Rating @bind-Value="sentiment" IconType="RatingIconType.Heart" ReadOnly="false" />

@code {
    private double rating;
    private double sentiment;
}
```

---

### Resizable

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Split layouts with draggable handles. Create resizable split panes.

**Components & Parameters:**

#### `ResizableHandle`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Index` | `int` |  | The index of the handle (zero-based, between panels). |
| `WithHandle` | `bool` | `false` | Whether to show a visual grip handle. Default is false. |
| `Class` | `string?` |  | Additional CSS classes to apply to the handle. |

#### `ResizablePanel`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render within the panel. |
| `DefaultSize` | `double?` |  | The default size of the panel as a percentage. |
| `MinSize` | `double?` |  | The minimum size of the panel as a percentage. |
| `MaxSize` | `double?` |  | The maximum size of the panel as a percentage. |
| `Collapsible` | `bool` | `false` | Whether the panel is collapsible. |
| `Class` | `string?` |  | Additional CSS classes to apply to the panel. |

#### `ResizablePanelGroup`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render within the panel group. Should contain ResizablePanel and ResizableHandle components. |
| `Direction` | `ResizableDirection` | `ResizableDirection.Horizontal` | The direction of the panel layout. Default is Horizontal. |
| `DefaultSizes` | `double[]?` |  | The initial sizes of the panels as percentages (must sum to 100). If not provided, panels will be sized equally. |
| `OnLayoutChange` | `EventCallback<double[]>` |  | Event callback invoked when panel sizes change. |
| `Class` | `string?` |  | Additional CSS classes to apply to the container. |

**Basic Usage:**
```razor
<ResizablePanelGroup Direction="ResizableDirection.Horizontal">
 <ResizablePanel DefaultSize="50">
  <div class="p-4">Left Panel</div>
 </ResizablePanel>
 <ResizableHandle />
 <ResizablePanel DefaultSize="50">
  <div class="p-4">Right Panel</div>
 </ResizablePanel>
</ResizablePanelGroup>
```

---

### RichTextEditor

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
WYSIWYG editor with formatting toolbar and HTML output. Full-featured rich text editing.

**Components & Parameters:**

#### `RichTextEditor`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Value` | `string?` |  | Gets or sets the HTML content value. |
| `ValueChanged` | `EventCallback<string?>` |  | Gets or sets the callback invoked when the value changes. |
| `Placeholder` | `string?` |  | Gets or sets the placeholder text displayed when the editor is empty. |
| `Disabled` | `bool` |  | Gets or sets whether the editor is disabled. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the editor container. |
| `Id` | `string?` |  | Gets or sets the HTML id attribute for the contenteditable element. |
| `AriaLabel` | `string?` |  | Gets or sets the ARIA label for the editor. |
| `AriaDescribedBy` | `string?` |  | Gets or sets the ID of the element that describes the editor. |
| `AriaInvalid` | `bool?` |  | Gets or sets whether the editor value is invalid. |
| `MinHeight` | `string` | `"150px"` | Gets or sets the minimum height of the editor content area. |
| `MaxHeight` | `string?` |  | Gets or sets the maximum height of the editor content area. When content exceeds this height, a scrollbar appears. |
| `Height` | `string?` |  | Gets or sets a fixed height for the editor content area. When set, the editor will not auto-expand and will show scrollbar when content overflows. Takes precedence over MinHeight/MaxHeight when set. |

**Basic Usage:**
```razor
<RichTextEditor @bind-Value="htmlContent" 
 Placeholder="Start typing..." />

@* With custom toolbar *@
<RichTextEditor @bind-Value="htmlContent">
 <ToolbarContent>
  <ToolbarButton Command="bold">Bold</ToolbarButton>
  <ToolbarButton Command="italic">Italic</ToolbarButton>
 </ToolbarContent>
</RichTextEditor>

@code {
 private string htmlContent = "<p>Hello World</p>";
}
```

---

### RenderStateProvider

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Provides application render lifecycle state to child components via a cascading `AppRenderContext`. Detects when the app becomes interactive (post-hydration), the hydration phase, and whether navigation is enhanced (client-side SPA). Required ancestor for `PageTransition`. Wrap your layout body or the root app component with this provider.

**Components & Parameters:**

#### `RenderStateProvider`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to wrap with the render state context. |

**Cascaded `AppRenderContext` properties:**

| Property | Type | Description |
|----------|------|-------------|
| `IsInteractive` | `bool` | `true` after hydration completes (JS/DOM is safe to use). |
| `IsHydrating` | `bool` | `true` during the first interactive frame after SSR. |
| `IsEnhancedNavigation` | `bool` | `true` after the first client-side navigation occurs. |


**Basic Usage:**
```razor
@* In MainLayout.razor *@
<RenderStateProvider>
    <PageTransition>
        @Body
    </PageTransition>
</RenderStateProvider>

@* Consuming AppRenderContext in a child component *@
@code {
    [CascadingParameter] public AppRenderContext? RenderContext { get; set; }

    private bool CanAnimate => RenderContext?.IsInteractive == true
                            && RenderContext?.IsHydrating == false;
}
```

---

### ResponsiveNav

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Responsive navigation system that renders desktop navigation inline and slides mobile navigation in from a side sheet. Three cooperating sub-components share state via a cascaded context. The mobile sheet auto-closes on navigation.

**Components & Parameters:**

#### `ResponsiveNavProvider`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Content including trigger, desktop nav, and mobile content. |

#### `ResponsiveNavTrigger`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Custom trigger content. Defaults to a hamburger (☰) icon. |
| `Class` | `string?` |  | Additional CSS classes. |
| `OnClick` | `EventCallback<MouseEventArgs>` |  | Optional additional click handler. |

#### `ResponsiveNavContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Navigation links rendered inside the mobile sheet. |
| `Header` | `RenderFragment?` |  | Optional header above the navigation links. |
| `Footer` | `RenderFragment?` |  | Optional footer below the navigation links. |
| `ShowClose` | `bool` | `true` | Show the close button in the mobile sheet. |
| `ContentClass` | `string?` |  | Additional CSS classes for the sheet content area. |


**Basic Usage:**
```razor
<ResponsiveNavProvider>
    @* Desktop nav — hidden on mobile *@
    <nav class="hidden md:flex gap-4">
        <a href="/">Home</a>
        <a href="/about">About</a>
    </nav>

    @* Mobile hamburger trigger *@
    <ResponsiveNavTrigger />

    @* Mobile slide-in sheet *@
    <ResponsiveNavContent>
        <nav class="flex flex-col gap-2">
            <a href="/">Home</a>
            <a href="/about">About</a>
        </nav>
    </ResponsiveNavContent>
</ResponsiveNavProvider>
```

---

### ScrollArea

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Custom scrollbars for styled scroll regions. Enhanced scrolling with custom styled scrollbars.

**Components & Parameters:**

#### `ScrollArea`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render within the scrollable area. |
| `Type` | `ScrollAreaType` | `ScrollAreaType.Auto` | The type of scrollbar to show. Default is Auto (scrollbars visible when content overflows). |
| `ScrollHideDelay` | `int` | `600` | Controls the visibility delay of scrollbars in milliseconds. Only applies when Type is Scroll or Hover. Default is 600ms. |
| `ShowVerticalScrollbar` | `bool` | `true` | Whether to show the vertical scrollbar. Default is true. |
| `ShowHorizontalScrollbar` | `bool` | `false` | Whether to show the horizontal scrollbar. Default is false. |
| `EnableScrollShadows` | `bool` | `false` | Whether to enable scroll shadows that indicate more content is available. Default is false. |
| `Class` | `string?` |  | Additional CSS classes to apply to the root element. |

#### `ScrollBar`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Orientation` | `Orientation` | `Orientation.Vertical` | The orientation of the scrollbar. Default is Vertical. |
| `Class` | `string?` |  | Additional CSS classes to apply to the scrollbar. |

**Basic Usage:**
```razor
<ScrollArea Class="h-72 w-48">
 <div class="p-4">
  <ul class="space-y-4">
@for (int i = 1; i <= 50; i++)
{
 <li>Item @i</li>
}
  </ul>
 </div>
</ScrollArea>

@* Horizontal scroll *@
<ScrollArea Orientation="ScrollOrientation.Horizontal">
 <ul class="flex gap-4 p-4">
  @for (int i = 1; i <= 20; i++)
  {
<li class="w-48">
 <Card>Item @i</Card>
</li>
  }
 </ul>
</ScrollArea>
```

---

### Select

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Dropdown select with search and keyboard navigation. Enhanced select component with filtering.

**Components & Parameters:**

#### `Select`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Value` | `TValue?` |  | Gets or sets the currently selected value. |
| `ValueChanged` | `EventCallback<TValue?>` |  | Gets or sets the callback invoked when the selected value changes. |
| `DisplayTextSelector` | `Func<TValue?, string?>?` |  | Custom function that converts the selected value to a display string shown in the trigger. Use when the default `ToString()` output isn't suitable. |
| `Disabled` | `bool` |  | Gets or sets whether the select is disabled. |
| `Open` | `bool?` |  | Gets or sets whether the dropdown is open (controlled mode). |
| `OpenChanged` | `EventCallback<bool>` |  | Gets or sets the callback invoked when the open state changes. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the select container. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the select component. Should contain SelectTrigger and SelectContent components. |

#### `SelectContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the content container. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the dropdown. |

#### `SelectGroup`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the group. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the group. |

#### `SelectItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Text` | `string?` |  | Gets or sets the display text for this item. If not provided, will use ChildContent text or Value.ToString(). |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the item. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered as the item's display text. |
| `Disabled` | `bool` |  | Gets or sets whether this item is disabled. |

#### `SelectLabel`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the label. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the label. |

#### `SelectTrigger`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the trigger button. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the trigger button. |

#### `SelectValue`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Placeholder` | `string?` |  | Gets or sets the placeholder text to display when no value is selected. |

**Basic Usage:**
```razor
<Select @bind-Value="selectedValue" Placeholder="Select an option">
 <SelectTrigger>
  <SelectValue />
 </SelectTrigger>
 <SelectContent>
  <SelectItem Value="option1">Option 1</SelectItem>
  <SelectItem Value="option2">Option 2</SelectItem>
  <SelectItem Value="option3">Option 3</SelectItem>
 </SelectContent>
</Select>

@code {
 private string? selectedValue;
}
```

---

### Separator

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Visual dividers for separating content. Horizontal or vertical line separator.

**Components & Parameters:**

#### `Separator`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Orientation` | `SeparatorOrientation` | `SeparatorOrientation.Horizontal` | Gets or sets the orientation of the separator. Determines whether the separator is displayed horizontally or vertically. Default value is . |
| `Decorative` | `bool` | `true` | Gets or sets whether the separator is purely decorative. When true (default), the separator is treated as decorative (role="none") and hidden from assistive technologies. When false, the separator is semantic (role="separator") and will be announced to screen readers, with the orientation specified via aria-orientation. Set to false when the separator provides meaningful structural information about content hierarchy. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the separator. Custom classes are appended after the component's base classes, allowing for style overrides and extensions. |

**Basic Usage:**
```razor
@* Horizontal separator *@
<div>Content above</div>
<Separator />
<div>Content below</div>

@* Vertical separator *@
<div class="flex gap-4 items-center">
 <span>Left</span>
 <Separator Orientation="SeparatorOrientation.Vertical" Class="h-4" />
 <span>Right</span>
</div>
```

---

### Sheet

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Slide-out panels from any edge (top, right, bottom, left). Drawer component for mobile and desktop.

**Components & Parameters:**

#### `Sheet`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render within the sheet. |
| `Open` | `bool?` |  | Controls whether the sheet is open (controlled mode). When null, the sheet manages its own state (uncontrolled mode). |
| `OpenChanged` | `EventCallback<bool>` |  | Event callback invoked when the open state changes. Use with @bind-Open for two-way binding. |
| `DefaultOpen` | `bool` | `false` | Default open state when in uncontrolled mode. |
| `OnOpenChange` | `EventCallback<bool>` |  | Event callback invoked when the sheet open state changes. |
| `Side` | `SheetSide` | `SheetSide.Right` | The side from which the sheet slides in. Default is Right. |
| `Modal` | `bool` | `true` | Whether the sheet can be dismissed by clicking the overlay or pressing Escape. Default is true. |

#### `SheetClose`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display inside the close button. |
| `AsChild` | `bool` | `false` | When true, the close does not render its own button element. Instead, it passes trigger behavior via TriggerContext to child components. Use this when you want a custom component (like Button) to act as the close button. |
| `OnClick` | `EventCallback<MouseEventArgs>` |  | Custom click handler. Called after the sheet is closed. |
| `PreventClose` | `bool` | `false` | Whether to prevent the default close behavior. When true, only the OnClick handler is invoked. Default is false (sheet closes on click). |

#### `SheetContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render inside the sheet. |
| `Class` | `string?` |  | Additional CSS classes to apply to the sheet content. |
| `Side` | `SheetSide?` |  | The side from which the sheet slides in. When null, uses the side from the parent Sheet component. |
| `ShowClose` | `bool` | `true` | Whether to show the close button (X icon). Default is true. |
| `CloseOnEscape` | `bool` | `true` | Whether pressing Escape should close the sheet. Default is true. |
| `TrapFocus` | `bool` | `true` | Whether to trap focus within the sheet. Default is true for modal sheets. |
| `LockScroll` | `bool` | `true` | Whether to lock body scroll when sheet is open. Default is true for modal sheets. |
| `OnEscapeKeyDown` | `EventCallback<KeyboardEventArgs>` |  | Event callback invoked when Escape key is pressed. |

#### `SheetDescription`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The description text or content. |
| `Class` | `string?` |  | Additional CSS classes to apply to the description. |

#### `SheetFooter`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display in the sheet footer (typically action buttons). |
| `Class` | `string?` |  | Additional CSS classes to apply to the footer container. |

#### `SheetHeader`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display in the sheet header (typically SheetTitle and SheetDescription). |
| `Class` | `string?` |  | Additional CSS classes to apply to the header container. |

#### `SheetTitle`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The title text or content. |
| `Class` | `string?` |  | Additional CSS classes to apply to the title. |

#### `SheetTrigger`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display inside the trigger button. |
| `AsChild` | `bool` | `false` | When true, the trigger does not render its own button element. Instead, it passes trigger behavior via TriggerContext to child components. Use this when you want a custom component (like Button) to act as the trigger. |

**Basic Usage:**
```razor
<Sheet>
 <SheetTrigger AsChild>
  <Button>Open Sheet</Button>
 </SheetTrigger>
 <SheetContent>
  <SheetHeader>
<SheetTitle>Sheet Title</SheetTitle>
<SheetDescription>Sheet description goes here.</SheetDescription>
  </SheetHeader>
  <div class="py-4">
<p>Sheet content</p>
  </div>
  <SheetFooter>
<Button>Save</Button>
  </SheetFooter>
 </SheetContent>
</Sheet>

@* From different sides *@
<Sheet Side="SheetSide.Left">...</Sheet>
<Sheet Side="SheetSide.Top">...</Sheet>
```

---

### Sidebar

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Responsive sidebar with collapsible icon mode, multiple variants (default, floating, inset), and mobile sheet integration.

**Components & Parameters:**

#### `Sidebar`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render inside the sidebar. |
| `Class` | `string?` |  | Additional CSS classes to apply to the sidebar. |
| `Collapsible` | `bool` | `true` | Collapsible behavior: icon-only when collapsed, full width when expanded. Default is true. |
| `AutoDetectActive` | `bool` | `false` | Whether menu items should automatically detect their active state based on current URL. When enabled, all SidebarMenuButton and SidebarMenuSubButton components will automatically highlight based on whether their Href matches the current route. Default is false. |

#### `SidebarContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render. |
| `Class` | `string?` |  | Additional CSS classes. |

#### `SidebarFooter`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render in the footer. |
| `Class` | `string?` |  | Additional CSS classes. |

#### `SidebarGroup`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The group content (typically SidebarGroupLabel, SidebarGroupAction, SidebarGroupContent). |
| `Class` | `string?` |  | Additional CSS classes. |

#### `SidebarGroupAction`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The button content (typically an icon). |
| `Tooltip` | `string?` |  | Tooltip text for the action. |
| `AsChild` | `SidebarMenuButtonElement` | `SidebarMenuButtonElement.Button` | The element tag to render (button or a). |
| `Class` | `string?` |  | Additional CSS classes. |

#### `SidebarGroupContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The group content. |
| `Class` | `string?` |  | Additional CSS classes. |

#### `SidebarGroupLabel`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The label content. |
| `AsChild` | `SidebarGroupLabelElement` | `SidebarGroupLabelElement.Div` | The element tag to render (div or button for collapsible). |
| `Class` | `string?` |  | Additional CSS classes. |

#### `SidebarHeader`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render in the header. |
| `Class` | `string?` |  | Additional CSS classes. |

#### `SidebarHeaderContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render (typically SidebarHeaderIcon and SidebarHeaderInfo). |
| `Class` | `string?` |  | Additional CSS classes. |

#### `SidebarHeaderInfo`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The text content to render (typically title and subtitle spans). |
| `Class` | `string?` |  | Additional CSS classes. |

#### `SidebarInset`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The main content to render. |
| `Class` | `string?` |  | Additional CSS classes to apply to the inset. |

#### `SidebarMenu`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The menu items to render. |
| `Class` | `string?` |  | Additional CSS classes. |

#### `SidebarMenuAction`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The button content (typically an icon). |
| `Tooltip` | `string?` |  | Tooltip text for the action. |
| `ShowOnHover` | `bool` |  | Whether to show the action only on hover. |
| `AsChild` | `SidebarMenuButtonElement` | `SidebarMenuButtonElement.Button` | The element tag to render (button or a). |
| `Class` | `string?` |  | Additional CSS classes. |

#### `SidebarMenuBadge`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The badge content (typically a number or text). |
| `Class` | `string?` |  | Additional CSS classes. |

#### `SidebarMenuButton`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The button content. |
| `Tooltip` | `string?` |  | Tooltip text to show when sidebar is collapsed (icon-only mode). |
| `Size` | `SidebarMenuButtonSize` | `SidebarMenuButtonSize.Default` | Size variant for the button. |
| `Variant` | `SidebarMenuButtonVariant` | `SidebarMenuButtonVariant.Default` | Style variant for the button. |
| `IsActive` | `bool?` |  | Whether this menu item is active/selected. If not set, active state will be auto-detected based on Href and Match if the Sidebar has AutoDetectActive enabled. |
| `AsChild` | `SidebarMenuButtonElement` | `SidebarMenuButtonElement.Button` | The element type to render. Defaults to Button, but automatically switches to Anchor if Href is provided. |
| `Href` | `string?` |  | The URL to navigate to. When provided, the button automatically renders as a NavLink (unless AsChild is explicitly set to Button). |
| `Match` | `NavLinkMatch` | `NavLinkMatch.Prefix` | How the link should match the current URL. Default is NavLinkMatch.Prefix. |
| `Class` | `string?` |  | Additional CSS classes. |

#### `SidebarMenuChevron`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The chevron icon content (typically a LucideIcon). |
| `Class` | `string?` |  | Additional CSS classes. |

#### `SidebarMenuItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The menu item content (typically SidebarMenuButton). |
| `Class` | `string?` |  | Additional CSS classes. |

#### `SidebarMenuSkeleton`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ShowIcon` | `bool` |  | Whether to show an icon skeleton. |
| `Class` | `string?` |  | Additional CSS classes. |

#### `SidebarMenuSub`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The submenu items to render. |
| `Class` | `string?` |  | Additional CSS classes. |

#### `SidebarMenuSubButton`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The button content. |
| `AsChild` | `SidebarMenuButtonElement` | `SidebarMenuButtonElement.Button` | The element tag to render. Defaults to Button, but automatically switches to Anchor if Href is provided. |
| `Href` | `string?` |  | The URL to navigate to. When provided, the button automatically renders as a NavLink (unless AsChild is explicitly set to Button). |
| `Match` | `NavLinkMatch` | `NavLinkMatch.Prefix` | How the link should match the current URL. Default is NavLinkMatch.Prefix. |
| `IsActive` | `bool?` |  | Whether this submenu item is active/selected. If not set, active state will be auto-detected based on Href and Match if the Sidebar has AutoDetectActive enabled. |
| `Size` | `SidebarMenuSubButtonSize` | `SidebarMenuSubButtonSize.Medium` | Button size variant. |
| `Class` | `string?` |  | Additional CSS classes. |

#### `SidebarMenuSubItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The submenu item content (typically SidebarMenuSubButton). |

#### `SidebarProvider`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render inside the sidebar provider. Should typically contain SidebarLayout with Sidebar and SidebarInset. |
| `DefaultOpen` | `bool` | `true` | Default open state for the sidebar on desktop. |
| `Variant` | `SidebarVariant` | `SidebarVariant.Sidebar` | The sidebar variant/style. |
| `Side` | `SidebarSide` | `SidebarSide.Left` | Which side the sidebar appears on. |
| `CookieKey` | `string?` | `"sidebar:state"` | Cookie key for persisting sidebar state. Set to null to disable persistence. |
| `HeightClass` | `string` | `"min-h-screen"` | CSS class for controlling the container height. Defaults to "min-h-screen" to fill viewport and grow with content. Can be set to "h-screen" for fixed viewport height or "h-full" for contained layouts. |
| `StaticRendering` | `bool` | `false` | Enable static rendering mode for SSR/prerendering scenarios. When true, JS will set up click delegation to call C# toggle via interop. Set to true when using rendermode="InteractiveServer" or "InteractiveAuto" in MainLayout. |

#### `SidebarRail`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `OnClick` | `EventCallback<MouseEventArgs>` |  | Click handler for custom behavior. |
| `Class` | `string?` |  | Additional CSS classes. |

#### `SidebarSeparator`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Class` | `string?` |  | Additional CSS classes. |

#### `SidebarTrigger`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Custom content for the trigger button. If not provided, defaults to a panel-left icon. |
| `OnClick` | `EventCallback<MouseEventArgs>` |  | Click handler for custom behavior.4 |
| `Class` | `string?` |  | Additional CSS classes. |

**Basic Usage:**
```razor
<SidebarProvider>
 <Sidebar>
  <SidebarHeader>
<h2 class="text-lg font-semibold">App Name</h2>
  </SidebarHeader>
  <SidebarContent>
<SidebarGroup>
 <SidebarGroupLabel>Navigation</SidebarGroupLabel>
 <SidebarGroupContent>
  <SidebarMenuItem>
<SidebarMenuButton Href="/">
 <LucideIcon Name="home" Size="16" />
 Home
</SidebarMenuButton>
  </SidebarMenuItem>
  <SidebarMenuItem>
<SidebarMenuButton Href="/settings">
 <LucideIcon Name="settings" Size="16" />
 Settings
</SidebarMenuButton>
  </SidebarMenuItem>
 </SidebarGroupContent>
</SidebarGroup>
  </SidebarContent>
  <SidebarFooter>
<SidebarMenuItem>User Menu</SidebarMenuItem>
  </SidebarFooter>
 </Sidebar>
 <SidebarInset>
  <main>@Body</main>
 </SidebarInset>
</SidebarProvider>
```

---

### Skeleton

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Loading placeholders with shimmer animation. Shows content structure while loading.

**Components & Parameters:**

#### `Skeleton`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Shape` | `SkeletonShape` | `SkeletonShape.Rectangular` | Gets or sets the shape variant of the skeleton. A  value. Default is . : Default rectangular shape with rounded corners : Circular shape, ideal for avatar placeholders |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the skeleton element. A string containing one or more CSS class names, or null. Use this parameter to customize the skeleton's dimensions and spacing. Common Tailwind utilities include: Height: h-4, h-12, h-[200px] Width: w-full, w-[250px], w-1/2 Margin: mb-2, mt-4 |

**Basic Usage:**
```razor
@* Simple skeleton *@
<Skeleton Class="h-12 w-12 rounded-full" />

@* Card skeleton *@
<Card>
 <CardHeader>
  <Skeleton Class="h-4 w-1/2" />
  <Skeleton Class="h-3 w-3/4 mt-2" />
 </CardHeader>
 <CardContent>
  <Skeleton Class="h-32 w-full" />
 </CardContent>
</Card>
```

---

### Slider

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Range input for numeric value selection with single or multiple handles. Interactive slider for selecting values.

**Components & Parameters:**

#### `Slider`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Value` | `double` |  | Gets or sets the current value of the slider. |
| `ValueChanged` | `EventCallback<double>` |  | Gets or sets the callback that is invoked when the value changes. |
| `Min` | `double` | `0` | Gets or sets the minimum value. |
| `Max` | `double` | `100` | Gets or sets the maximum value. |
| `Step` | `double` | `1` | Gets or sets the step increment. |
| `Disabled` | `bool` |  | Gets or sets whether the slider is disabled. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the slider. |

**Basic Usage:**
```razor
@* Single value slider *@
<Slider @bind-Value="sliderValue" Min="0" Max="100" Step="1" />
<p>Value: @sliderValue</p>

@* Range slider *@
<Slider @bind-Value="rangeValues" Min="0" Max="100" />

@code {
 private double sliderValue = 50;
 private double[] rangeValues = new[] { 25.0, 75.0 };
}
```

---

### Spinner

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Loading indicators with multiple sizes. Animated spinner for loading states.

**Components & Parameters:**

#### `Spinner`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Size` | `SpinnerSize` | `SpinnerSize.Medium` | Gets or sets the size of the spinner. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the spinner. |

**Basic Usage:**
```razor
@* Default spinner *@
<Spinner />

@* Different sizes *@
<Spinner Size="SpinnerSize.Small" />
<Spinner Size="SpinnerSize.Large" />

@* With text *@
<div class="flex items-center gap-2">
 <Spinner />
 <span>Loading...</span>
</div>
```

---

### Switch

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Toggle switch component for boolean settings. Alternative to checkbox with toggle UI.

**Components & Parameters:**

#### `Switch`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Checked` | `bool` |  | Gets or sets whether the switch is checked (on). This property supports two-way binding using the @bind-Checked directive. Changes to this property trigger the CheckedChanged event callback. |
| `CheckedChanged` | `EventCallback<bool>` |  | Gets or sets the callback invoked when the checked state changes. This event callback enables two-way binding with @bind-Checked. It is invoked whenever the user toggles the switch state. |
| `Disabled` | `bool` |  | Gets or sets whether the switch is disabled. When disabled: - Switch cannot be clicked or focused - Opacity is reduced - Pointer events are disabled - aria-disabled attribute is set to true |
| `Size` | `SwitchSize` | `SwitchSize.Medium` | Gets or sets the size variant of the switch. Available sizes: - Small: Compact switch for dense layouts - Medium: Default size (recommended) - Large: Prominent switch for primary actions |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the switch. Custom classes are appended after the component's base classes, allowing for style overrides and extensions. |
| `AriaLabel` | `string?` |  | Gets or sets the ARIA label for the switch. Provides accessible text for screen readers when the switch doesn't have associated label text. |
| `Id` | `string?` |  | Gets or sets the ID attribute for the switch element. Used for associating the switch with label elements via htmlFor attribute. |
| `Name` | `string?` |  | Gets or sets the name of the switch for form submission. This is critical for form submission. The name/value pair is submitted to the server. If not specified, falls back to the Id value. |
| `Required` | `bool` |  | Gets or sets whether the switch is required. When true, the switch must be checked for form submission. Works with form validation. |
| `CheckedExpression` | `Expression<Func<bool>>?` |  | Gets or sets an expression that identifies the bound value. Used for form validation integration. When provided, the switch registers with the EditContext and participates in form validation. |

**Basic Usage:**
```razor
@* Simple switch *@
<Switch @bind-Checked="isEnabled" />

@* With label *@
<div class="flex items-center space-x-2">
 <Switch Id="airplane-mode" @bind-Checked="airplaneMode" />
 <Label For="airplane-mode">Airplane Mode</Label>
</div>

@* Disabled *@
<Switch Disabled="true" />

@code {
 private bool isEnabled = false;
 private bool airplaneMode = false;
}
```

---

### Tabs

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Tabbed interfaces with controlled/uncontrolled modes. Organize content into switchable tabs.

**Components & Parameters:**

#### `Tabs`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render within the tabs. Should include TabsList and TabsContent components. |
| `Value` | `string?` |  | Controls which tab is active (controlled mode). When null, the tabs manage their own state (uncontrolled mode). |
| `ValueChanged` | `EventCallback<string?>` |  | Event callback invoked when the active tab changes. Use with @bind-Value for two-way binding. |
| `DefaultValue` | `string?` |  | Default active tab value when in uncontrolled mode. |
| `OnValueChange` | `EventCallback<string?>` |  | Event callback invoked when the active tab changes. |
| `Orientation` | `TabsOrientation` | `TabsOrientation.Horizontal` | Orientation of the tabs (horizontal or vertical). Default is horizontal. |
| `ActivationMode` | `TabsActivationMode` | `TabsActivationMode.Automatic` | Activation mode for tabs (automatic on focus or manual on click). Default is automatic. |

#### `TabsContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ForceMount` | `bool` | `false` | Whether to force mount the content even when inactive. |
| `ChildContent` | `RenderFragment?` |  | The child content to render when this tab is active. |
| `Class` | `string?` |  | Additional CSS classes to apply to the tab content. |

#### `TabsList`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render within the tabs list. Should contain TabsTrigger components. |
| `Class` | `string?` |  | Additional CSS classes to apply to the tabs list. |

#### `TabsTrigger`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Disabled` | `bool` |  | Whether this tab trigger is disabled. |
| `ChildContent` | `RenderFragment?` |  | The child content to render within the tab trigger. |
| `Class` | `string?` |  | Additional CSS classes to apply to the tab trigger. |

**Basic Usage:**
```razor
<Tabs DefaultValue="tab1">
 <TabsList>
  <TabsTrigger Value="tab1">Account</TabsTrigger>
  <TabsTrigger Value="tab2">Password</TabsTrigger>
 </TabsList>
 <TabsContent Value="tab1">
  <Card>
<CardHeader>
 <CardTitle>Account</CardTitle>
</CardHeader>
<CardContent>Account settings content</CardContent>
  </Card>
 </TabsContent>
 <TabsContent Value="tab2">
  <Card>
<CardHeader>
 <CardTitle>Password</CardTitle>
</CardHeader>
<CardContent>Password settings content</CardContent>
  </Card>
 </TabsContent>
</Tabs>
```

---

### Textarea

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Multi-line text input with automatic content sizing. Resizable textarea for long text input.

**Components & Parameters:**

#### `Textarea`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Value` | `string?` |  | Gets or sets the current value of the textarea. Supports two-way binding via @bind-Value syntax. |
| `ValueChanged` | `EventCallback<string?>` |  | Gets or sets the callback invoked when the textarea value changes. This event is fired on every keystroke (oninput event). Use with Value parameter for two-way binding. |
| `Placeholder` | `string?` |  | Gets or sets the placeholder text displayed when the textarea is empty. Provides a hint to the user about what to enter. Should not be used as a replacement for a label. |
| `Disabled` | `bool` |  | Gets or sets whether the textarea is disabled. When disabled: - Textarea cannot be focused or edited - Cursor is set to not-allowed - Opacity is reduced for visual feedback |
| `Required` | `bool` |  | Gets or sets whether the textarea is required. When true, the HTML5 required attribute is set. Works with form validation and :invalid CSS pseudo-class. |
| `MaxLength` | `int?` |  | Gets or sets the maximum number of characters allowed in the textarea. When set, the HTML5 maxlength attribute is applied. Browser will prevent users from entering more than this many characters. |
| `MinLength` | `int?` |  | Gets or sets the minimum number of characters required. Works with form validation. Browser validates that at least this many characters are present. |
| `Name` | `string?` |  | Gets or sets the name of the textarea for form submission. This is critical for form submission. The name/value pair is submitted to the server. Should be unique within the form. |
| `Autocomplete` | `string?` |  | Gets or sets the autocomplete hint for the browser. Examples: "on", "off", "name", "street-address". Helps browsers provide appropriate autofill suggestions. |
| `Readonly` | `bool` |  | Gets or sets whether the textarea is read-only. When true, the user cannot modify the value, but it's still focusable and submitted with forms. Different from Disabled - readonly textareas are still submitted with forms. |
| `Rows` | `int?` |  | Gets or sets the visible number of text rows. Specifies the height of the textarea in rows of text. If not specified, the component uses field-sizing-content for automatic sizing. |
| `Cols` | `int?` |  | Gets or sets the visible width in characters. Specifies the width of the textarea in average character widths. Usually controlled by CSS width instead. |
| `Wrap` | `string?` |  | Gets or sets how text wraps when submitted in a form. Values: "soft" (default - newlines not submitted), "hard" (newlines submitted), "off" (no wrapping). When "hard", the cols attribute must be specified. |
| `InputMode` | `string?` |  | Gets or sets the input mode hint for mobile keyboards. Examples: "none", "text", "decimal", "numeric", "tel", "search", "email", "url". Helps mobile devices show the appropriate keyboard. |
| `Autofocus` | `bool` |  | Gets or sets whether the textarea should be auto-focused when the page loads. Only one element per page should have autofocus. Improves accessibility when used appropriately. |
| `Spellcheck` | `bool?` |  | Gets or sets whether spell checking is enabled. Can be true, false, or null (browser default). Useful for controlling spell checking on technical content, code, etc. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the textarea. Custom classes are appended after the component's base classes, allowing for style overrides and extensions. |
| `Id` | `string?` |  | Gets or sets the HTML id attribute for the textarea element. Used to associate the textarea with a label element via the label's 'for' attribute. This is essential for accessibility and allows clicking the label to focus the textarea. |
| `AriaLabel` | `string?` |  | Gets or sets the ARIA label for the textarea. Provides an accessible name for screen readers. Use when there is no visible label element. |
| `AriaDescribedBy` | `string?` |  | Gets or sets the ID of the element that describes the textarea. References the id of an element containing help text or error messages. Improves screen reader experience by associating descriptive text. |
| `AriaInvalid` | `bool?` |  | Gets or sets whether the textarea value is invalid. When true, aria-invalid="true" is set. Should be set based on validation state. Triggers destructive color styling for error states. |

**Basic Usage:**
```razor
@* Simple textarea *@
<Textarea @bind-Value="description" 
 Placeholder="Enter description..." />

@* With rows *@
<Textarea @bind-Value="comments" 
 Rows="5" 
 Placeholder="Your comments..." />

@* Disabled *@
<Textarea Value="Read only text" Disabled="true" />

@code {
 private string description = "";
 private string comments = "";
}
```

---

### TimePicker

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Time selection with 12/24-hour format support. Interactive time input with dropdown selection.

**Components & Parameters:**

#### `TimePicker`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `SelectedTime` | `TimeOnly?` |  | The selected time. |
| `SelectedTimeChanged` | `EventCallback<TimeOnly?>` |  | Event callback invoked when the selected time changes. Use with @bind-SelectedTime for two-way binding. |
| `Use24HourFormat` | `bool` | `false` | Whether to use 24-hour format. Default is false (12-hour with AM/PM). |
| `MinuteStep` | `int` | `1` | Minute step interval. Default is 1. |
| `ButtonVariant` | `ButtonVariant` | `ButtonVariant.Outline` | Button variant for the trigger button. |
| `ButtonSize` | `ButtonSize` | `ButtonSize.Default` | Button size for the trigger button. |
| `ShowIcon` | `bool` | `true` | Whether to show the clock icon in the button. |
| `Placeholder` | `string` | `"Pick a time"` | Placeholder text when no time is selected. |
| `TimeFormat` | `string?` |  | Time format string for displaying the selected time. If not specified, uses "hh:mm tt" for 12-hour or "HH:mm" for 24-hour. |
| `Disabled` | `bool` |  | Whether the time picker is disabled. |
| `Align` | `PopoverAlign` | `PopoverAlign.Start` | Alignment of the popover content. |
| `Class` | `string?` |  | Additional CSS classes for the button. |
| `AriaLabel` | `string?` |  | ARIA label for the button. |

**Basic Usage:**
```razor
@* 12-hour format *@
<TimePicker @bind-Value="selectedTime" />

@* 24-hour format *@
<TimePicker @bind-Value="selectedTime" 
Format="TimeFormat.Hour24" />

@code {
 private TimeSpan? selectedTime;
}
```

---

### Toast

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Temporary notifications with variants and actions. Shows brief messages and alerts.

**Components & Parameters:**

#### `Toast`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Id` | `string?` |  | The unique identifier for this toast. |
| `Title` | `string?` |  | The title of the toast. |
| `Description` | `string?` |  | The description of the toast. |
| `Variant` | `ToastVariant` | `ToastVariant.Default` | The variant/style of the toast. |
| `ActionLabel` | `string?` |  | The label for the action button. |
| `OnAction` | `Action?` |  | Callback when action button is clicked. |
| `OnDismiss` | `Action?` |  | Callback when the toast is dismissed. |
| `Class` | `string?` |  | Additional CSS classes to apply to the toast. |

#### `ToastAction`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Label` | `string?` |  | The button label. |
| `OnClick` | `EventCallback` |  | Callback when the button is clicked. |
| `Class` | `string?` |  | Additional CSS classes to apply. |

#### `ToastClose`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `OnClick` | `EventCallback` |  | Callback when the button is clicked. |
| `Class` | `string?` |  | Additional CSS classes to apply. |

#### `ToastDescription`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The description content. |
| `Class` | `string?` |  | Additional CSS classes to apply. |

#### `ToastProvider`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render within the provider. |
| `Position` | `ToastPosition` | `ToastPosition.BottomRight` | The position of the toast viewport. Default is BottomRight. |
| `MaxToasts` | `int` | `5` | Maximum number of toasts to display at once. Default is 5. |

#### `ToastTitle`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The title content. |
| `Class` | `string?` |  | Additional CSS classes to apply. |

#### `ToastViewport`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Position` | `ToastPosition` | `ToastPosition.BottomRight` | The position of the viewport. Default is BottomRight. |
| `MaxToasts` | `int` | `5` | Maximum number of toasts to display at once. Default is 5. |
| `Class` | `string?` |  | Additional CSS classes to apply to the viewport. |

**Basic Usage:**
```razor
@inject IToastService ToastService

<Button OnClick="ShowToast">Show Toast</Button>

@code {
 private void ShowToast()
 {
  ToastService.Show("Event created successfully!");
 }
 
 private void ShowDestructiveToast()
 {
  ToastService.Show(
"Error occurred",
"There was a problem with your request.",
ToastVariant.Destructive
  );
 }
}
```

---

### Toggle

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Pressable toggle buttons for boolean states. Button that toggles between pressed and unpressed.

**Components & Parameters:**

#### `Toggle`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Pressed` | `bool` |  | Gets or sets whether the toggle is pressed. |
| `PressedChanged` | `EventCallback<bool>` |  | Gets or sets the callback that is invoked when the pressed state changes. |
| `Variant` | `ToggleVariant` | `ToggleVariant.Default` | Gets or sets the visual variant of the toggle. |
| `Size` | `ToggleSize` | `ToggleSize.Default` | Gets or sets the size of the toggle. |
| `Disabled` | `bool` |  | Gets or sets whether the toggle is disabled. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the toggle. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the toggle. |

**Basic Usage:**
```razor
@* Simple toggle *@
<Toggle @bind-Pressed="isPressed">
 <LucideIcon Name="bold" Size="16" />
</Toggle>

@* Toggle group *@
<div class="flex gap-1">
 <Toggle @bind-Pressed="isBold">
  <LucideIcon Name="bold" Size="16" />
 </Toggle>
 <Toggle @bind-Pressed="isItalic">
  <LucideIcon Name="italic" Size="16" />
 </Toggle>
</div>

@code {
 private bool isPressed = false;
 private bool isBold = false;
 private bool isItalic = false;
}
```

---

### ToggleGroup

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Single or multiple selection toggle groups. Group of toggle buttons with exclusive or multi-select.

**Components & Parameters:**

#### `ToggleGroup`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Type` | `ToggleGroupType` | `ToggleGroupType.Single` | Gets or sets the type of toggle group (single or multiple selection). |
| `Value` | `string?` |  | Gets or sets the currently selected value (for single selection mode). |
| `ValueChanged` | `EventCallback<string?>` |  | Gets or sets the callback that is invoked when the value changes. |
| `Values` | `List<string>?` |  | Gets or sets the currently selected values (for multiple selection mode). |
| `ValuesChanged` | `EventCallback<List<string>?>` |  | Gets or sets the callback that is invoked when the values change. |
| `Disabled` | `bool` |  | Gets or sets whether the toggle group is disabled. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the toggle group. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the toggle group. |

#### `ToggleGroupItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Value` | `string` | `string.Empty` | Gets or sets the value of this toggle item. |
| `Disabled` | `bool` |  | Gets or sets whether this item is disabled. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the toggle item. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the toggle item. |

**Basic Usage:**
```razor
@* Single selection *@
<ToggleGroup @bind-Value="selectedValue" Type="ToggleGroupType.Single">
 <ToggleGroupItem Value="left">
  <LucideIcon Name="align-left" Size="16" />
 </ToggleGroupItem>
 <ToggleGroupItem Value="center">
  <LucideIcon Name="align-center" Size="16" />
 </ToggleGroupItem>
 <ToggleGroupItem Value="right">
  <LucideIcon Name="align-right" Size="16" />
 </ToggleGroupItem>
</ToggleGroup>

@* Multiple selection *@
<ToggleGroup @bind-Values="selectedValues" Type="ToggleGroupType.Multiple">
 <ToggleGroupItem Value="bold">B</ToggleGroupItem>
 <ToggleGroupItem Value="italic">I</ToggleGroupItem>
 <ToggleGroupItem Value="underline">U</ToggleGroupItem>
</ToggleGroup>

@code {
 private string? selectedValue;
 private HashSet<string> selectedValues = new();
}
```

---

### Tooltip

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Contextual hover tooltips with delay and positioning. Shows helpful text on hover.

**Components & Parameters:**

#### `Tooltip`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The child content to render within the tooltip. Typically includes TooltipTrigger and TooltipContent. |
| `Open` | `bool?` |  | Controls whether the tooltip is open (controlled mode). When null, the tooltip manages its own state (uncontrolled mode). |
| `OpenChanged` | `EventCallback<bool>` |  | Event callback invoked when the open state changes. Use with @bind-Open for two-way binding. |
| `DefaultOpen` | `bool` | `false` | Default open state when in uncontrolled mode. |
| `DelayDuration` | `int` | `300` | The delay in milliseconds before showing the tooltip. Default is 300ms. |
| `HideDelay` | `int` | `0` | The delay in milliseconds before hiding the tooltip after mouse leaves. Default is 0ms (immediate). |
| `Placement` | `PopoverPlacement` | `PopoverPlacement.Top` | The placement position for the tooltip. Default is PopoverPlacement.Top. |

#### `TooltipContent`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to render inside the tooltip. |
| `Class` | `string?` |  | Additional CSS classes to apply to the content container. |
| `Side` | `PopoverSide` | `PopoverSide.Top` | Preferred side for positioning: PopoverSide.Top, PopoverSide.Bottom, PopoverSide.Left, PopoverSide.Right. Default is PopoverSide.Top. |
| `Align` | `PopoverAlign` | `PopoverAlign.Center` | Alignment relative to trigger: "@PopoverAlign.Start", "@PopoverAlign.Center", "@PopoverAlign.End". Default is "@PopoverAlign.Center". |
| `Offset` | `int` | `8` | Offset distance from the trigger in pixels. Default is 8. |

#### `TooltipProvider`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `DelayDuration` | `int` | `700` | Gets or sets the duration in milliseconds to wait before showing a tooltip. The delay duration in milliseconds. Default is 700ms. This delay applies to all child  components. When a user hovers over or focuses a tooltip trigger, the tooltip will wait this duration before appearing. Recommended values: 0-200ms: Very fast (toolbars, frequently accessed UI) 300-500ms: Fast (interactive elements) 600-800ms: Standard (balanced, default) 900-1200ms: Slow (detailed information) Individual tooltips cannot override this value - they inherit it from their nearest TooltipProvider ancestor. |
| `SkipDelayDuration` | `int` | `300` | Gets or sets the duration in milliseconds during which the delay is skipped for subsequent tooltips. The skip delay duration in milliseconds. Default is 300ms. After a user sees one tooltip, subsequent tooltips within this time window appear immediately without delay. This creates a fluid "tooltip discovery mode" experience. Recommended values: 0ms: Disable skip behavior 200-400ms: Short window (closely grouped elements) 500-1000ms: Standard window (comfortable exploration) 1500-3000ms: Long window (very forgiving) Set to 0 to disable the skip delay feature entirely. All tooltips will always wait the full . |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content to be rendered within the provider. A  containing child components, or null. All child  components will receive the tooltip configuration from this provider via Blazor's CascadingValue mechanism. |

#### `TooltipTrigger`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | The content to display inside the trigger. |
| `Class` | `string?` |  | Additional CSS classes to apply to the wrapper. |
| `AsChild` | `bool` | `false` | When true, the trigger does not render its own span element. Instead, it passes trigger behavior via TriggerContext to child components. Use this when you want a custom component to act as the trigger. |
| `Focusable` | `bool` | `true` | Whether the trigger should be keyboard focusable. Default is true. Set to false if child content is already focusable. |
| `OnMouseEnter` | `EventCallback<MouseEventArgs>` |  | Custom mouse enter handler. |
| `OnMouseLeave` | `EventCallback<MouseEventArgs>` |  | Custom mouse leave handler. |

**Basic Usage:**
```razor
<Tooltip>
 <TooltipTrigger AsChild>
  <Button Size="ButtonSize.Icon" Variant="ButtonVariant.Outline">
<LucideIcon Name="info" Size="16" />
  </Button>
 </TooltipTrigger>
 <TooltipContent>
  <p>Additional information</p>
 </TooltipContent>
</Tooltip>

@* With delay *@
<Tooltip DelayDuration="500">
 <TooltipTrigger AsChild>
  <span>Hover me</span>
 </TooltipTrigger>
 <TooltipContent>Tooltip text</TooltipContent>
</Tooltip>
```

---

### Typography

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Semantic text styling components for headings, paragraphs, lists, and more. Consistent text styles across the application.

**Components & Parameters:**

#### `Typography`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Variant` | `TypographyVariant` | `TypographyVariant.P` | Gets or sets the typography variant. |
| `Class` | `string?` |  | Gets or sets additional CSS classes to apply to the typography element. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the content to be rendered inside the typography element. |

**Basic Usage:**
```razor
@* Headings *@
<TypographyH1>Heading 1</TypographyH1>
<TypographyH2>Heading 2</TypographyH2>
<TypographyH3>Heading 3</TypographyH3>

@* Paragraph *@
<TypographyP>
 This is a paragraph with proper styling and spacing.
</TypographyP>

@* Other elements *@
<TypographyBlockquote>
 A meaningful quote
</TypographyBlockquote>

<TypographyList>
 <li>List item 1</li>
 <li>List item 2</li>
</TypographyList>

<TypographyInlineCode>const code = true;</TypographyInlineCode>

<TypographyLead>
 Lead text that stands out
</TypographyLead>
```

---

### Timeline

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Composable chronological event display with statuses, icons, connectors, and collapsible items. Supports Center, Left, Right, and Alternate alignment modes.

**Components & Parameters:**

#### `Timeline`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Size` | `TimelineSize` | `TimelineSize.Medium` | Gets or sets the size variant controlling gap spacing between items. |
| `Align` | `TimelineAlign` | `TimelineAlign.Center` | Gets or sets the layout alignment for timeline items. |
| `ConnectorFit` | `TimelineConnectorFit` | `TimelineConnectorFit.Spaced` | Gets or sets how the connector line fits between icons. |
| `Class` | `string?` |  | Gets or sets additional CSS classes. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content (TimelineItem elements). |

#### `TimelineItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Status` | `TimelineStatus` | `TimelineStatus.Completed` | Gets or sets the current status of the item. |
| `IconColor` | `TimelineColor` | `TimelineColor.Primary` | Gets or sets the color theme for the icon. |
| `ConnectorColor` | `TimelineColor?` |  | Gets or sets the color theme for the connector line. |
| `ShowConnector` | `bool` | `true` | Gets or sets whether to show the connector line below this item. |
| `IconSize` | `TimelineSize?` |  | Gets or sets the icon size. When null, inherits from parent Timeline's Size. |
| `IconVariant` | `TimelineIconVariant` | `TimelineIconVariant.Solid` | Gets or sets the icon style variant. |
| `ConnectorStyle` | `TimelineConnectorStyle` | `TimelineConnectorStyle.Solid` | Gets or sets the connector line style. |
| `Loading` | `bool` | `false` | Gets or sets whether the item is in a loading state (shows pulse animation). |
| `IsCollapsible` | `bool` | `false` | Gets or sets whether the item content is collapsible. |
| `DefaultOpen` | `bool` | `true` | Gets or sets whether collapsible content is open by default. |
| `Title` | `string?` |  | Shorthand title text. Auto-renders the full content tree when ChildContent is null. |
| `Time` | `string?` |  | Shorthand time/date text. |
| `Description` | `string?` |  | Shorthand description text. |
| `DetailContent` | `RenderFragment?` |  | Gets or sets the detail content shown when collapsible is expanded. |
| `IconContent` | `RenderFragment?` |  | Gets or sets custom icon content to replace the default icon. |
| `TimeContent` | `RenderFragment?` |  | Gets or sets the time/date content for the date column. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the main content. |
| `Class` | `string?` |  | Gets or sets additional CSS classes. |

**Enums:**

`TimelineSize`: `Small`, `Medium`, `Large`

`TimelineAlign`: `Center`, `Left`, `Right`, `Alternate`

`TimelineStatus`: `Completed`, `InProgress`, `Pending`

`TimelineColor`: `Primary`, `Secondary`, `Muted`, `Accent`, `Destructive`

`TimelineConnectorFit`: `Spaced`, `Connected`

`TimelineConnectorStyle`: `Solid`, `Dashed`, `Dotted`

`TimelineIconVariant`: `Solid`, `Outline`

**Basic Usage:**
```razor
<Timeline Align="TimelineAlign.Center">
 <TimelineItem Title="Order Placed"
               Time="Jan 1, 2025"
               Status="TimelineStatus.Completed"
               Description="Your order has been received." />
 <TimelineItem Title="Processing"
               Time="Jan 2, 2025"
               Status="TimelineStatus.InProgress" />
 <TimelineItem Title="Shipped"
               Status="TimelineStatus.Pending" />
</Timeline>
```

---

### ThemeSwitcher

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Popover-based theme switcher that lets users choose a base color (Zinc, Slate, Gray, Neutral, Stone), a primary accent color (18 options), and toggle dark mode. Displays a color-wheel circle as its trigger button. Persists selections via the injected `ThemeService`.

**Components & Parameters:**

#### `ThemeSwitcher`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Strategy` | `PositioningStrategy` | `Fixed` | Positioning strategy for the popover (`Fixed` or `Absolute`). |
| `ZIndex` | `int` | `60` | Z-index for the popover content. |
| `TriggerClass` | `string?` |  | Additional CSS classes for the trigger button. |
| `PopoverContentClass` | `string?` |  | Additional CSS classes for the popover content panel. |
| `Align` | `PopoverAlign` | `End` | Popover alignment relative to the trigger: `Start`, `Center`, `End`. |


**Basic Usage:**
```razor
<ThemeSwitcher />

@* Custom alignment *@
<ThemeSwitcher Align="PopoverAlign.Start" />
```

---

### TreeView

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Hierarchical data display with expand/collapse, single/multi selection, tri-state checkboxes, lazy loading, and drag-and-drop reordering. Supports nested (ChildrenProperty) and flat (ParentField) data structures.

**Components & Parameters:**

#### `TreeView<TItem>`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Items` | `IEnumerable<TItem>?` |  | Gets or sets the data source for data-driven mode. |
| `TextField` | `Func<TItem, string>?` |  | Gets or sets a function to extract display text from an item. |
| `ValueField` | `Func<TItem, string>?` |  | Gets or sets a function to extract the unique value/ID from an item. |
| `ChildrenProperty` | `Func<TItem, IEnumerable<TItem>?>?` |  | Gets or sets a function to extract child items from a parent (nested mode). |
| `ParentField` | `Func<TItem, string?>?` |  | Gets or sets a function to extract the parent ID from an item (flat mode). |
| `IconField` | `Func<TItem, string?>?` |  | Gets or sets a function to extract an icon name from an item. |
| `HasChildrenField` | `Func<TItem, bool>?` |  | Gets or sets a function to determine if an item has children (for lazy load). |
| `SelectionMode` | `TreeSelectionMode` | `TreeSelectionMode.None` | Gets or sets the selection mode. |
| `SelectedValue` | `string?` |  | Gets or sets the selected value in single selection mode. |
| `SelectedValueChanged` | `EventCallback<string?>` |  | Fired when selected value changes. |
| `SelectedValues` | `HashSet<string>?` |  | Gets or sets the selected values in multiple selection mode. |
| `SelectedValuesChanged` | `EventCallback<HashSet<string>>` |  | Fired when selection changes. |
| `ExpandedValues` | `HashSet<string>?` |  | Gets or sets the set of expanded node values (controlled mode). |
| `ExpandedValuesChanged` | `EventCallback<HashSet<string>>` |  | Fired when expanded values change. |
| `DefaultExpandAll` | `bool` | `false` | Gets or sets whether to expand all nodes on first render. |
| `DefaultExpandDepth` | `int?` |  | Gets or sets the depth to auto-expand on first render (1 = root children only). |
| `Checkable` | `bool` | `false` | Gets or sets whether nodes display checkboxes. |
| `CheckedValues` | `HashSet<string>?` |  | Gets or sets the checked values. |
| `CheckedValuesChanged` | `EventCallback<HashSet<string>>` |  | Fired when checked values change. |
| `PropagateChecks` | `bool` | `false` | When true, checking a parent checks all descendants and vice-versa with tri-state support. |
| `SearchText` | `string?` |  | Gets or sets the search text used to filter and highlight nodes. |
| `LoadChildrenAsync` | `Func<TItem, Task<IEnumerable<TItem>>>?` |  | When set, the tree calls this on first expand of each node for lazy loading. |
| `OnNodeDrop` | `EventCallback<(string Source, string Target, string Position)>` |  | Callback invoked when a node is dropped (drag-and-drop). |
| `OnNodeClick` | `EventCallback<string>` |  | Callback invoked when a node is clicked. |
| `ChildContent` | `RenderFragment?` |  | Declarative child content (TreeItem elements) for static trees. |
| `AriaLabel` | `string?` |  | ARIA label for the tree container. |
| `Class` | `string?` |  | Gets or sets additional CSS classes. |

**Enums:**

`TreeSelectionMode`: `None`, `Single`, `Multiple`

**Basic Usage:**
```razor
<TreeView TItem="FileNode"
          Items="@_files"
          TextField="n => n.Name"
          ValueField="n => n.Id"
          ChildrenProperty="n => n.Children"
          SelectionMode="TreeSelectionMode.Single"
          @bind-SelectedValue="_selected"
          DefaultExpandDepth="1" />

@code {
 private string? _selected;
 private List<FileNode> _files = [ /* ... */ ];

 record FileNode(string Id, string Name, List<FileNode>? Children = null);
}
```

---

### DataView

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Switchable list/grid layout container with built-in search, sort, grouping, pagination, virtualization, and item selection. Use DataViewColumn child declarations inside a Fields slot to enable built-in search and sort.

**Components & Parameters:**

#### `DataView<TItem>`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Items` | `IEnumerable<TItem>?` |  | Gets or sets the data source. |
| `ItemsProvider` | `ItemsProviderDelegate<TItem>?` |  | Server-side data provider for infinite-scroll virtualization. When set, Items is ignored and pagination is hidden. |
| `Layout` | `DataViewLayout` | `DataViewLayout.List` | Gets or sets the initial display mode. |
| `PageSize` | `int` | `0` | Gets or sets the items per page. 0 shows all items and hides pagination. |
| `PageSizes` | `int[]` | `[10,25,50,100]` | Gets or sets the available page-size options. |
| `SelectionMode` | `DataViewSelectionMode` | `DataViewSelectionMode.None` | Gets or sets the item selection mode. |
| `SelectedItem` | `TItem?` |  | Gets or sets the selected item in Single mode (two-way bindable). |
| `SelectedItemChanged` | `EventCallback<TItem?>` |  | Fired when the selected item changes. |
| `GroupBy` | `Func<TItem, object>?` |  | Gets or sets a function to extract the group key from each item. |
| `GridColumns` | `int` | `3` | Gets or sets the column count in Grid layout (1-6). Ignored when `GridColumnMinWidth` is set. |
| `GridColumnMinWidth` | `string?` |  | Enables CSS `repeat(auto-fill, minmax(…, 1fr))` grid. The browser computes column count automatically from container width. Accepts any CSS length (`"160px"`, `"10rem"`) or bare Tailwind spacing key (`"40"`). Overrides `GridColumns` when set. |
| `Loading` | `bool` | `false` | Gets or sets whether to show a loading spinner. |
| `EmptyText` | `string` | `"No items to display."` | Gets or sets the text shown when Items is empty and EmptyTemplate is null. |
| `ShowPagination` | `bool` | `true` | Gets or sets whether the pagination bar is visible. |
| `ShowToolbar` | `bool` | `true` | Gets or sets whether the toolbar is visible. |
| `Virtualize` | `bool` | `false` | When true and Items is set, renders via Virtualize for client-side virtual scrolling. Pagination is hidden. |
| `ItemHeight` | `float` | `72f` | Gets or sets the approximate item height in pixels used by the virtualizer. |
| `Height` | `string` | `"500px"` | Gets or sets the CSS height of the virtualized scroll container. Required when Virtualize is true. |
| `ItemTemplate` | `RenderFragment<TItem>?` |  | Shared template used for both layouts when layout-specific templates are not set. |
| `ListTemplate` | `RenderFragment<TItem>?` |  | List-specific item template. Provide with GridTemplate to enable the layout toggle button. |
| `GridTemplate` | `RenderFragment<TItem>?` |  | Grid-specific item template. Provide with ListTemplate to enable the layout toggle button. |
| `EmptyTemplate` | `RenderFragment?` |  | Custom empty-state content. |
| `Header` | `RenderFragment?` |  | Optional header rendered above the toolbar and items. |
| `ToolbarActions` | `RenderFragment?` |  | Custom content rendered in the toolbar. |
| `Fields` | `RenderFragment?` |  | DataViewColumn child declarations that enable built-in search and sort. |
| `Class` | `string?` |  | Gets or sets additional CSS classes. |

#### `DataViewColumn<TItem>`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Header` | `string?` |  | Gets or sets the column display name (shown in the sort picker). |
| `Property` | `Func<TItem, object?>?` |  | Gets or sets the property selector for sorting and searching. |
| `Sortable` | `bool` | `false` | Gets or sets whether this column can be sorted. |
| `Filterable` | `bool` | `false` | Gets or sets whether this column is included in the global search. |

**Enums:**

`DataViewLayout`: `List`, `Grid`

`DataViewSelectionMode`: `None`, `Single`, `Multiple`

**Basic Usage:**
```razor
<DataView TItem="Product"
          Items="@_products"
          Layout="DataViewLayout.Grid"
          GridColumns="3"
          PageSize="12">
 <Fields>
  <DataViewColumn Header="Name"     Property="p => p.Name"     Sortable Filterable />
  <DataViewColumn Header="Category" Property="p => p.Category" Sortable />
 </Fields>
 <ListTemplate Context="p">
  <div class="flex items-center gap-3 p-3">
   <span class="font-medium">@p.Name</span>
   <Badge>@p.Category</Badge>
  </div>
 </ListTemplate>
 <GridTemplate Context="p">
  <Card>
   <CardContent class="p-4">
    <p class="font-semibold">@p.Name</p>
    <p class="text-muted-foreground text-sm">@p.Category</p>
   </CardContent>
  </Card>
 </GridTemplate>
</DataView>

@code {
 record Product(string Name, string Category);
 private List<Product> _products = [ /* ... */ ];
}
```

---

### DynamicForm

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Schema-driven form renderer that generates complete forms from a FormSchema definition. Supports 30+ field types, validation, conditional visibility, multi-column layouts, collapsible sections, and custom renderers.

**Components & Parameters:**

#### `DynamicForm`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Schema` | `FormSchema?` |  | Gets or sets the form schema. |
| `Values` | `Dictionary<string, object?>` | `new()` | Gets or sets the current field values dictionary. |
| `ValuesChanged` | `EventCallback<Dictionary<string, object?>>` |  | Callback invoked when Values changes. |
| `OnValidSubmit` | `EventCallback<Dictionary<string, object?>>` |  | Callback invoked when validation passes and the form is submitted. |
| `OnSubmit` | `EventCallback<Dictionary<string, object?>>` |  | Callback invoked on submit even when validation fails. |
| `OnFieldChanged` | `EventCallback<FormFieldChangedEventArgs>` |  | Callback invoked when a field value changes. |
| `Columns` | `int` | `1` | Gets or sets the number of columns in the field grid (when schema does not override). |
| `ShowSubmitButton` | `bool` | `true` | Gets or sets whether to show the submit button. |
| `SubmitText` | `string` | `"Submit"` | Gets or sets the submit button label. |
| `ShowValidationSummary` | `bool` | `true` | Gets or sets whether to show a validation summary above the form. |
| `Disabled` | `bool` | `false` | Gets or sets whether all inputs are disabled. |
| `CustomRenderers` | `Dictionary<string, Func<FormFieldDefinition, Dictionary<string, object?>, RenderFragment>>?` |  | Gets or sets custom field renderers keyed by field name or type name. |
| `Class` | `string?` |  | Gets or sets additional CSS classes for the form element. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets additional form-level content appended before the submit button. |

#### `FormSchema`

| Property | Type | Description |
|----------|------|-------------|
| `Title` | `string?` | Optional form title. |
| `Description` | `string?` | Optional form description. |
| `Columns` | `int?` | Number of grid columns for the form. |
| `Sections` | `List<FormSectionDefinition>?` | Optional list of form sections for grouping fields. |
| `Fields` | `List<FormFieldDefinition>?` | Flat list of form fields (used when Sections is null). |

#### `FormFieldDefinition`

| Property | Type | Description |
|----------|------|-------------|
| `Name` | `string` | Field name (key in values dictionary). |
| `Label` | `string?` | Display label. |
| `Type` | `FieldType` | Input type determining which component is rendered. |
| `Required` | `bool` | Whether the field is required. |
| `Placeholder` | `string?` | Placeholder text. |
| `Description` | `string?` | Helper text shown below the field. |
| `DefaultValue` | `object?` | Initial value. |
| `ColSpan` | `int` | Column span within the form grid (default 1). |
| `VisibleWhen` | `string?` | Expression for conditional visibility (e.g. `"Country == 'US'"`). |
| `Options` | `List<FormSelectOption>?` | Options for Select/Radio/CheckboxGroup fields. |
| `Validations` | `List<FieldValidation>?` | Validation rules. |
| `Disabled` | `bool` | Whether this field is disabled. |
| `ReadOnly` | `bool` | Whether this field is read-only. |

**Enums:**

`FieldType`: `Text`, `Email`, `Password`, `Url`, `Phone`, `Number`, `Currency`, `Masked`, `Textarea`, `RichText`, `Select`, `Combobox`, `MultiSelect`, `NativeSelect`, `Checkbox`, `Switch`, `CheckboxGroup`, `RadioGroup`, `Date`, `DateRange`, `Time`, `DateTime`, `Color`, `File`, `OTP`, `Slider`, `RangeSlider`, `Tags`, `Rating`, `Custom`

**Basic Usage:**
```razor
<DynamicForm Schema="@_schema"
             @bind-Values="_values"
             OnValidSubmit="HandleSubmit" />

@code {
 private Dictionary<string, object?> _values = new();

 private FormSchema _schema = new()
 {
  Title = "Contact Form",
  Fields =
  [
   new() { Name = "name",    Label = "Full Name", Type = FieldType.Text,  Required = true },
   new() { Name = "email",   Label = "Email",     Type = FieldType.Email, Required = true },
   new() { Name = "message", Label = "Message",   Type = FieldType.Textarea },
   new() { Name = "role",    Label = "Role",       Type = FieldType.Select,
           Options = [new() { Label = "Admin", Value = "admin" },
                      new() { Label = "User",  Value = "user"  }] },
  ]
 };

 private void HandleSubmit(Dictionary<string, object?> values) { /* process */ }
}
```

---

### TagInput

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Tag/chip input with configurable add triggers (Enter, Comma, Space, Tab, Semicolon), async autocomplete suggestions, duplicate prevention, and max-tag enforcement.

**Components & Parameters:**

#### `TagInput`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Tags` | `IReadOnlyList<string>?` |  | Gets or sets the list of tags. Use @bind-Tags for two-way binding. |
| `TagsChanged` | `EventCallback<IReadOnlyList<string>?>` |  | Callback invoked when the tag list changes. |
| `Placeholder` | `string?` |  | Placeholder text shown when no tags are present. |
| `MaxTags` | `int` | `int.MaxValue` | Gets or sets the maximum number of tags allowed. |
| `MaxTagLength` | `int` | `50` | Gets or sets the maximum character length for a single tag. |
| `AllowDuplicates` | `bool` | `false` | Gets or sets whether duplicate tag values are allowed (case-insensitive). |
| `AddTrigger` | `TagInputTrigger` | `Enter \| Comma` | Gets or sets which keys trigger tag creation. Combine flags with bitwise OR. |
| `Validate` | `Func<string, bool>?` |  | Optional validation function. Return false to reject a tag. |
| `OnTagRejected` | `EventCallback<string>` |  | Callback invoked when a tag is rejected (duplicate, validation failure, or limit reached). |
| `Suggestions` | `IEnumerable<string>?` |  | Static list of suggestions shown as the user types. |
| `OnSearchSuggestions` | `Func<string, CancellationToken, Task<IEnumerable<string>>>?` |  | Async function to load suggestions based on the search query. |
| `SuggestionDebounceMs` | `int` | `300` | Gets or sets the debounce interval in milliseconds for suggestion search. |
| `Variant` | `TagInputVariant` | `TagInputVariant.Default` | Gets or sets the visual variant for rendered tags. |
| `Clearable` | `bool` | `false` | Gets or sets whether to show a clear-all button when tags are present. |
| `Disabled` | `bool` | `false` | Gets or sets whether the component is disabled. |
| `TagTemplate` | `RenderFragment<string>?` |  | Optional custom template for rendering each tag. |
| `AriaLabel` | `string?` |  | ARIA label for the input container. |
| `Class` | `string?` |  | Gets or sets additional CSS classes. |

**Enums:**

`TagInputVariant`: `Default`, `Outline`, `Secondary`

`TagInputTrigger` (flags): `Enter`, `Comma`, `Space`, `Tab`, `Semicolon`

**Basic Usage:**
```razor
<TagInput @bind-Tags="_tags"
          Placeholder="Add technology..."
          MaxTags="5"
          AllowDuplicates="false"
          OnSearchSuggestions="GetSuggestions" />

@code {
 private IReadOnlyList<string> _tags = ["Blazor", "C#"];

 private async Task<IEnumerable<string>> GetSuggestions(string q, CancellationToken ct)
 {
  var all = new[] { "Blazor", "C#", ".NET", "React", "TypeScript", "Rust" };
  return all.Where(t => t.Contains(q, StringComparison.OrdinalIgnoreCase));
 }
}
```

---

### SplitButton

**Package:** `NeoUI.Blazor`  
**Namespace:** `NeoUI.Blazor`

**Installation:**
```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor
```

**Description:**
Primary action button paired with a chevron-triggered dropdown for secondary actions. Both segments share the same Variant and Size. Use SplitButtonItem and SplitButtonSeparator inside DropdownContent.

**Components & Parameters:**

#### `SplitButton`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ChildContent` | `RenderFragment?` |  | Gets or sets the primary button label content. |
| `DropdownContent` | `RenderFragment?` |  | Gets or sets the dropdown menu items content. |
| `Variant` | `ButtonVariant` | `ButtonVariant.Default` | Gets or sets the visual variant. |
| `Size` | `ButtonSize` | `ButtonSize.Default` | Gets or sets the size. |
| `Disabled` | `bool` | `false` | Gets or sets whether the button is disabled. |
| `OnClick` | `EventCallback<MouseEventArgs>` |  | Gets or sets the primary button click callback. |
| `Icon` | `RenderFragment?` |  | Gets or sets an icon to render inside the primary button. |
| `IconPosition` | `IconPosition` | `IconPosition.Start` | Gets or sets the icon position inside the primary button. |
| `AriaLabel` | `string?` |  | Gets or sets the aria-label for the primary button. |
| `DropdownAriaLabel` | `string?` |  | Gets or sets the aria-label for the dropdown toggle button. |
| `Class` | `string?` |  | Gets or sets additional CSS classes. |

#### `SplitButtonItem`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `OnClick` | `EventCallback` |  | Gets or sets the click callback for this item. |
| `Disabled` | `bool` | `false` | Gets or sets whether this item is disabled. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the item label content. |

**Basic Usage:**
```razor
<SplitButton OnClick="HandleSave" Variant="ButtonVariant.Default">
 Save
 <DropdownContent>
  <SplitButtonItem OnClick="HandleSaveAs">Save As...</SplitButtonItem>
  <SplitButtonItem OnClick="HandleSaveDraft">Save as Draft</SplitButtonItem>
  <SplitButtonSeparator />
  <SplitButtonItem OnClick="HandleDiscard">Discard</SplitButtonItem>
 </DropdownContent>
</SplitButton>

@code {
 private void HandleSave()      { /* primary action */ }
 private void HandleSaveAs()    { /* secondary */ }
 private void HandleSaveDraft() { /* secondary */ }
 private void HandleDiscard()   { /* secondary */ }
}
```

---

### CandlestickChart

**Package:** `NeoUI.Blazor.Charts`  
**Namespace:** `NeoUI.Blazor.Charts`

**Installation:**
```bash
dotnet add package NeoUI.Blazor.Charts --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor.Charts
```

**Description:**
OHLC candlestick chart for financial and time-series price data. Uses the declarative series pattern: wrap a Candlestick series inside a CandlestickChart, combined with XAxis and ChartTooltip primitives.

**Components & Parameters:**

#### `CandlestickChart<TData>` (inherits ChartBase)

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Data` | `IEnumerable<TData>` |  | Gets or sets the data source. |
| `EnableAnimation` | `bool` | `true` | Gets or sets whether to enable chart animation. |
| `AnimationDuration` | `int` | `1500` | Gets or sets the animation duration in milliseconds. |
| `Class` | `string?` |  | Gets or sets additional CSS classes. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content (series and primitive components). |

#### `Candlestick` (series)

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `DataKey` | `string` | (required) | Gets or sets the property name for open price values (used as the primary data key). |
| `OpenKey` | `string?` |  | Gets or sets the property name for open price values. |
| `CloseKey` | `string?` |  | Gets or sets the property name for close price values. |
| `HighKey` | `string?` |  | Gets or sets the property name for high price values. |
| `LowKey` | `string?` |  | Gets or sets the property name for low price values. |
| `RisingColor` | `string` | `"#22c55e"` | Gets or sets the color for rising (close > open) candles. |
| `FallingColor` | `string` | `"#ef4444"` | Gets or sets the color for falling (close < open) candles. |
| `BarWidth` | `string?` |  | Gets or sets the width of each candlestick bar (e.g. "60%"). |
| `Name` | `string?` |  | Gets or sets the display name shown in the legend/tooltip. |
| `ShowLabel` | `bool` | `false` | Gets or sets whether to show data labels. |

**Basic Usage:**
```razor
<ChartContainer>
 <CandlestickChart Data="@_ohlc" TData="OhlcPoint">
  <XAxis DataKey="date" />
  <ChartTooltip />
  <Candlestick DataKey="open"
               OpenKey="open" CloseKey="close"
               HighKey="high" LowKey="low"
               Name="Price" />
 </CandlestickChart>
</ChartContainer>

@code {
 record OhlcPoint(string date, double open, double high, double low, double close);

 private List<OhlcPoint> _ohlc =
 [
  new("Jan 1", 100, 115, 95,  112),
  new("Jan 2", 112, 118, 108, 105),
  new("Jan 3", 105, 110, 98,  107),
 ];
}
```

---

### FunnelChart

**Package:** `NeoUI.Blazor.Charts`  
**Namespace:** `NeoUI.Blazor.Charts`

**Installation:**
```bash
dotnet add package NeoUI.Blazor.Charts --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor.Charts
```

**Description:**
Pipeline and conversion funnel chart. Uses the declarative series pattern: wrap a Funnel series inside a FunnelChart. Supports sort order, horizontal alignment, and pyramid (ascending) mode.

**Components & Parameters:**

#### `FunnelChart<TData>` (inherits ChartBase)

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Data` | `IEnumerable<TData>` |  | Gets or sets the data source. |
| `EnableAnimation` | `bool` | `true` | Gets or sets whether to enable chart animation. |
| `AnimationDuration` | `int` | `1500` | Gets or sets the animation duration in milliseconds. |
| `Class` | `string?` |  | Gets or sets additional CSS classes. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content (series and primitive components). |

#### `Funnel` (series)

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `DataKey` | `string` | (required) | Gets or sets the property name for the value used to size each segment. |
| `NameKey` | `string?` |  | Gets or sets the property name for the category/stage name. |
| `Sort` | `FunnelSort` | `FunnelSort.Descending` | Gets or sets the sort order for funnel segments. |
| `Align` | `FunnelAlign` | `FunnelAlign.Center` | Gets or sets the horizontal alignment of funnel segments. |
| `Gap` | `int` | `2` | Gets or sets the gap between funnel segments in pixels. |
| `MinSize` | `string` | `"0%"` | Gets or sets the minimum segment size (percentage or pixel string). |
| `MaxSize` | `string` | `"100%"` | Gets or sets the maximum segment size. |
| `ShowLabels` | `bool` | `true` | Gets or sets whether to display labels on each segment. |
| `Colors` | `string[]?` |  | Custom color palette for segments. Cycles through the array when there are more segments than colors. `null` = auto CSS-variable palette (`--chart-1` … `--chart-5`). |
| `Fill` | `string?` |  | Gets or sets the fill color (supports CSS variables). |
| `Name` | `string?` |  | Gets or sets the display name shown in the legend/tooltip. |

**Enums:**

`FunnelSort`: `Descending`, `Ascending`, `None`

`FunnelAlign`: `Center`, `Left`, `Right`

**Basic Usage:**
```razor
<ChartContainer>
 <FunnelChart Data="@_pipeline" TData="Stage">
  <ChartTooltip />
  <Legend />
  <Funnel DataKey="count" NameKey="stage"
          Sort="FunnelSort.Descending"
          Align="FunnelAlign.Center" />
 </FunnelChart>
</ChartContainer>

@code {
 record Stage(string stage, int count);

 private List<Stage> _pipeline =
 [
  new("Leads",     1000),
  new("Prospects",  600),
  new("Qualified",  300),
  new("Proposals",  120),
  new("Won",         45),
 ];
}
```

---

### GaugeChart

**Package:** `NeoUI.Blazor.Charts`  
**Namespace:** `NeoUI.Blazor.Charts`

**Installation:**
```bash
dotnet add package NeoUI.Blazor.Charts --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor.Charts
```

**Description:**
Circular gauge and speedometer charts. Multiple Gauge series can be combined in a single GaugeChart for auto-tiled multi-gauge layouts.

**Components & Parameters:**

#### `GaugeChart<TData>` (inherits ChartBase)

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Data` | `IEnumerable<TData>` |  | Gets or sets the data source. |
| `EnableAnimation` | `bool` | `true` | Gets or sets whether to enable chart animation. |
| `AnimationDuration` | `int` | `1500` | Gets or sets the animation duration in milliseconds. |
| `Class` | `string?` |  | Gets or sets additional CSS classes. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content (Gauge series and ChartTooltip). |

#### `Gauge` (series)

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `DataKey` | `string` | (required) | Gets or sets the property name for the gauge value. |
| `Name` | `string?` |  | Gets or sets the display name shown as the gauge title. |
| `Min` | `double` | `0` | Gets or sets the minimum value on the gauge scale. |
| `Max` | `double` | `100` | Gets or sets the maximum value on the gauge scale. |
| `StartAngle` | `int` | `225` | Gets or sets the start angle in degrees. |
| `EndAngle` | `int` | `-45` | Gets or sets the end angle in degrees. |
| `SplitNumber` | `int` | `10` | Gets or sets the number of split segments on the gauge scale. |
| `ShowPointer` | `bool` | `true` | Gets or sets whether to show the pointer/needle. |
| `ShowProgress` | `bool` | `true` | Gets or sets whether to show the progress arc. |
| `ProgressWidth` | `int` | `10` | Gets or sets the progress arc width in pixels. |
| `ProgressRoundCap` | `bool` | `true` | Gets or sets whether the progress arc has rounded caps. |
| `ShowDetail` | `bool` | `true` | Gets or sets whether to show the center value detail. |
| `DetailFormatter` | `string` | `"{value}"` | Gets or sets the detail value formatter (ECharts format string). |
| `DetailFontSize` | `int` | `24` | Gets or sets the detail value font size in pixels. |
| `ShowTitle` | `bool` | `true` | Gets or sets whether to show the series title label below the gauge. |
| `Fill` | `string?` |  | Gets or sets the fill color (supports CSS variables). |

**Basic Usage:**
```razor
<ChartContainer>
 <GaugeChart Data="@_metrics" TData="Metric">
  <ChartTooltip />
  <Gauge DataKey="value" Name="CPU" Min="0" Max="100"
         ShowProgress ShowDetail />
 </GaugeChart>
</ChartContainer>

@code {
 record Metric(string name, double value);

 private List<Metric> _metrics =
 [
  new("CPU",    72),
  new("Memory", 45),
  new("Disk",   88),
 ];
}
```

---

### HeatmapChart

**Package:** `NeoUI.Blazor.Charts`  
**Namespace:** `NeoUI.Blazor.Charts`

**Installation:**
```bash
dotnet add package NeoUI.Blazor.Charts --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor.Charts
```

**Description:**
Intensity grid chart for activity calendars and correlation matrices. Use the VisualMap primitive to configure the colour scale and legend. XAxis and YAxis provide category labels.

**Components & Parameters:**

#### `HeatmapChart<TData>` (inherits ChartBase)

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Data` | `IEnumerable<TData>` |  | Gets or sets the data source. |
| `EnableAnimation` | `bool` | `true` | Gets or sets whether to enable chart animation. |
| `Class` | `string?` |  | Gets or sets additional CSS classes. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content (Heatmap series, VisualMap, and axes). |

#### `Heatmap` (series)

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `DataKey` | `string` | (required) | Gets or sets the property name for the cell intensity value. |
| `XKey` | `string?` |  | Gets or sets the property name for the X coordinate (column index or category). |
| `YKey` | `string?` |  | Gets or sets the property name for the Y coordinate (row index or category). |
| `LabelColor` | `string?` |  | Gets or sets the label text color for cell labels. |
| `LabelFontSize` | `int?` |  | Gets or sets the label font size in pixels. |
| `ShowLabel` | `bool` | `false` | Gets or sets whether to show data labels in each cell. |

#### `VisualMap` (primitive)

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Min` | `double` | `0` | Gets or sets the minimum data value for color scaling. |
| `Max` | `double` | `100` | Gets or sets the maximum data value for color scaling. |
| `InRange` | `string[]?` |  | Gets or sets the color range for the visual map. Defaults to a blue gradient. |
| `ShowLegend` | `bool` | `true` | Gets or sets whether the visual map legend control is shown. |
| `Orient` | `string` | `"horizontal"` | Gets or sets the orientation: "horizontal" or "vertical". |
| `Left` | `string` | `"center"` | Gets or sets the left position of the legend. |
| `Bottom` | `string` | `"0"` | Gets or sets the bottom position of the legend. |
| `Calculable` | `bool` | `true` | Gets or sets whether the user can drag to filter values. |

**Basic Usage:**
```razor
<ChartContainer>
 <HeatmapChart Data="@_activity" TData="Cell">
  <XAxis DataKey="hour" />
  <VisualMap Min="0" Max="10" InRange="@(new[]{ "#eff6ff", "#1d4ed8" })" />
  <Heatmap DataKey="count" XKey="hour" YKey="day" />
 </HeatmapChart>
</ChartContainer>

@code {
 record Cell(int hour, int day, int count);

 private List<Cell> _activity = GenerateActivity();

 private static List<Cell> GenerateActivity()
 {
  var rng = new Random(42);
  return [..Enumerable.Range(0, 7).SelectMany(d =>
   Enumerable.Range(0, 24).Select(h => new Cell(h, d, rng.Next(0, 11))))];
 }
}
```

---

### RadialBarChart

**Package:** `NeoUI.Blazor.Charts`  
**Namespace:** `NeoUI.Blazor.Charts`

**Installation:**
```bash
dotnet add package NeoUI.Blazor.Charts --version 3.6.3
```

**Import:**
```razor
@using NeoUI.Blazor.Charts
```

**Description:**
Radial bar charts for circular data comparisons. Each RadialBar series renders on a concentric ring, ideal for progress comparisons or multi-metric dashboards.

**Components & Parameters:**

#### `RadialBarChart<TData>` (inherits ChartBase)

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Data` | `IEnumerable<TData>` |  | Gets or sets the data source. |
| `StartAngle` | `int` | `90` | Gets or sets the start angle in degrees (90 = top). |
| `EndAngle` | `int` | `450` | Gets or sets the end angle in degrees (450 = full circle from top). |
| `Clockwise` | `bool` | `true` | Gets or sets whether the angle axis runs clockwise. |
| `RadiusMin` | `double?` | `0` | Gets or sets the minimum value for the radius axis. |
| `RadiusMax` | `double?` |  | Gets or sets the maximum value for the radius axis. |
| `EnableAnimation` | `bool` | `true` | Gets or sets whether to enable chart animation. |
| `Class` | `string?` |  | Gets or sets additional CSS classes. |
| `ChildContent` | `RenderFragment?` |  | Gets or sets the child content (RadialBar series, Legend, Tooltip). |

#### `RadialBar` (series)

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `DataKey` | `string` | (required) | Gets or sets the property name for the bar value. |
| `Name` | `string?` |  | Gets or sets the display name shown in the legend/tooltip. |
| `InnerRadius` | `string?` |  | Gets or sets the inner radius (e.g. "60%" or "60"). |
| `OuterRadius` | `string?` |  | Gets or sets the outer radius (e.g. "80%" or "80"). |
| `CornerRadius` | `int?` |  | Gets or sets the corner radius for rounded bars. |
| `StackId` | `string?` |  | Gets or sets the stack group ID for stacked radial bars. |
| `ShowBackground` | `bool` | `false` | Gets or sets whether to show a background track. |
| `BackgroundColor` | `string?` |  | Gets or sets the background track color. |
| `BackgroundOpacity` | `double?` | `0.1` | Gets or sets the background track opacity (0.0 to 1.0). |
| `Fill` | `string?` |  | Gets or sets the fill color (supports CSS variables like "var(--chart-1)"). |

**Basic Usage:**
```razor
<ChartContainer>
 <RadialBarChart Data="@_metrics" TData="Metric">
  <Legend />
  <ChartTooltip />
  <RadialBar DataKey="value" ShowBackground />
 </RadialBarChart>
</ChartContainer>

@code {
 record Metric(string name, int value);

 private List<Metric> _metrics =
 [
  new("Instagram", 85),
  new("Facebook",  72),
  new("Twitter",   60),
  new("LinkedIn",  45),
 ];
}
```

---

## Localization (`ILocalizer` / `DefaultLocalizer`) — *v3.6.4+*

**Package:** `NeoUI.Blazor`

All UI-chrome strings rendered by NeoUI components are resolved through a DI-registered `ILocalizer`. The library ships English defaults for every key. Explicit string parameters on components always take priority over the localizer.

### Registration

**Option A — startup-time override (most common)**
```csharp
// Program.cs
builder.Services.AddNeoUIComponents(localizer =>
{
    localizer.Set("Combobox.Placeholder", "Wählen Sie eine Option...");
    localizer.Set("DataTable.Loading", "Laden...");
    localizer.Set("DataTable.NoData", "Keine Daten");
    localizer.Set("Pagination.Previous", "Zurück");
    localizer.Set("Pagination.Next", "Weiter");
});
```

**Option B — `.resx` / `IStringLocalizer<T>` integration**
```csharp
// AppLocalizer.cs
public class AppLocalizer : DefaultLocalizer
{
    private readonly IStringLocalizer<AppLocalizer> _loc;
    public AppLocalizer(IStringLocalizer<AppLocalizer> loc) => _loc = loc;
    public override string this[string key] => _loc[key] ?? base[key];
}

// Program.cs
builder.Services.AddScoped<ILocalizer, AppLocalizer>();
```

`ILocalizer` is registered as **Scoped** — each Blazor Server circuit and WebAssembly session gets an independent instance.

### `ILocalizer` interface
| Method | Description |
|--------|-------------|
| `this[string key]` | Returns the string for the given key. Falls back to English default if not overridden. |
| `this[string key, params object[] args]` | Returns a formatted string using `string.Format`. |

### `DefaultLocalizer.Set(key, value)`
Sets a key at runtime. Thread-safe for startup-time calls (before any circuit is created).

### Components wired to `ILocalizer`
`Alert`, `Breadcrumb`, `Calendar`, `Carousel`, `Combobox`, `DataGrid`, `DataTable`, `DataView`, `DatePicker`, `DateRangePicker`, `Dialog`, `MultiSelect`, `NumericInput`, `Pagination` (all sub-components), `Rating`, `ResponsiveNav`, `Sheet`, `Sidebar`, `TagInput`.

### Selected key reference (70+ keys total — see `/components/localization` for full list)
| Key | English default | Component |
|-----|----------------|-----------|
| `Combobox.Placeholder` | `"Select..."` | `Combobox` |
| `Combobox.Empty` | `"No results found."` | `Combobox` |
| `DataTable.Loading` | `"Loading..."` | `DataTable` |
| `DataTable.NoData` | `"No data available."` | `DataTable` |
| `DataTable.SearchPlaceholder` | `"Search..."` | `DataTable` |
| `Pagination.Previous` | `"Previous"` | `PaginationPrevious` |
| `Pagination.Next` | `"Next"` | `PaginationNext` |
| `Pagination.First` | `"First"` | `PaginationFirst` |
| `Pagination.Last` | `"Last"` | `PaginationLast` |
| `Pagination.PageInfo` | `"{0}–{1} of {2}"` | `PaginationInfo` |
| `Dialog.Close` | `"Close"` | `Dialog` |
| `Sheet.Close` | `"Close"` | `Sheet` |
| `MultiSelect.Placeholder` | `"Select items..."` | `MultiSelect` |
| `DatePicker.Placeholder` | `"Pick a date"` | `DatePicker` |
| `Rating.AriaLabel` | `"Rating: {0} out of {1}"` | `Rating` |


---

## New in v3.8 -- SelectionIndicator

### SelectionIndicator

Spring-animated sliding indicator for active-item navigation. Drop inside any list-like container; it auto-detects the active item via a CSS selector and animates position/size changes.

| Parameter | Type    | Default              | Description                              |
|-----------|---------|----------------------|------------------------------------------|
| Selector  | string  | [data-state=active]  | CSS selector identifying the active item |
| Hover     | bool    | false                | Also track hovered item                  |
| Class     | string? | null                 | Additional CSS classes                   |

**CSS Variables:**
| Variable       | Description                        |
|----------------|------------------------------------|
| --si-duration  | Animation duration (e.g. 250ms)    |
| --si-easing    | Spring easing (e.g. spring(1,80,10,0)) |
| --si-height    | Indicator height override          |

**Usage patterns:**

```razor
@* With Tabs *@
<TabsList>
    <SelectionIndicator />
    <TabsTrigger Value="a">Alpha</TabsTrigger>
    <TabsTrigger Value="b">Beta</TabsTrigger>
</TabsList>

@* With ToggleGroup *@
<ToggleGroup @bind-Value="size">
    <SelectionIndicator />
    <ToggleGroupItem Value="sm">S</ToggleGroupItem>
    <ToggleGroupItem Value="md">M</ToggleGroupItem>
    <ToggleGroupItem Value="lg">L</ToggleGroupItem>
</ToggleGroup>

@* Custom markup (any element with data-state=active) *@
<div class="relative flex">
    <SelectionIndicator />
    @foreach (var item in items)
    {
        <button data-state="@(selected == item.Id ? "active" : "inactive")"
                @onclick="@(() => selected = item.Id)">
            @item.Name
        </button>
    }
</div>
```

---

## New in v3.8 -- Sortable System

### Sortable

Drag-and-drop sortable list container.

| Parameter            | Type                              | Default | Description                                          |
|----------------------|-----------------------------------|---------|------------------------------------------------------|
| Items                | IList<TItem>                      | --      | The list to sort (@bind-Items for two-way binding)   |
| ItemsChanged         | EventCallback<IList<TItem>>       | --      | Fires after reorder                                  |
| Group                | string?                           | null    | Share with other Sortables for cross-list DnD        |
| Handle               | bool                              | false   | Require SortableItemHandle to initiate drag          |
| Disabled             | bool                              | false   | Disable all dragging                                 |
| Animation            | int                               | 150     | Reorder animation duration (ms)                      |
| OnItemTransferredOut | EventCallback<SortableTransferEventArgs<TItem>> | -- | Fires when item leaves this list |
| OnItemTransferredIn  | EventCallback<SortableTransferEventArgs<TItem>> | -- | Fires when item enters this list |
| Class                | string?                           | null    | CSS classes                                          |
| ChildContent         | RenderFragment                    | --      | SortableItem children                                |

### SortableItem

Wrapper for each sortable row.

| Parameter    | Type                   | Default | Description               |
|--------------|------------------------|---------|---------------------------|
| Context      | TItem                  | --      | The data item (via @context) |
| Class        | string?                | null    | CSS classes               |
| ChildContent | RenderFragment<TItem>  | --      | Row content               |

### SortableContent

Inner content of a `SortableItem`. Exposes `data-[state=over]` attribute when an item is dragged over it.

### SortableOverlay

Optional ghost/overlay element shown during drag. Renders in a portal.

### SortableItemHandle

Drag handle sub-component. Only used when `Sortable Handle="true"`.

```razor
<Sortable @bind-Items="items" TItem="Task" Handle="true">
    <SortableItem Context="item">
        <SortableContent class="flex items-center gap-2">
            <SortableItemHandle><LucideIcon Name="grip-vertical" /></SortableItemHandle>
            @item.Title
        </SortableContent>
    </SortableItem>
</Sortable>
```

**Cross-list drag-and-drop example:**

```razor
<div class="grid grid-cols-2 gap-4">
    <Sortable @bind-Items="todo" TItem="Task" Group="kanban"
              OnItemTransferredOut="@(e => Console.WriteLine($"Out: {e.Item.Title}"))"
              OnItemTransferredIn="@(e => Console.WriteLine($"In: {e.Item.Title}"))">
        <SortableItem Context="t"><SortableContent>@t.Title</SortableContent></SortableItem>
    </Sortable>
    <Sortable @bind-Items="done" TItem="Task" Group="kanban"
              OnItemTransferredOut="@(e => Console.WriteLine($"Out: {e.Item.Title}"))"
              OnItemTransferredIn="@(e => Console.WriteLine($"In: {e.Item.Title}"))">
        <SortableItem Context="t"><SortableContent>@t.Title</SortableContent></SortableItem>
    </Sortable>
</div>
```

---

## New in v3.9 -- AppBar

Mobile top app bar.

| Parameter     | Type             | Default | Description                                           |
|---------------|------------------|---------|-------------------------------------------------------|
| Title         | string?          | null    | Title text                                            |
| TitleContent  | RenderFragment?  | null    | Custom title slot (overrides Title)                   |
| OnBack        | EventCallback    | --      | When set, renders a back chevron button               |
| Transparent   | bool             | false   | Removes background for overlay use                    |
| RightContent  | RenderFragment?  | null    | Content slot on the right side                        |
| Class         | string?          | null    | Additional CSS classes                                |

---

## New in v3.9 -- BottomNav + BottomNavItem

### BottomNav

Persistent mobile tab bar, pinned to the bottom of the screen by default.

| Parameter    | Type             | Default             | Description                             |
|--------------|------------------|---------------------|-----------------------------------------|
| ActiveTab    | string?          | null                | The currently active tab value          |
| ActiveTabChanged | EventCallback<string?> | --         | Two-way binding (@bind-ActiveTab)       |
| Fixed        | bool             | true                | Fixed positioning at bottom of viewport |
| AriaLabel    | string           | "Main navigation"   | Accessible label for the nav element    |
| ChildContent | RenderFragment   | --                  | BottomNavItem children                  |
| Class        | string?          | null                | Additional CSS classes                  |

### BottomNavItem

| Parameter     | Type          | Default | Description                                           |
|---------------|---------------|---------|-------------------------------------------------------|
| Value         | string        | --      | Required. Tab value matched against BottomNav.ActiveTab |
| Icon          | string?       | null    | Lucide icon name (kebab-case)                         |
| IconContent   | RenderFragment? | null  | Custom icon slot (overrides Icon)                     |
| Label         | string?       | null    | Tab label text                                        |
| BadgeCount    | int           | 0       | Badge count overlaid on icon                          |
| MaxBadgeCount | int           | 99      | Badge shows "99+" when Count exceeds this             |
| ShowZeroBadge | bool          | false   | Show badge when BadgeCount is 0                       |

---

## New in v3.9 -- NotificationBadge

Wraps any element and overlays a count badge in the top-right corner.

| Parameter   | Type                      | Default | Description                                  |
|-------------|---------------------------|---------|----------------------------------------------|
| Count       | int                       | 0       | Badge count                                  |
| ShowZero    | bool                      | false   | Show badge when Count is 0                   |
| Dot         | bool                      | false   | Dot indicator (no number)                    |
| Max         | int                       | 99      | Displays "99+" when Count exceeds this       |
| Variant     | NotificationBadgeVariant  | Destructive | Color: Destructive / Primary / Success   |
| ChildContent| RenderFragment            | --      | The element to wrap                          |
| Class       | string?                   | null    | Additional CSS classes                       |

`NotificationBadgeVariant` enum: `Destructive` | `Primary` | `Success`

---

## New in v3.9 -- QuantityStepper

Circular +/- quantity control.

| Parameter           | Type                 | Default       | Description                                      |
|---------------------|----------------------|---------------|--------------------------------------------------|
| Value               | int                  | 1             | Current value (@bind-Value)                      |
| Min                 | int                  | 1             | Minimum value                                    |
| Max                 | int                  | int.MaxValue  | Maximum value                                    |
| Step                | int                  | 1             | Increment/decrement step                         |
| Size                | QuantityStepperSize  | Default       | Small / Default / Large                          |
| DestructiveAtMin    | bool                 | false         | Replace minus with trash icon when Value == Min  |
| OnDestructiveAction | EventCallback        | --            | Fired when trash icon is clicked                 |
| Disabled            | bool                 | false         | Disables both buttons                            |

`QuantityStepperSize` enum: `Small` | `Default` | `Large`

---

## New in v3.9 -- SectionHeader

Title row with optional "view all" link and separator.

| Parameter     | Type             | Default | Description                                      |
|---------------|------------------|---------|--------------------------------------------------|
| Title         | string?          | null    | Title text                                       |
| TitleContent  | RenderFragment?  | null    | Custom title slot (overrides Title)              |
| OnViewAll     | EventCallback    | --      | When set, renders a chevron-right button         |
| ShowSeparator | bool             | false   | Renders a separator line below the header        |
| Class         | string?          | null    | Additional CSS classes                           |

---

## New in v3.9 -- ScreenTransition

Animated container for multi-screen navigation. Changing `Key` triggers the entrance animation.

| Parameter    | Type                      | Default | Description                              |
|--------------|---------------------------|---------|------------------------------------------|
| Key          | string                    | --      | Required. Changing this triggers animation |
| Direction    | ScreenTransitionDirection | None    | Animation direction                      |
| Class        | string?                   | null    | Additional CSS classes                   |
| ChildContent | RenderFragment            | --      | Screen content                           |

`ScreenTransitionDirection` enum:
| Value | Animation                 |
|-------|---------------------------|
| None  | No animation              |
| Tab   | Fade-in                   |
| Push  | Slide in from right       |
| Pop   | Slide in from left        |

---

## New in v3.9 -- BadgeIcon

Renders an icon inside a `Badge` chip. Use as a sub-component anywhere Badge is valid.

```razor
<BadgeIcon Variant="BadgeVariant.Destructive">
    <LucideIcon Name="x" Size="12" />
</BadgeIcon>
<BadgeIcon Variant="BadgeVariant.Secondary">
    <LucideIcon Name="check" Size="12" />
</BadgeIcon>
```

---

## New in v3.9 -- Drawer Enhancements (SnapPoints)

`DrawerContent` gains snap-point support for bottom-direction drawers:

| Parameter   | Type     | Default | Description                                                   |
|-------------|----------|---------|---------------------------------------------------------------|
| SnapPoints  | float[]? | null    | Array of snap positions as 0.0-1.0 fractions of viewport height |
| SnapIndex   | int      | 0       | Active snap point index (@bind-SnapIndex)                     |
| ShowHandle  | bool     | false   | Show drag handle bar at top of drawer                         |

```razor
<Drawer>
    <DrawerTrigger><Button>Open</Button></DrawerTrigger>
    <DrawerContent SnapPoints="@(new[]{0.4f, 0.75f, 1.0f})" @bind-SnapIndex="snapIdx" ShowHandle="true">
        @* content *@
    </DrawerContent>
</Drawer>
```

---

## New in v3.9 -- Select Presentation (BottomSheet)

`Select` gains a `Presentation` parameter to open options in a bottom Drawer on mobile.

| Parameter    | Type               | Default | Description                                    |
|--------------|--------------------|---------|------------------------------------------------|
| Presentation | SelectPresentation | Popover | Popover (default) or BottomSheet               |

`SelectPresentation` enum: `Popover` | `BottomSheet`

```razor
<Select @bind-Value="val" Presentation="SelectPresentation.BottomSheet">
    <SelectTrigger />
    <SelectContent>
        <SelectItem Value="a">Option A</SelectItem>
    </SelectContent>
</Select>
```

---

## New in v3.9 -- Separator LineStyle

| Parameter | Type           | Default | Description                        |
|-----------|----------------|---------|------------------------------------|
| LineStyle | SeparatorStyle | Solid   | Solid / Dashed / Dotted            |

`SeparatorStyle` enum: `Solid` | `Dashed` | `Dotted`

---

## New in v3.9 -- ToggleGroup Scrollable + Required

| Parameter  | Type | Default | Description                                              |
|------------|------|---------|----------------------------------------------------------|
| Scrollable | bool | false   | Enables horizontal scroll strip (overflow-x: auto)       |
| Required   | bool | false   | Prevents deselecting the currently active item           |

---

## New in v3.9 -- Carousel DotsPosition

| Parameter    | Type                  | Default | Description                    |
|--------------|-----------------------|---------|--------------------------------|
| DotsPosition | CarouselDotsPosition  | Bottom  | Bottom / Top / Left / Right    |

`CarouselDotsPosition` enum: `Bottom` | `Top` | `Left` | `Right`

---

## New in v4.0 -- AppProvider

Required outermost wrapper in `MainLayout.razor`. No parameters; wrap all content including portal hosts.

```razor
@* MainLayout.razor *@
<AppProvider>
    @Body
    <ToastViewport />
    <SpotlightCommandPalette />
    <DialogHost />
</AppProvider>
```

Does two things:
1. Initializes `IThemeService` and restores persisted theme dimensions from localStorage.
2. Broadcasts the active `StyleVariant` as a `CascadingValue<StyleVariant>` to all descendants.

Components outside `AppProvider` receive `StyleVariant.Default` permanently. StyleVariant class overrides use a 3-layer merge: base component classes → `StyleVariant.GetClasses("Component.Key")` → user `Class` prop (always wins via tailwind-merge).

**aria-disabled pattern:** Always use `@(Disabled ? "true" : "false")` for `aria-disabled` attributes, not `@Disabled` directly (Blazor serializes `bool` as "True"/"False" with capital T, which is invalid ARIA).

---

## Updated in v4.0 -- ThemeSwitcher

Full parameter reference for the `ThemeSwitcher` component:

| Parameter           | Type                | Default | Description                                            |
|---------------------|---------------------|---------|--------------------------------------------------------|
| ShowStyles          | bool                | false   | Adds a Styles tab with variant/radius/font/menu options|
| Strategy            | PositioningStrategy | Fixed   | Popover positioning strategy                           |
| ZIndex              | int                 | 60      | z-index of the switcher popover                        |
| TriggerClass        | string?             | null    | CSS classes applied to the trigger button              |
| PopoverContentClass | string?             | null    | CSS classes applied to the popover content panel       |
| Align               | PopoverAlign        | End     | Popover alignment (Start / Center / End)               |

With `ShowStyles="false"` (default): shows base color + primary color selectors.
With `ShowStyles="true"`: tabbed layout -- Colors tab (base + primary) + Styles tab (StyleVariant, RadiusPreset, FontPreset, MenuAccent, MenuColor).

Trigger button displays a two-tone swatch: current base color (fill) + current primary (border).

==================================================================
FILE: datagrid.txt
URL:  https://neoui.io/llms/datagrid.txt
==================================================================

# NeoUI -- DataGrid Quick Reference

The DataGrid is NeoUI's advanced data grid with sorting, filtering, pagination, inline editing,
server-side data loading, virtual scrolling, and full theming support.

## Installation & Import

```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

```razor
@using NeoUI.Blazor
```

## Service Registration

```csharp
// Program.cs -- basic (field-based rendering only)
builder.Services.AddNeoUIComponents();

// Full features (with template cell rendering)
builder.Services.AddNeoUIComponents();
builder.Services.AddScoped<IDataGridTemplateRenderer, DataGridTemplateRenderer>();
```

---

## Usage Patterns

### 1. Simple DataGrid

```razor
<DataGrid TItem="Product" Data="@products">
 <DataGridColumn Field="@nameof(Product.Name)" Header="Name" Sortable="true" />
 <DataGridColumn Field="@nameof(Product.Price)" Header="Price" Sortable="true" />
 <DataGridColumn Field="@nameof(Product.Stock)" Header="Stock" Filterable="true" />
</DataGrid>

@code {
 private List<Product> products = new();
 protected override async Task OnInitializedAsync() => products = await LoadProducts();
}
```

### 2. DataGrid with Custom Cell Templates

Requires `IDataGridTemplateRenderer` in DI.

```razor
<DataGrid TItem="Customer" Data="@customers">
 <DataGridColumn Field="@nameof(Customer.Name)" Header="Name">
  <CellTemplate Context="customer">
<div class="flex items-center gap-2">
 <Avatar><AvatarFallback>@customer.Name[0]</AvatarFallback></Avatar>
 <span class="font-medium">@customer.Name</span>
</div>
  </CellTemplate>
 </DataGridColumn>

 <DataGridColumn Field="@nameof(Customer.Status)" Header="Status">
  <CellTemplate Context="customer">
<Badge Variant="@(customer.IsActive ? BadgeVariant.Success : BadgeVariant.Secondary)">
 @customer.Status
</Badge>
  </CellTemplate>
 </DataGridColumn>
</DataGrid>
```

### 3. Server-Side DataGrid

```razor
<DataGrid TItem="Order"
 PagingMode="DataGridPagingMode.Server"
 PageSize="25"
 OnDataRequest="@LoadDataAsync">
 <DataGridColumn Field="@nameof(Order.Id)" Header="Order #" />
 <DataGridColumn Field="@nameof(Order.Customer)" Header="Customer" Sortable="true" />
 <DataGridColumn Field="@nameof(Order.Total)" Header="Total" Sortable="true" />
</DataGrid>

@code {
 private async Task<DataGridDataResponse<Order>> LoadDataAsync(DataGridDataRequest<Order> request)
 {
  var query = _context.Orders.AsQueryable();

  foreach (var sort in request.SortDescriptors)
  {
query = sort.Direction == DataGridSortDirection.Ascending
 ? query.OrderBy(o => EF.Property<object>(o, sort.Field))
 : query.OrderByDescending(o => EF.Property<object>(o, sort.Field));
  }

  var totalCount = await query.CountAsync();
  var items = await query.Skip(request.StartIndex).Take(request.Count).ToListAsync();

  return new DataGridDataResponse<Order> { Items = items, TotalCount = totalCount };
 }
}
```

### 4. Selection

```razor
<DataGrid TItem="Customer"
 Data="@customers"
 SelectionMode="DataGridSelectionMode.Multiple"
 OnSelectionChanged="@HandleSelectionChanged">
 <DataGridColumn Field="@nameof(Customer.Name)" Header="Name" />
 <DataGridColumn Field="@nameof(Customer.Email)" Header="Email" />
</DataGrid>

@code {
 private List<Customer> selectedCustomers = new();
 private void HandleSelectionChanged(IReadOnlyCollection<Customer> selection)
  => selectedCustomers = selection.ToList();
}
```
Selection modes: `None` | `Single` | `Multiple`

### 5. Inline Editing (Transactions)

```razor
<DataGrid TItem="Product"
 Data="@products"
 Editable="true"
 OnRowCommit="@SaveRow"
 OnRowCancel="@CancelRow">
 <DataGridColumn Field="@nameof(Product.Name)" Header="Name" Editable="true" />
 <DataGridColumn Field="@nameof(Product.Price)" Header="Price" Editable="true" />
</DataGrid>
```

### 6. State Persistence

```razor
<DataGrid TItem="Product"
 Data="@products"
 @bind-State="@gridState"
 OnStateChanged="@SaveState">
 <DataGridColumn Field="@nameof(Product.Name)" Header="Name" Sortable="true" />
</DataGrid>

@code {
 private DataGridState gridState = new();

 protected override async Task OnInitializedAsync()
  => gridState = await LocalStorage.GetItemAsync<DataGridState>("grid-state") ?? new();

 private async Task SaveState(DataGridState state)
  => await LocalStorage.SetItemAsync("grid-state", state);
}
```

### 7. Advanced: Frozen Columns, Row Grouping, Virtual Scrolling

```razor
<DataGrid TItem="Employee"
 Data="@employees"
 VirtualScrolling="true"
 RowGrouping="true"
 GroupField="@nameof(Employee.Department)">
 <DataGridColumn Field="@nameof(Employee.Name)" Header="Name" Frozen="true" />
 <DataGridColumn Field="@nameof(Employee.Department)" Header="Department" />
 <DataGridColumn Field="@nameof(Employee.Salary)" Header="Salary" />
</DataGrid>
```

---

## DataGridColumn Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `Field` | `string` | Property name to bind |
| `Header` | `string` | Column header text |
| `Sortable` | `bool` | Enable column sorting |
| `Filterable` | `bool` | Enable column filtering |
| `Editable` | `bool` | Enable inline editing |
| `Width` | `int?` | Column width in pixels |
| `MinWidth` | `int?` | Minimum width in pixels |
| `Frozen` | `bool` | Freeze column (left) |
| `FrozenRight` | `bool` | Freeze column (right) |
| `CellTemplate` | `RenderFragment<TItem>` | Custom cell renderer |
| `HeaderTemplate` | `RenderFragment` | Custom header renderer |
| `Class` | `string?` | CSS classes for cells |

---

## DataGrid Parameters (Key)

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Data` | `IEnumerable<TItem>?` | | Client-side data |
| `PagingMode` | `DataGridPagingMode` | `Client` | Client or Server paging |
| `PageSize` | `int` | `20` | Rows per page |
| `SelectionMode` | `DataGridSelectionMode` | `None` | Row selection mode |
| `Sortable` | `bool` | `true` | Global sort toggle |
| `Filterable` | `bool` | `false` | Global filter toggle |
| `Editable` | `bool` | `false` | Inline editing |
| `VirtualScrolling` | `bool` | `false` | Virtual rows |
| `Density` | `DataGridDensity` | `Compact` | Row density (`Compact`, `Medium`, `Spacious`). `Comfortable` is an `[Obsolete]` alias for `Medium`. |
| `Theme` | `DataGridTheme` | `Shadcn` | Visual theme |
| `VisualStyle` | `DataGridStyle` | `Default` | Striped/Bordered/etc. |
| `OnDataRequest` | `Func<DataGridDataRequest<TItem>, Task<DataGridDataResponse<TItem>>>` | | Server-side handler |
| `OnSelectionChanged` | `EventCallback<IReadOnlyCollection<TItem>>` | | Selection callback |
| `@bind-State` | `DataGridState` | | State binding |
| `OnStateChanged` | `EventCallback<DataGridState>` | | State changed callback |

---

## Theming

### High-Level Presets

```razor
<DataGrid TItem="Order" Data="@orders"
 Theme="DataGridTheme.Shadcn"
 Density="DataGridDensity.Compact"
 VisualStyle="DataGridStyle.Striped">
 ...
</DataGrid>
```

Themes: `Shadcn` | `Alpine` | `Balham` | `Material` | `Quartz`
Density: `Compact` | `Medium` | `Spacious` (`Comfortable` is `[Obsolete]` alias for `Medium`)
VisualStyle: `Default` | `Striped` | `Bordered` | `Minimal`

### Fine-Grained Parameters

```razor
<DataGrid TItem="Order" Data="@orders">
 <DataGridThemeParameters
  AccentColor="var(--primary)"
  RowHeight="44"
  FontSize="14"
  BorderRadius="6"
  HeaderBackgroundColor="var(--muted)" />
 <DataGridColumn ... />
</DataGrid>
```

Key theme parameters: `AccentColor`, `BackgroundColor`, `ForegroundColor`, `BorderColor`,
`HeaderBackgroundColor`, `RowHoverColor`, `OddRowBackgroundColor`, `SelectedRowBackgroundColor`,
`RowHeight`, `HeaderHeight`, `FontSize`, `FontFamily`, `HeaderFontWeight`, `Spacing`, `BorderRadius`

### CSS Override

```razor
<DataGrid TItem="Order" Data="@orders" Class="my-grid">...</DataGrid>

<style>
.my-grid { --ag-cell-horizontal-padding: 20px; }
</style>
```

---

## Sub-Pages (Demo Site)

| Path | Description |
|------|-------------|
| `/components/datagrid` | Overview |
| `/components/datagrid/basic` | Basic usage |
| `/components/datagrid/templating` | Custom cell templates |
| `/components/datagrid/selection` | Row selection |
| `/components/datagrid/transactions` | Inline editing |
| `/components/datagrid/sorting` | Sorting & filtering |
| `/components/datagrid/state` | State persistence |
| `/components/datagrid/server-side` | Server-side loading |
| `/components/datagrid/advanced` | Frozen columns, grouping, virtual scroll |
| `/components/datagrid/theming` | Custom themes |


==================================================================
FILE: primitives.txt
URL:  https://neoui.io/llms/primitives.txt
==================================================================

# NeoUI -- Primitives Reference

NeoUI.Blazor.Primitives provides 15 headless, unstyled components with full WCAG 2.1 AA
accessibility, keyboard navigation, and ARIA attributes. Use them to build a fully custom
design system without any opinionated styling.

## Installation

```bash
dotnet add package NeoUI.Blazor.Primitives --version 3.6.3
```

Note: Already included transitively when using `NeoUI.Blazor`.

## Import

```razor
@using NeoUI.Blazor.Primitives
@using NeoUI.Blazor.Primitives.Services
```

## Service Registration

```csharp
builder.Services.AddNeoUIPrimitives();
```

---

## Available Primitives

### Accordion (Inputs & Forms)
Headless collapsible content with keyboard navigation.
```razor
@using NeoUI.Blazor.Primitives.Accordion
<Accordion ...>...</Accordion>
```

### Checkbox (Inputs & Forms)
Unstyled checkbox with indeterminate state.
```razor
@using NeoUI.Blazor.Primitives.Checkbox
<Checkbox ...>...</Checkbox>
```

### Label (Inputs & Forms)
Accessible label with associated control support.
```razor
@using NeoUI.Blazor.Primitives.Label
<Label For="id">Label text</Label>
```

### RadioGroup (Inputs & Forms)
Headless radio group with keyboard navigation.
```razor
@using NeoUI.Blazor.Primitives.RadioGroup
<RadioGroup ...>...</RadioGroup>
```

### Select (Inputs & Forms)
Headless select with search and keyboard navigation.
```razor
@using NeoUI.Blazor.Primitives.Select
<Select ...>...</Select>
```

### Switch (Inputs & Forms)
Headless toggle switch with ARIA checked state.
```razor
@using NeoUI.Blazor.Primitives.Switch
<Switch ...>...</Switch>
```

### Table (Data Display)
Unstyled accessible data table with semantic markup.
```razor
@using NeoUI.Blazor.Primitives.Table
<Table ...>...</Table>
```

### Tabs (Navigation)
Headless tabs with keyboard navigation (arrow keys, Home, End).
```razor
@using NeoUI.Blazor.Primitives.Tabs
<Tabs ...>...</Tabs>
```

### Accordion (Layout)
Headless accordion with keyboard navigation.
```razor
@using NeoUI.Blazor.Primitives.Accordion
<Accordion ...>...</Accordion>
```

### Collapsible (Layout)
Unstyled collapsible content with trigger.
```razor
@using NeoUI.Blazor.Primitives.Collapsible
<Collapsible ...>...</Collapsible>
```

### Dialog (Overlays)
Headless modal dialog with focus trap, scroll lock, and ARIA.
```razor
@using NeoUI.Blazor.Primitives.Dialog
<Dialog ...>...</Dialog>
```

### DropdownMenu (Overlays)
Unstyled floating menu with keyboard navigation.
```razor
@using NeoUI.Blazor.Primitives.DropdownMenu
<DropdownMenu ...>...</DropdownMenu>
```

### HoverCard (Overlays)
Unstyled hover card with delay and pointer event handling.
```razor
@using NeoUI.Blazor.Primitives.HoverCard
<HoverCard ...>...</HoverCard>
```

### Popover (Overlays)
Unstyled floating panel with positioning.
```razor
@using NeoUI.Blazor.Primitives.Popover
<Popover ...>...</Popover>
```

### Sheet (Overlays)
Unstyled side panel with animation support.
```razor
@using NeoUI.Blazor.Primitives.Sheet
<Sheet ...>...</Sheet>
```

### Tooltip (Overlays)
Unstyled tooltip with delay, positioning, and keyboard focus support.
```razor
@using NeoUI.Blazor.Primitives.Tooltip
<Tooltip ...>...</Tooltip>
```

---

## Building on Primitives

Example: custom-styled Dialog using the headless primitive:

```razor
@using NeoUI.Blazor.Primitives.Dialog

<Dialog @bind-Open="isOpen">
 <DialogTrigger>
  <button class="my-custom-button">Open</button>
 </DialogTrigger>
 <DialogPortal>
  <DialogOverlay class="my-overlay" />
  <DialogContent class="my-dialog-content">
<h2>My Custom Dialog</h2>
<p>All behavior, focus management, and ARIA handled automatically.</p>
<DialogClose>
 <button class="my-close-button">×</button>
</DialogClose>
  </DialogContent>
 </DialogPortal>
</Dialog>
```

## Services

### IKeyboardShortcutService
Register global keyboard shortcuts.
```csharp
@inject IKeyboardShortcutService KeyboardShortcuts

await KeyboardShortcuts.RegisterAsync("Ctrl+K", OpenPalette);
await KeyboardShortcuts.UnregisterAsync("Ctrl+K");
```


==================================================================
FILE: patterns.txt
URL:  https://neoui.io/llms/patterns.txt
==================================================================

# NeoUI -- Usage Patterns & Best Practices

Practical patterns for the most common scenarios when building Blazor apps with NeoUI.

---

## Forms

### Basic Validated Form

```razor
@using System.ComponentModel.DataAnnotations

<EditForm Model="@_model" OnValidSubmit="HandleSubmit">
 <DataAnnotationsValidator />

 <FieldGroup>
  <Field>
<FieldLabel For="email">Email</FieldLabel>
<FieldContent>
 <Input Id="email" Type="InputType.Email"
  @bind-Value="_model.Email"
  Placeholder="you@example.com" />
</FieldContent>
<ValidationMessage For="() => _model.Email" />
  </Field>

  <Field>
<FieldLabel For="password">Password</FieldLabel>
<FieldContent>
 <Input Id="password" Type="InputType.Password"
  @bind-Value="_model.Password" />
</FieldContent>
<ValidationMessage For="() => _model.Password" />
  </Field>
 </FieldGroup>

 <Button Type="ButtonType.Submit" Class="mt-4">Sign in</Button>
</EditForm>

@code {
 private LoginModel _model = new();

 private async Task HandleSubmit()
 {
  // validated, safe to submit
 }

 private class LoginModel
 {
  [Required, EmailAddress]
  public string Email { get; set; } = "";

  [Required, MinLength(8)]
  public string Password { get; set; } = "";
 }
}
```

### Select / Combobox Binding

```razor
@* Native select -- simple, always works *@
<Select @bind-Value="_country" Placeholder="Select country">
 <SelectTrigger />
 <SelectContent>
  <SelectItem Value="us">United States</SelectItem>
  <SelectItem Value="uk">United Kingdom</SelectItem>
  <SelectItem Value="ca">Canada</SelectItem>
 </SelectContent>
</Select>

@* Combobox -- searchable *@
<Combobox @bind-Value="_country" Placeholder="Search countries..."
 SearchPlaceholder="Type to search...">
 @foreach (var country in _countries)
 {
  <ComboboxItem Value="@country.Code">@country.Name</ComboboxItem>
 }
</Combobox>
```

### Multi-Select

```razor
<MultiSelect @bind-Values="_tags" Placeholder="Select tags..." MaxDisplayTags="3">
 <MultiSelectItem Value="react">React</MultiSelectItem>
 <MultiSelectItem Value="vue">Vue</MultiSelectItem>
 <MultiSelectItem Value="angular">Angular</MultiSelectItem>
 <MultiSelectItem Value="svelte">Svelte</MultiSelectItem>
</MultiSelect>

@code {
 private IEnumerable<string>? _tags;
}
```

### Date & Time Pickers

```razor
@* Date only *@
<DatePicker @bind-SelectedDate="_date" Placeholder="Pick a date" />

@* Date range *@
<DateRangePicker @bind-StartDate="_start" @bind-EndDate="_end" />

@* Time picker *@
<TimePicker @bind-SelectedTime="_time" Use24HourFormat="false" />

@code {
 private DateOnly? _date;
 private DateOnly? _start;
 private DateOnly? _end;
 private TimeOnly? _time;
}
```

### File Upload

```razor
<FileUpload Accept=".pdf,.docx"
MaxFileSizeMb="10"
Multiple="true"
OnFilesChanged="HandleFiles">
 <UploadPrompt>
  <p>Drag files here or <span class="text-primary">browse</span></p>
  <p class="text-xs text-muted-foreground mt-1">PDF, DOCX up to 10 MB</p>
 </UploadPrompt>
</FileUpload>
```

---

## Data Binding Patterns

### Two-Way Binding (@bind-Value)

```razor
@* Standard two-way binding *@
<Input @bind-Value="_name" />
<Switch @bind-Checked="_enabled" />
<Slider @bind-Value="_volume" Min="0" Max="100" />
<Checkbox @bind-Checked="_agreed" />
<RadioGroup @bind-Value="_size">
 <RadioGroupItem Value="sm">Small</RadioGroupItem>
 <RadioGroupItem Value="md">Medium</RadioGroupItem>
 <RadioGroupItem Value="lg">Large</RadioGroupItem>
</RadioGroup>

@code {
 private string _name = "";
 private bool _enabled = true;
 private double _volume = 50;
 private bool _agreed = false;
 private string _size = "md";
}
```

### Controlled Open/Close State

```razor
@* Controlled dialog *@
<Dialog @bind-Open="_open">
 <DialogTrigger AsChild>
  <Button>Open</Button>
 </DialogTrigger>
 <DialogContent>
  <DialogHeader><DialogTitle>Edit</DialogTitle></DialogHeader>
  <DialogFooter>
<Button Variant="ButtonVariant.Outline" OnClick="() => _open = false">Cancel</Button>
<Button OnClick="Save">Save</Button>
  </DialogFooter>
 </DialogContent>
</Dialog>

@code {
 private bool _open = false;
 private void Save() { /* ... */ _open = false; }
}
```

### Tab State

```razor
<Tabs @bind-Value="_activeTab" DefaultValue="overview">
 <TabsList>
  <TabsTrigger Value="overview">Overview</TabsTrigger>
  <TabsTrigger Value="details">Details</TabsTrigger>
  <TabsTrigger Value="history">History</TabsTrigger>
 </TabsList>
 <TabsContent Value="overview"><OverviewPanel /></TabsContent>
 <TabsContent Value="details"><DetailsPanel /></TabsContent>
 <TabsContent Value="history"><HistoryPanel /></TabsContent>
</Tabs>

@code {
 private string? _activeTab;
 // Switch programmatically: _activeTab = "details";
}
```

---

## Toasts / Notifications

### Service Injection

```razor
@inject IToastService Toast

<Button OnClick="ShowSuccess">Save</Button>
<Button OnClick="ShowError" Variant="ButtonVariant.Destructive">Delete</Button>

@code {
 private void ShowSuccess() =>
  Toast.Show("Changes saved", "Your changes have been saved successfully.", ToastVariant.Default);

 private void ShowError() =>
  Toast.Show("Error", "Could not delete item. Please try again.", ToastVariant.Destructive);
}
```

### Setup (once in MainLayout.razor or App.razor)

```razor
<ToastProvider Position="ToastPosition.BottomRight" MaxToasts="5" />
```

---

## Dialogs -- Programmatic (DialogService)

```razor
@inject IDialogService DialogService

<Button OnClick="ConfirmDelete">Delete</Button>

@code {
 private async Task ConfirmDelete()
 {
  var result = await DialogService.ShowAsync<ConfirmDialog>(
new DialogParameters { ["ItemName"] = "Document" });

  if (result.Confirmed)
await DeleteItemAsync();
 }
}
```

```razor
@* ConfirmDialog.razor *@
<DialogContent>
 <DialogHeader>
  <DialogTitle>Delete @ItemName?</DialogTitle>
  <DialogDescription>This action cannot be undone.</DialogDescription>
 </DialogHeader>
 <DialogFooter>
  <DialogClose AsChild>
<Button Variant="ButtonVariant.Outline">Cancel</Button>
  </DialogClose>
  <Button Variant="ButtonVariant.Destructive" OnClick="Confirm">Delete</Button>
 </DialogFooter>
</DialogContent>

@code {
 [Parameter] public string ItemName { get; set; } = "";
 [CascadingParameter] public DialogInstance Dialog { get; set; } = null!;
 private async Task Confirm() => await Dialog.CloseAsync(new DialogResult { Confirmed = true });
}
```

---

## Theming

### Runtime Theme Switching

```razor
@inject ThemeService ThemeService

<ThemeSwitcher />@* Built-in UI -- picks base + accent *@
<DarkModeToggle />  @* Built-in dark mode toggle *@

@* Programmatic *@
<Button OnClick="() => ThemeService.SetTheme(ThemeBase.Zinc, ThemeAccent.Violet)">
 Apply Zinc + Violet
</Button>
```

### CSS Variable Overrides

```css
/* In your app.css -- override any variable per-component or globally */
:root {
 --radius: 0.25rem; /* sharper corners */
 --primary: oklch(0.6 0.2 250); /* custom brand color */
}

/* Scoped override */
.my-card {
 --card: oklch(0.98 0 0);
}
```

### Conditional Dark Mode Classes

```razor
@* Tailwind dark: variant *@
<div class="bg-white dark:bg-zinc-900 text-zinc-900 dark:text-zinc-100">
 Content
</div>
```

---

## Sidebar Layout Pattern

```razor
@* MainLayout.razor *@
<SidebarProvider DefaultOpen="true" StaticRendering="true">
 <Sidebar AutoDetectActive="true">
  <SidebarHeader>
<SidebarHeaderContent>
 <LucideIcon Name="layers" Size="20" />
 <SidebarHeaderInfo>
  <span class="font-semibold">My App</span>
 </SidebarHeaderInfo>
</SidebarHeaderContent>
  </SidebarHeader>

  <SidebarContent>
<SidebarGroup>
 <SidebarGroupLabel>Main</SidebarGroupLabel>
 <SidebarGroupContent>
  <SidebarMenu>
<SidebarMenuItem>
 <SidebarMenuButton Href="/">
  <LucideIcon Name="home" Size="16" />
  Home
 </SidebarMenuButton>
</SidebarMenuItem>
<SidebarMenuItem>
 <SidebarMenuButton Href="/settings">
  <LucideIcon Name="settings" Size="16" />
  Settings
 </SidebarMenuButton>
</SidebarMenuItem>
  </SidebarMenu>
 </SidebarGroupContent>
</SidebarGroup>
  </SidebarContent>

  <SidebarFooter>
<SidebarMenuItem>
 <SidebarMenuButton>
  <LucideIcon Name="user" Size="16" />
  John Doe
 </SidebarMenuButton>
</SidebarMenuItem>
  </SidebarFooter>
 </Sidebar>

 <SidebarInset>
  <header class="flex h-16 items-center gap-2 border-b px-4">
<SidebarTrigger />
<Separator Orientation="SeparatorOrientation.Vertical" Class="h-4" />
<Breadcrumb>...</Breadcrumb>
  </header>
  <main class="p-6">@Body</main>
 </SidebarInset>
</SidebarProvider>
```

---

## Data Grid Patterns

### Basic Grid

```razor
<DataGrid TItem="Order" Items="@_orders" Height="500px">
 <DataGridColumn Field="Id" Header="#" Width="80px" />
 <DataGridColumn Field="Customer" Header="Customer" Sortable="true" Filterable="true" />
 <DataGridColumn Field="Amount" Header="Amount" DataFormatString="C" />
 <DataGridColumn Field="Status" Header="Status">
  <CellTemplate Context="order">
   <Badge Variant="@(order.Status == "Paid" ? BadgeVariant.Default : BadgeVariant.Secondary)">
    @order.Status
   </Badge>
  </CellTemplate>
 </DataGridColumn>
</DataGrid>
```

### Server-Side Grid

```razor
<DataGrid TItem="Product"
 RowModelType="DataGridRowModelType.BlazorServerSide"
 OnServerDataRequest="FetchPage"
 Height="600px">
 <DataGridColumn Field="Name" Header="Name" Sortable="true" Filterable="true" />
 <DataGridColumn Field="Price" Header="Price" DataFormatString="C" Sortable="true" />
</DataGrid>

@code {
 private async Task<DataGridDataResponse<Product>> FetchPage(DataGridDataRequest<Product> req)
 {
  var (items, total) = await _api.GetProductsAsync(
   page: req.StartRow / req.PageSize,
   pageSize: req.PageSize,
   sortField: req.SortModel.FirstOrDefault()?.ColId,
   sortDir: req.SortModel.FirstOrDefault()?.Sort,
   filter: req.FilterModel.GetValueOrDefault("Name")?.Filter);

  return new DataGridDataResponse<Product> { Items = items, TotalCount = total };
 }
}
```

---

## Render Mode Gotchas

### Interactive Components Need Interactive Render Mode

Tabs, NavigationMenu, Combobox, DataGrid -- all require interactive rendering.

```razor
@* App.razor -- set global interactive render mode *@
<Routes @rendermode="@InteractiveAuto" />
```

```razor
@* Or per-component in a Static SSR page *@
<Tabs @rendermode="@InteractiveServer" DefaultValue="tab1">
 ...
</Tabs>
```

### InteractiveAuto Requires Registration in Both Projects

```csharp
// Server project Program.cs
builder.Services.AddRazorComponents()
 .AddInteractiveServerComponents()
 .AddInteractiveWebAssemblyComponents();

// Both Server AND WASM Client Program.cs
builder.Services.AddNeoUIPrimitives();
builder.Services.AddNeoUIComponents();
builder.Services.AddScoped<IPortalService, PortalService>();
```

### SidebarProvider with Static Rendering

```razor
@* Set StaticRendering="true" when parent renders statically *@
<SidebarProvider StaticRendering="true">
 ...
</SidebarProvider>
```

---

## Keyboard Shortcuts

```razor
@inject IKeyboardShortcutService KeyboardShortcuts

@code {
 protected override async Task OnAfterRenderAsync(bool firstRender)
 {
  if (firstRender)
  {
await KeyboardShortcuts.RegisterAsync("Ctrl+K", OpenCommandPalette);
await KeyboardShortcuts.RegisterAsync("Escape", CloseAll);
  }
 }

 private void OpenCommandPalette() { /* ... */ }
 private void CloseAll() { /* ... */ }
}
```

---

## Loading States Pattern

```razor
@if (_loading)
{
 <div class="space-y-3">
  <Skeleton Class="h-8 w-48" />
  <Skeleton Class="h-4 w-full" />
  <Skeleton Class="h-4 w-3/4" />
  <Skeleton Class="h-32 w-full" />
 </div>
}
else if (_error is not null)
{
 <Empty>
  <EmptyIcon><LucideIcon Name="alert-circle" Size="48" Class="text-destructive" /></EmptyIcon>
  <EmptyTitle>Failed to load</EmptyTitle>
  <EmptyDescription>@_error</EmptyDescription>
  <EmptyActions><Button OnClick="Reload">Retry</Button></EmptyActions>
 </Empty>
}
else if (!_items.Any())
{
 <Empty>
  <EmptyIcon><LucideIcon Name="inbox" Size="48" /></EmptyIcon>
  <EmptyTitle>No items yet</EmptyTitle>
  <EmptyDescription>Create your first item to get started.</EmptyDescription>
  <EmptyActions><Button>Create Item</Button></EmptyActions>
 </Empty>
}
else
{
 @foreach (var item in _items)
 {
  <ItemCard @key="item.Id" Item="item" />
 }
}
```


==================================================================
FILE: icons.txt
URL:  https://neoui.io/llms/icons.txt
==================================================================

# NeoUI -- Icon Libraries

NeoUI ships three icon libraries, all included transitively with `NeoUI.Blazor`.
No additional install step is required.

## Packages & Counts

| Package | Icons | Style | Import |
|---------|-------|-------|--------|
| NeoUI.Icons.Lucide | 1,640 | Stroke (outline) | `@using NeoUI.Icons.Lucide` |
| NeoUI.Icons.Heroicons | 1,288 | 4 variants | `@using NeoUI.Icons.Heroicons` |
| NeoUI.Icons.Feather | 286 | Thin stroke | `@using NeoUI.Icons.Feather` |

---

## Lucide Icons (1,640 icons)

**Recommended default.** Clean, consistent stroke-weight icons covering almost every UI need.

### Component

```razor
<LucideIcon Name="circle-check" Size="20" Class="text-green-500" StrokeWidth="1.5" />
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Name` | `string` | required | Kebab-case icon name (e.g. `"chevron-down"`, `"loader-circle"`) |
| `Size` | `int` | `24` | Width and height in pixels |
| `Class` | `string?` | `null` | Additional CSS classes |
| `StrokeWidth` | `double` | `2` | SVG stroke-width attribute |
| `Color` | `string?` | `null` | Inline color override (prefer Tailwind classes) |
| `AriaLabel` | `string?` | `null` | Accessible label; set for meaningful icons |
| `AriaHidden` | `bool` | `true` | Set false for semantic icons |

### Icon Categories

**Actions:** check, x, plus, minus, edit-2, trash-2, copy, download, upload, share, refresh-cw, search, filter, sort-asc, sort-desc, more-horizontal, more-vertical

**Arrows & Navigation:** arrow-left, arrow-right, arrow-up, arrow-down, chevron-left, chevron-right, chevron-up, chevron-down, chevrons-left, chevrons-right, move, external-link, corner-up-left

**Files & Data:** file, file-text, folder, folder-open, database, table-2, server, cloud, cloud-upload, cloud-download, hard-drive, archive, package

**Communication:** mail, message-circle, message-square, phone, video, bell, bell-off, rss, send, inbox, at-sign

**UI & Layout:** layout, layout-dashboard, panel-left, panel-right, sidebar, menu, grid, list, columns, rows, maximize, minimize, expand, shrink, align-left, align-center, align-right

**Media:** play, pause, stop-circle, skip-back, skip-forward, volume-2, volume-x, image, camera, mic, headphones, music

**Users & Security:** user, users, user-plus, user-minus, lock, unlock, shield, shield-check, key, eye, eye-off, fingerprint

**Status & Feedback:** check, check-circle, circle-check, alert-circle, alert-triangle, info, help-circle, loader, loader-circle, zap, star, heart, thumbs-up, thumbs-down

**Time & Calendar:** calendar, calendar-days, clock, timer, history, hourglass

**Charts & Analytics:** bar-chart, bar-chart-2, bar-chart-4, line-chart, pie-chart, area-chart, activity, trending-up, trending-down

**Settings & Tools:** settings, settings-2, sliders-horizontal, tool, wrench, terminal, code, code-2, brackets, bug

**E-Commerce:** shopping-cart, shopping-bag, credit-card, tag, tags, percent, dollar-sign, receipt, package

**Misc:** globe, map-pin, home, building, bookmark, link, link-2, paperclip, flag, award, gift, lightbulb, moon, sun, contrast

### Usage Examples

```razor
@* Button with icon *@
<Button>
 <LucideIcon Name="download" Size="16" />
 Download
</Button>

@* Icon-only button *@
<Button Size="ButtonSize.Icon" Variant="ButtonVariant.Ghost" AriaLabel="Settings">
 <LucideIcon Name="settings" Size="18" />
</Button>

@* Status indicator *@
<div class="flex items-center gap-2">
 <LucideIcon Name="circle-check" Size="16" Class="text-green-500" />
 <span>Saved successfully</span>
</div>

@* Sidebar menu item *@
<SidebarMenuButton Href="/dashboard">
 <LucideIcon Name="layout-dashboard" Size="16" />
 Dashboard
</SidebarMenuButton>

@* Spinner alternative *@
<LucideIcon Name="loader-circle" Size="20" Class="animate-spin text-primary" />
```

---

## Heroicons (1,288 icons)

Icons from Tailwind's design team, available in four visual weight variants.

### Component

```razor
<HeroIcon Name="check-circle" Variant="HeroIconVariant.Solid" Size="20" Class="text-green-500" />
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Name` | `string` | required | Kebab-case icon name |
| `Variant` | `HeroIconVariant` | `Outline` | `Outline` \| `Solid` \| `Mini` \| `Micro` |
| `Size` | `int` | `24` | Width and height in pixels (Mini defaults to 20, Micro to 16) |
| `Class` | `string?` | `null` | CSS classes |
| `AriaLabel` | `string?` | `null` | Accessible label |
| `AriaHidden` | `bool` | `true` | Decorative by default |

### Variants

- **Outline** (24px default) -- 1.5px stroke, for primary UI
- **Solid** (24px default) -- Filled, for emphasis and active states
- **Mini** (20px default) -- Compact filled icons
- **Micro** (16px default) -- Smallest, inline-text scale

```razor
<HeroIcon Name="bell" Variant="HeroIconVariant.Outline" />
<HeroIcon Name="bell" Variant="HeroIconVariant.Solid" />
<HeroIcon Name="bell" Variant="HeroIconVariant.Mini" />
<HeroIcon Name="bell" Variant="HeroIconVariant.Micro" />
```

---

## Feather Icons (286 icons)

Minimalist, thin-stroke icon set -- great for clean, modern interfaces.

### Component

```razor
<FeatherIcon Name="check-circle" Size="20" Class="text-green-500" />
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Name` | `string` | required | Kebab-case icon name |
| `Size` | `int` | `24` | Width and height in pixels |
| `Class` | `string?` | `null` | CSS classes |
| `StrokeWidth` | `double` | `2` | SVG stroke-width |
| `AriaLabel` | `string?` | `null` | Accessible label |

---

## Choosing an Icon Library

| Scenario | Recommendation |
|----------|---------------|
| General app UI | **Lucide** -- largest catalog, best coverage |
| Tailwind CSS projects | **Heroicons** -- designed to complement Tailwind |
| Minimal/editorial design | **Feather** -- clean, thin strokes |
| Mixed | Use Lucide as default; mix Heroicons for specific icons |

## Accessibility

```razor
@* Decorative icon -- hidden from screen readers (default) *@
<LucideIcon Name="star" Size="16" />

@* Meaningful icon with label *@
<LucideIcon Name="warning" Size="16" AriaLabel="Warning" AriaHidden="false" />

@* Icon inside labeled button -- icon is decorative *@
<Button AriaLabel="Delete item">
 <LucideIcon Name="trash-2" Size="16" />
</Button>
```

## Finding Icons

- Lucide: https://lucide.dev/icons/ -- search by keyword, browse by category
- Heroicons: https://heroicons.com -- search and copy name
- Feather: https://feathericons.com -- browse full catalog

## Custom SVG Icons

```razor
@* Inline SVG when a named icon isn't available *@
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24"
  fill="none" stroke="currentColor" stroke-width="2"
  stroke-linecap="round" stroke-linejoin="round">
 <path d="M12 2L2 7l10 5 10-5-10-5z" />
 <path d="M2 17l10 5 10-5M2 12l10 5 10-5" />
</svg>
```


==================================================================
FILE: blocks.txt
URL:  https://neoui.io/llms/blocks.txt
==================================================================

# NeoUI -- Blocks

> **Status: Available — Foundation Released**
> Blocks are built on top of the existing NeoUI component library. The initial set of
> 6 blocks is live at `/blocks`. More blocks are added continuously.

---

## What Are Blocks?

Blocks are complete, production-ready UI sections composed from NeoUI components.
Each block is:
- **Self-contained** -- full Razor markup with `@code`, ready to drop in
- **Customizable** -- uses CSS variables and Tailwind so theming is automatic
- **Copy-paste ready** -- no wiring required beyond adding your data

Unlike individual components, blocks solve real layout problems (a full dashboard header,
an auth form, a product card grid) rather than providing a single interactive element.

---

## Block Registry Architecture

Blocks are registered in `BlockRegistry.cs` (mirrors `ComponentRegistry.cs`):

```csharp
// BlockRegistryEntry record -- metadata for each block
public sealed record BlockRegistryEntry(
    string Slug,             // URL slug, e.g. "dashboard-01"
    string Title,            // Display name
    string Description,      // One-line description
    string Icon,             // Lucide icon name
    BlockCategoryInfo Category,
    Type ComponentType,      // The actual Razor component type (for DynamicComponent)
    IReadOnlyList<string> NeoUiComponents,  // Component pills shown in the card
    bool Featured = false,
    bool IsNew = false,
    int PreviewHeight = 600); // Ideal height for the live preview

// BlockCategoryInfo record
public sealed record BlockCategoryInfo(string Slug, string DisplayName, string Icon);
```

All blocks are registered in `BlockRegistry.BuildAll()`:

```csharp
// Example entry
new(
    Slug:            "auth-01",
    Title:           "Sign In Form",
    Description:     "Email and password sign-in card with remember me checkbox.",
    Icon:            "lock",
    Category:        BlockCategories.Authentication,
    ComponentType:   typeof(AuthSignIn01),
    NeoUiComponents: ["Card", "Input", "Checkbox", "Button", "Label"],
    Featured:        true,
    IsNew:           true,
    PreviewHeight:   480)
```

---

## Block Categories

| Slug | Display Name |
|------|-------------|
| `dashboard` | Dashboard |
| `auth` | Authentication |
| `marketing` | Marketing |
| `forms` | Forms |
| `navigation` | Navigation |
| `ecommerce` | E-Commerce |
| `settings` | Settings |
| `data-tables` | Data & Tables |

---

## Available Blocks

### Dashboard

| Slug | Title | Description |
|------|-------|-------------|
| `dashboard-01` | Analytics Dashboard | KPI cards row with icons, values, and delta indicators |
| `dashboard-02` | Dashboard Shell | Full sidebar and main content area shell with header and navigation |

### Authentication

| Slug | Title | Description |
|------|-------|-------------|
| `auth-01` | Sign In Form | Email and password sign-in card with remember me checkbox |
| `auth-02` | Sign Up Form | Registration form with name, email, password and terms acceptance |

### Marketing

| Slug | Title | Description |
|------|-------|-------------|
| `hero-01` | Centered Hero | Full-width centered hero with headline, subheadline, and CTA buttons |
| `feature-01` | Feature Grid | 3-column feature cards with icons, titles, and descriptions |

---

## Block URL Pattern

- **Catalogue**: `/blocks` -- category filter pills + CSS-scaled live preview cards
- **Detail**: `/blocks/{slug}` -- full-size live preview with viewport switcher (Desktop / Tablet / Mobile)

---

## File Structure

```
NeoUI.Web.Shared/
├── BlockRegistry.cs                 -- central registry (mirroring ComponentRegistry.cs)
├── Components/Blocks/
│   └── BlockCard.razor              -- catalogue thumbnail card with CSS-scaled DynamicComponent
└── Pages/Blocks/
    ├── Index.razor                  -- /blocks catalogue page
    ├── BlockDetail.razor            -- /blocks/{slug} detail page
    ├── Dashboard/
    │   ├── DashboardStats01.razor
    │   └── DashboardShell01.razor
    ├── Auth/
    │   ├── AuthSignIn01.razor
    │   └── AuthSignUp01.razor
    └── Marketing/
        ├── HeroCentered01.razor
        └── FeatureGrid01.razor
```

---

## Adding a New Block

1. Create `Pages/Blocks/{Category}/MyBlock01.razor` with `@namespace NeoUI.Web.Shared.Pages.Blocks.{Category}`
2. Add an entry to `BlockRegistry.BuildAll()` in `BlockRegistry.cs`
3. The block automatically appears on `/blocks` and gets its own `/blocks/{slug}` detail page



==================================================================
FILE: changelog.txt
URL:  https://neoui.io/llms/changelog.txt
==================================================================

## Version 4.0.0 -- Theme v2: Full Dimension Expansion + AppProvider

### Breaking Changes
- **AppProvider** is now required in `MainLayout.razor` wrapping all content including portal hosts. Without it, ThemeService will not initialize persisted theme, and StyleVariant will not cascade to components.

### New Features
- **AppProvider** -- required outermost wrapper in MainLayout. Initializes ThemeService, restores persisted theme from localStorage, broadcasts StyleVariant as CascadingValue.
- **StyleVariant enum** -- 7 named visual styles controlling `--radius`, `--spacing-scale`, and shadow values: Default, Vega (0.625rem/1), Nova (0.375rem/0.85, compact), Maia (1rem/1.15, spacious), Lyra (0rem/1, sharp/boxy), Mira (0.25rem/0.7, ultra-dense), Luma (0.75rem/1, glassmorphism). CSS: `_content/NeoUI.Blazor/css/themes/styles/{vega,nova,maia,lyra,mira,luma}.css`
- **RadiusPreset enum** -- independent named radius overrides (wins over StyleVariant in CSS cascade): None=0rem, Small=0.45rem, Medium=0.625rem (default, no file), Large=0.875rem. CSS: `_content/NeoUI.Blazor/css/themes/radius/{none,small,large}.css`
- **FontPreset enum** -- 6 curated font pairings: System (default), Inter, Geist, CalSans, DmSans, PlusJakarta. Sets `--font-sans` and `--font-heading`. CSS files set variables only; load actual font faces separately. CSS: `_content/NeoUI.Blazor/css/themes/fonts/{inter,geist,calsans,dmsans,plusjakarta}.css`
- **--font-heading CSS variable** -- new variable for distinct heading typography; falls back to `--font-sans`.
- **7-step proportional radius scale** -- `--radius-xs` (x0.4) through `--radius-4xl` (x2.6); all safe at `--radius: 0rem`.
- **MenuColor enum** -- controls background treatment of floating surfaces (Popover, DropdownMenu, Select, Combobox): Default, Inverted, DefaultTranslucent (50% opacity + blur(18px) + saturate(150%)), InvertedTranslucent.
- **MenuAccent enum** -- controls menu item hover intensity: Subtle (--accent, default), Bold (--primary, high-contrast).
- **BaseColor enum** -- 5 new chromatic neutrals: Luma (blue-indigo), Mist (cool blue-gray), Mauve (warm purple-gray), Taupe (warm brownish-gray), Olive (muted green-gray). Total: 10 base x 17 primary = 170 combinations.
- **ThemePreset record** -- bundles all 8 dimensions atomically. Built-in presets: Default, Luma (Zinc+Luma+Inter), Nova (Zinc+Nova+Small+Geist), Maia (Mauve+Maia+Large+PlusJakarta), Lyra (Slate+Lyra+None+Geist).
- **ThemeService** -- new properties: CurrentStyleVariant, CurrentRadiusPreset, CurrentFontPreset, CurrentMenuAccent, CurrentMenuColor. New methods: SetBaseColorAsync, SetPrimaryColorAsync, SetStyleVariantAsync, SetRadiusPresetAsync, SetFontPresetAsync, SetMenuAccentAsync, SetMenuColorAsync, ApplyPresetAsync. Old `SetTheme(base, primary)` still works.
- **ThemeSwitcher** -- new `ShowStyles` param (bool, false). When true: tabbed layout with Colors tab + Styles tab (variant, radius, font, menu accent, menu color). Trigger button shows two-tone swatch (base fill + primary border).
- **Tailwind v4:** Must add `@theme inline` to Tailwind build input to prevent hardcoded oklch() values overriding runtime CSS variable changes.

---

## Version 3.9.0 -- Mobile Components + ScreenTransition + Enhancements

### New Components
- **AppBar** -- mobile top app bar. Params: TitleContent (RenderFragment?), Title (string?), OnBack (EventCallback -- shows back chevron when set), Transparent (bool, false), RightContent (RenderFragment?), Class (string?)
- **BottomNav + BottomNavItem** -- persistent mobile tab bar. BottomNav: @bind-ActiveTab, Fixed (bool, true), AriaLabel ("Main navigation"). BottomNavItem: Value (required), Icon (string?), IconContent (RenderFragment?), Label (string?), BadgeCount (int, 0), MaxBadgeCount (int, 99), ShowZeroBadge (bool, false)
- **NotificationBadge** -- wraps any element, overlays count badge top-right. Params: Count (int, 0), ShowZero (bool, false), Dot (bool, false), Max (int, 99), Variant (NotificationBadgeVariant: Destructive/Primary/Success)
- **QuantityStepper** -- circular +/- quantity buttons. Params: @bind-Value (int, 1), Min (int, 1), Max (int.MaxValue), Step (int, 1), Size (QuantityStepperSize: Small/Default/Large), DestructiveAtMin (bool, false), OnDestructiveAction (EventCallback), Disabled (bool, false)
- **SectionHeader** -- title row with optional "view all" chevron and separator. Params: TitleContent (RenderFragment?), Title (string?), OnViewAll (EventCallback -- shows chevron when set), ShowSeparator (bool, false), Class (string?)
- **ScreenTransition** -- animated container for multi-screen navigation. Changing Key triggers entrance animation. Params: Key (string, required), Direction (ScreenTransitionDirection: None/Tab/Push/Pop), Class, ChildContent. Tab=fade-in, Push=slide from right, Pop=slide from left.

### Enhancements
- **Carousel:** `DotsPosition` (CarouselDotsPosition: Bottom/Top/Left/Right, default Bottom). Drag-click suppression.
- **Drawer:** DrawerContent gains `SnapPoints` (float[]?), `SnapIndex` (@bind, int), `ShowHandle` (bool). Bottom direction only.
- **Select:** `Presentation` (SelectPresentation: Popover/BottomSheet) -- BottomSheet opens options in a bottom Drawer.
- **Separator:** `LineStyle` (SeparatorStyle: Solid/Dashed/Dotted, default Solid).
- **ToggleGroup:** `Scrollable` (bool, false -- horizontal scroll strip), `Required` (bool, false -- active item cannot be deselected).
- **BadgeIcon:** New sub-component -- renders icon inside a Badge chip.
- **ScrollArea:** Non-horizontal instances no longer force width:100% on inner container.

---

## Version 3.8.2 -- SelectionIndicator + Sortable Cross-list DnD + ToggleGroupItem Fix

### New Features
- **SelectionIndicator** -- spring-animated indicator that slides between active items. Works with Tabs, ToggleGroup, RadioGroup, Pagination, and any custom markup. Params: Selector (string, default `[data-state=active]`), Hover (bool), Class (string?). CSS variables: `--si-duration`, `--si-easing`, `--si-height`.
- **Sortable cross-list drag-and-drop** -- multiple `Sortable` instances sharing a `Group` name allow items to be dragged across containers. Events: OnItemTransferredOut, OnItemTransferredIn. `SortableContent` uses `data-[state=over]` for visual drag-over feedback.

### Bug Fixes
- **ToggleGroupItem:** `aria-checked` now always renders as lowercase `"true"/"false"` (previously Blazor serialized as Pascal-case `"True"/"False"`, which is invalid ARIA).

---
# NeoUI -- Changelog

## Version 3.6.7 -- 2026-03-20

### Changes
- **Build:** Tailwind CSS build for components moved to CI/CD pipeline (no API changes).

---

## Version 3.6.6 -- 2026-03-20

### Bug Fixes
- **DataTable:** Keyboard focus ring now visible in Safari. CSS focus ring rules migrated from `<tr>`-level `box-shadow` (unsupported in Safari) to per-cell inset `box-shadow` on `[role="cell"]`/`[role="columnheader"]`. Rules scoped to `[data-keyboard-nav]` so they only activate inside `DataTable` with `EnableKeyboardNavigation="true"`.

---

## Version 3.6.5 -- 2026-03-20

### Enhancements
- **DataTable:** Mobile-responsive pagination bar. Three-tier layout: `< 640px` shows row count + Prev/Next only; `>= 640px` adds page-size selector + First/Last; `>= 1024px` adds Page X of Y display.

---

## Version 3.6.4 -- 2026-03-19

### New Features
- **`ILocalizer` / `DefaultLocalizer`:** DI-based localization abstraction for all UI-chrome strings rendered by NeoUI components (placeholders, button labels, ARIA text, pagination labels, empty states, screen-reader text). 70+ built-in English default keys. Register via `AddNeoUIComponents(localizer => { localizer.Set("Combobox.Placeholder", "..."); })`. Override globally at startup (Option A) or subclass `DefaultLocalizer` for `.resx`/`IStringLocalizer<T>` integration (Option B). Registered as **Scoped**.
- **Components wired up with `ILocalizer`:** `Alert`, `Breadcrumb`, `Calendar`, `Carousel`, `Combobox`, `DataGrid`, `DataTable`, `DataView`, `DatePicker`, `DateRangePicker`, `Dialog`, `MultiSelect`, `NumericInput`, `Pagination`, `Rating`, `ResponsiveNav`, `Sheet`, `Sidebar`, `TagInput`.
- **`ChartTooltip.AppendToBody`** (`bool?`) -- when `true`, appends the tooltip DOM to `document.body` instead of nesting inside the chart container. Prevents tooltip clipping inside `overflow:hidden` ancestors.

---

## Version 3.6.3 -- 2026-03-18

### Enhancements
- **DataTable:** `SyncWidthOnResize` (`bool`, default `false`) — keeps `<table>` width equal to sum of column widths during/after resize. Pair with `TableContainerClass="border-0"`.
- **DataTable:** `TableContainerClass` (`string?`) — CSS classes on the inner table container div (wraps `<table>`). Use `border-0` to remove the border.
- **DataTable:** `Striped` (`bool`, default `false`) and `StripeClass` (`string?`, default `even:bg-muted/30 even:hover:bg-muted/70`) — zebra row striping.
- **DataTable:** Smooth column reorder animation — affected columns fade out, Blazor re-renders, then fade back in at new positions with 500 ms ease-in transition.
- **DataTable:** Fixed column reorder double-invocation race condition via `_reorderInitializing`/`_resizeInitializing` bool flags.
- **DataTable:** Fixed column reorder incorrect order after 3+ moves — removed `commitDomReorder` from JS; Blazor is now sole owner of DOM ordering.
- **DataTable:** Fixed column resize width reset in Safari — remove all event listeners before `releasePointerCapture`.
- **PieChart:** Fixed `PieChart` and `FunnelChart` not using CSS variable color palette (`--chart-1` … `--chart-5`). Each slice/segment now receives an `itemStyle.color` cycling through the auto palette.
- **PieChart:** `Pie` series — new `Colors` (`string[]?`) parameter for custom slice palette.
- **FunnelChart:** `Funnel` series — new `Colors` (`string[]?`) parameter for custom segment palette.

### Breaking Changes
- **`Pie.Color`** parameter removed. It was never wired into the chart builder. Replace with `Colors="@(new[] { "#hex" })"`.

---

## Version 3.6.2 -- 2026-03-17

### Enhancements
- **DataTable:** Column pinning — `DataTableColumn.Pinned` (`ColumnPinnedSide`: `None`/`Left`/`Right`). Pinned columns stay fixed during horizontal scroll with frosted-glass treatment and separator borders.
- **DataTable:** Hierarchical/tree rows — `ChildrenProperty`, `LoadChildrenAsync`, `HasChildrenField`, `ValueField`, `ExpandedValues`, `ExpandedValuesChanged`. Pagination hidden in tree mode. Search auto-expands ancestor nodes.
- **DataTable:** Keyboard navigation — `↑`/`↓` arrow-key row navigation and `Enter`/`Space` selection, independent of `SelectionMode`.
- **ContextMenu:** Programmatic positioning — new `X`/`Y` parameters and `OpenAt(double x, double y)` method. Used by `DataTable` row context menu.

---

## Version 3.6.1 -- 2026-03-16

### Enhancements
- **DataTable:** Server-side virtualisation — `ItemsProvider` (`DataTableVirtualProvider<TData>`) for demand-driven infinite scroll via Blazor `<Virtualize>`. New types: `DataTableVirtualRequest`, `SortDescriptor`.
- **DataTable:** Client-side DOM windowing — `Virtualize="true"` for large in-memory datasets. Requires `ItemHeight` and `Height`.
- **DataTable:** New parameters: `ItemHeight` (`float`, 40), `Height` (`string`, "400px"), `VirtualizeOverscanCount` (`int`, 3).
- **DataView:** `GridColumnMinWidth` (`string?`) — CSS `repeat(auto-fill, minmax(…, 1fr))` adaptive grid. Overrides `GridColumns` when set.

### Breaking Changes
- **`DataTableRequest.SortColumn`** and **`SortDirection`** removed. Use `SortDescriptors` (`IReadOnlyList<SortDescriptor>`) instead: `req.SortDescriptors.FirstOrDefault()?.Column`.

---

## Version 3.6.0 -- 2026-03-14

### New Components (6)
- **Timeline** -- Composable chronological event display. Three statuses (`Pending`, `Active`, `Completed`), custom icon content, `Solid`/`Dashed`/`Dotted` connectors, collapsible items, and `Left`/`Right`/`Alternate` alignment. Sub-components: `Timeline`, `TimelineItem`, `TimelineHeader`, `TimelineTitle`, `TimelineDescription`, `TimelineTime`, `TimelineIcon`, `TimelineConnector`, `TimelineContent`, `TimelineEmpty`.
- **TreeView** -- Hierarchical data display with expand/collapse, single and multi-select, tri-state checkbox propagation, and optional drag-and-drop reordering. Generic `TItem` with lambda-based child/value/text/icon resolution. Sub-components: `TreeView<TItem>`, `TreeItem<TItem>`, `TreeItemNode<TItem>`.
- **DataView** -- Switchable list/grid layout container. Declarative `DataViewColumn` definitions auto-wire the search input, sort dropdown, and keyboard navigation. Built-in pagination, grouping, single/multi/none selection, infinite scroll, and client-side virtualization. Sub-components: `DataView<TItem>`, `DataViewColumn<TItem>`, `DataViewListTemplate`, `DataViewGridTemplate`.
- **DynamicForm** -- Schema-driven form renderer. Pass a `FormSchema` (list of `FormFieldDefinition`) and it renders the appropriate NeoUI input for all 24 `FieldType` values. Handles validation rules, `VisibleWhen` conditional visibility, and emits `@bind-Values` / `OnFieldChanged`. Components: `DynamicForm`, `FormSection`, `DynamicFieldRenderer`.
- **TagInput** -- Tag/chip input managing a list of string tags. Configurable `AddTrigger` flags enum (`Enter`, `Comma`, `Tab`, `Space`, `Blur`), async `OnSearchSuggestions`, duplicate prevention, `MaxTags` limit, and `Backspace` removal. Variants: `Default`, `Outlined`, `Ghost`.
- **SplitButton** -- Primary action button paired with a chevron-triggered dropdown for secondary actions. Matches `Button` `Variant` and `Size` tokens. Sub-components: `SplitButton`, `SplitButtonItem`, `SplitButtonSeparator`.

### New Chart Types (4) + New Demo (1)
- **CandlestickChart** -- OHLC chart. `Candlestick` series parameters: `OpenKey`, `HighKey`, `LowKey`, `CloseKey`, `DateKey`, `BullishColor`, `BearishColor`.
- **FunnelChart** -- Pipeline/conversion funnel. `Funnel` series parameters: `DataKey`, `NameKey`, `Sort` (`Ascending`/`Descending`/`None`), `Align` (`Left`/`Center`/`Right`), `Gap`, `MinSize`, `MaxSize`, `Top`, `Bottom`.
- **GaugeChart** -- Circular gauge and speedometer. Multiple `Gauge` series auto-tile horizontally. Key parameters: `StartAngle`, `EndAngle`, `SplitNumber`, `ShowPointer`, `ShowProgress`, `ProgressWidth`, `ShowSplitLine`, `ShowAxisLabel`, `Fill`.
- **HeatmapChart** -- Intensity grid (activity calendars, correlation matrices). `Heatmap` series uses `XKey`/`YKey`/`ValueKey`. `VisualMap` sub-component controls color-stop ranges, orientation, and min/max.
- **RadialBarChart** -- New demo page added for the pre-existing component at `/components/chart/radial-bar`.

### Enhancements
- **DataGrid:** New server-side demo page (`/components/datagrid/server-side`) with five patterns: `OnServerDataRequest` Func, `IDataGridServerDataProvider<TItem>` / `InMemoryProductProvider`, simulated latency, cross-page row selection (`@bind-SelectedItems`), and `FilterBuilder` integration.
- **DataGrid:** Fixed initializing-state race condition that produced empty rows on pages with multiple simultaneous `DataGrid<TItem>` instances. Removed `_isInitializing` from the render gate; `_columnsRegistered` is now the sole guard.
- **DataTable:** New appearance parameters -- `Dense` (`bool`, default `true`), `HeaderBackground` (`bool`, default `true`), `HeaderBorder` (`bool`, default `false`), `CellBorder` (`bool`, default `false`), `ColumnsVisibility` (`bool`, default `true`).
- **DataTable:** Per-part CSS class overrides -- `HeaderClass`, `HeaderRowClass`, `BodyRowClass`.
- **MultiSelect:** Selected-tag overflow now truncates visible tags and shows a `Tooltip` listing all selected values instead of reflowing the trigger width.
- **Sidebar / Button / LinkButton:** Fixed stale `ElementReference` when used as `AsChild` trigger after conditional re-renders (e.g. sidebar collapsed/expanded toggling `TooltipPrimitive` wrapper).
- **Sidebar:** Fixed `SidebarRail` absolute-positioned button causing a horizontal scrollbar. Removed `overflow-y-auto` and `h-screen` from layout variant classes; replaced with `min-h-full`.
- **DropdownMenuContent:** `ForceMount` default changed from `false` to `true`. Eliminates mid-animation pop-in on first open by pre-mounting the portal at startup.

---

## Version 3.1.0 -- 2026-02-15

### New Components
- **ColorPicker** -- Full color selection with hex, RGB, HSL support, swatches, and opacity control
- **CurrencyInput** -- Formatted currency input with locale-aware formatting and `@bind-Value`
- **DateRangePicker** -- Dual-calendar date range picker with optional quick-select presets
- **MaskedInput** -- Configurable format masks (phone, date, credit card, postal code, custom)
- **NumericInput** -- Number input with increment/decrement buttons, step, min/max, and formatting
- **RangeSlider** -- Dual-handle slider for selecting a min/max value range
- **Rating** -- Star rating with half-star precision, readonly mode, and custom icons
- **ResponsiveNav** -- Wrapper that shows full horizontal nav on desktop, hamburger sheet on mobile
- **DrawerService** -- Programmatic drawer API mirroring DialogService

### Enhancements
- **Sidebar:** `AutoDetectActive` prop -- automatically highlights menu items based on current URL
- **Sidebar:** `StaticRendering` prop -- click-delegation interop for SSR/prerendering scenarios
- **DataGrid:** `OnServerDataRequest` (Func-based) -- replaces legacy `OnDataRequest` EventCallback
- **DataGrid:** `DataFormatString` on `DataGridColumn` -- format cells without a CellTemplate
- **Calendar:** `CaptionLayout = Dropdown` -- quick month/year jump dropdown mode
- **Calendar:** `DisplayedMonthChanged` event -- react to user month navigation
- **Select:** Generic `TValue` -- bind to enum or any non-string type natively
- **RadioGroup:** Generic `TValue` -- bind to strongly-typed values
- **DropdownMenuContent:** `MatchTriggerWidth` prop -- expand dropdown to trigger width
- **DropdownMenuContent:** `Strategy = Fixed` -- escape stacking contexts (sidebars, modals)
- **Motion:** `StaggerChildren` support -- animate list items in sequence
- **Motion:** `RespectReducedMotion` prop -- honours `prefers-reduced-motion` media query
- **ToastProvider:** `MaxToasts` prop -- cap simultaneous visible toasts
- **ThemeSwitcher:** Live preview on hover before committing theme change
- **Input, Textarea:** `AriaDescribedBy` and `AriaInvalid` props for richer accessibility

### Bug Fixes
- Fixed focus trap escaping in nested Dialog → Sheet scenarios
- Fixed Combobox dropdown position in overflow containers
- Fixed DataGrid column reorder losing sort state
- Fixed Calendar year dropdown wrapping incorrectly in narrow viewports
- Fixed Sheet `LockScroll` not restoring body padding on close
- Fixed MultiSelect selected tags overflowing trigger button on small widths

### Breaking Changes
- **`DataGrid.OnDataRequest`** (EventCallback) deprecated; replaced by `OnServerDataRequest` (Func). Old binding still compiles but emits a warning and will be removed in 4.0.
- **`DialogContent.TrapFocus`** now defaults `true` (was `false`). Add `TrapFocus="false"` to opt out.
- **`SidebarProvider.HeightClass`** default changed from `h-screen` to `min-h-screen` to support content-taller-than-viewport layouts.

---

## Version 3.0.0 -- 2025-11-01

### Highlights
- Full rewrite targeting **.NET 10** and **Blazor InteractiveAuto**
- New **shadcn/ui**-compatible theming with 85 out-of-the-box theme combinations
- **NeoUI.Blazor.Primitives** headless layer extracted as standalone package
- Three icon libraries: **NeoUI.Icons.Lucide** (1,640), **NeoUI.Icons.Heroicons** (1,288), **NeoUI.Icons.Feather** (286)
- **Portal architecture** -- all floating UI (dialogs, sheets, toasts) rendered via `<PortalHost />`
- **AG Grid integration** -- `Grid` component wrapping AG Grid Community Edition with NeoUI Shadcn theme

### New in 3.0
- Accordion, AlertDialog, AspectRatio, Avatar, Badge, Breadcrumb, Button, ButtonGroup
- Calendar, Card, Carousel, Chart suite (Area, Bar, Line, Pie, Scatter, Radar, Composed, Radial)
- Checkbox, Collapsible, Combobox, Command, ContextMenu, DataGrid, DataTable, DatePicker
- Dialog, DialogService, DropdownMenu, Empty, Field, HeightAnimation, HoverCard
- Input, InputGroup, InputOTP, Item, Kbd, Label, MarkdownEditor, Menubar
- Motion (20+ animation presets), MultiSelect, NativeSelect, NavigationMenu
- Pagination, Popover, Progress, RadioGroup, Resizable, RichTextEditor, ScrollArea
- Select, Separator, Sheet, Sidebar, Skeleton, Slider, Spinner, Switch
- Tabs, Textarea, TimePicker, Toast, Toggle, ToggleGroup, Tooltip, Typography

### Breaking Changes from 2.x
- All component namespaces consolidated -- `@using NeoUI.Blazor` covers everything
- Theme system migrated from CSS classes to CSS custom properties
- `PortalHost` required in `MainLayout.razor`
- Service registration API changed: `AddNeoUIPrimitives()` + `AddNeoUIComponents()`
- Icon components renamed: `Icon` → `LucideIcon`, `HeroIcon`, `FeatherIcon`

---

## Version 2.x → 3.0 Migration Guide

### Package References

```bash
# Remove old packages
dotnet remove package NeoBlazorUI
dotnet remove package NeoBlazorUI.Primitives

# Add new packages
dotnet add package NeoUI.Blazor --version 3.6.7
```

### _Imports.razor

```razor
@* Old *@
@using NeoBlazorUI
@using NeoBlazorUI.Components

@* New *@
@using NeoUI.Blazor
@using NeoUI.Blazor.Services
@using NeoUI.Icons.Lucide
```

### Program.cs

```csharp
// Old
builder.Services.AddBlazorUIPrimitives();
builder.Services.AddBlazorUIComponents();

// New
builder.Services.AddNeoUIPrimitives();
builder.Services.AddNeoUIComponents();
builder.Services.AddScoped<IPortalService, PortalService>();
```

### MainLayout.razor

```razor
@* Add PortalHost (required for overlays) *@
<PortalHost />
```