NeoUI.Blazor.Primitives 4.0.2

NeoUI.Blazor.Primitives

Headless, unstyled Blazor primitive components with full accessibility support. Build your own component library using these composable primitives.

✨ Features

• 🎭 Headless & Unstyled: Complete control over styling - primitives provide behavior, accessibility, and state management without imposing any visual design
• ♿ Accessibility First: Built-in ARIA attributes, keyboard navigation, and screen reader support following WCAG 2.1 AA standards
• 🧩 Composition-Based: Flexible component composition patterns for building complex UIs
• 🎯 .NET 10 Ready: Built for the latest .NET platform with full WebAssembly and Server support
• 🔒 Type-Safe: Full C# type safety with IntelliSense support
• 🔄 State Management: Built-in controlled and uncontrolled state patterns
• ⌨️ Keyboard Navigation: Full keyboard support for all interactive components
• 📦 Zero Dependencies: No CSS or JavaScript required - bring your own styling

📦 Installation

dotnet add package NeoUI.Blazor.Primitives

🚀 Quick Start

Try the Live Demo - Explore all primitives and styled components with interactive examples and full documentation.

📚 Available Primitives

• Accordion: Collapsible content sections with single or multiple item expansion
• Checkbox: Binary selection control with indeterminate state
• Collapsible: Expandable content area with trigger control
• Dialog: Modal dialogs with backdrop and focus management
• Dropdown Menu: Context menus with items, separators, and keyboard shortcuts
• Hover Card: Rich preview cards on hover with delay control
• Label: Accessible labels for form controls with automatic association
• Popover: Floating panels for additional content with positioning
• Radio Group: Mutually exclusive options with keyboard navigation
• Select: Dropdown selection with groups and virtualization support
• Sheet: Side panels that slide in from viewport edges
• Sortable: Headless drag-and-drop sortable list with pointer, touch, and keyboard support. Supports cross-list transfer between grouped containers.
• Switch: Toggle control for on/off states
• Table: Data table with header, body, rows, cells, and pagination
• Tabs: Tabbed interface with keyboard navigation
• Tooltip: Brief informational popups with hover/focus triggers

🎨 Pre-Styled Components (100+)

Built on top of these primitives, NeoUI.Blazor provides production-ready components with beautiful shadcn/ui design:

Form & Input Components

Button, Button Group, Checkbox, Combobox, Date Picker, Field, Input, Input Group, Input OTP, Label, Multi Select, Native Select, Radio Group, Select, Slider, Switch, Textarea, Time Picker

Data Display Components

Avatar, Badge, Card, Data Table, Empty, Grid, Item, Kbd, Progress, Separator, Skeleton, Spinner, Typography

Navigation Components

Accordion, Breadcrumb, Command, Context Menu, Dropdown Menu, Menubar, Navigation Menu, Pagination, Selection Indicator, Sidebar, Tabs

Overlay Components

Alert Dialog, Dialog, Hover Card, Popover, Sheet, Toast, Tooltip

Feedback Components

Alert

Layout & Display Components

Aspect Ratio, Carousel, Collapsible, Resizable, Scroll Area, Selection Indicator, Sortable

Advanced Components

Chart (12 types), Grid, Markdown Editor, Motion (20+ animation presets), Rich Text Editor, Toggle, Toggle Group

Icon Libraries

Lucide Icons (1,640+), Heroicons (1,288), Feather Icons (286)

Want beautiful defaults? Check out the Components README for full documentation.

📖 Primitive API Reference

Accordion

<AccordionPrimitive Type="AccordionType.Single" Collapsible="true" DefaultValue="item-1">
    <AccordionItemPrimitive Value="item-1">
        <AccordionTriggerPrimitive>Section 1</AccordionTriggerPrimitive>
        <AccordionContentPrimitive>Content 1</AccordionContentPrimitive>
    </AccordionItemPrimitive>
</AccordionPrimitive>

Tabs

<TabsPrimitive
    DefaultValue="tab1"
    Orientation="TabsOrientation.Horizontal"
    ActivationMode="TabsActivationMode.Automatic">
    <TabsListPrimitive>
        <TabsTriggerPrimitive Value="tab1">Tab 1</TabsTriggerPrimitive>
    </TabsListPrimitive>
    <TabsContentPrimitive Value="tab1">Content</TabsContentPrimitive>
</TabsPrimitive>

Sheet

<SheetPrimitive>
    <SheetTriggerPrimitive>Open</SheetTriggerPrimitive>
    <SheetPortal>
        <SheetOverlay />
        <SheetContentPrimitive Side="SheetSide.Right">
            <SheetTitlePrimitive>Title</SheetTitlePrimitive>
            <SheetDescriptionPrimitive>Description</SheetDescriptionPrimitive>
            <SheetClosePrimitive>Close</SheetClosePrimitive>
        </SheetContentPrimitive>
    </SheetPortal>
</SheetPrimitive>

Popover

<PopoverPrimitive>
    <PopoverTriggerPrimitive>Open</PopoverTriggerPrimitive>
    <PopoverContentPrimitive Side="PopoverSide.Bottom" Align="PopoverAlign.Center">
        Content here
    </PopoverContentPrimitive>
</PopoverPrimitive>

Tooltip

<TooltipPrimitive DelayDuration="400" HideDelay="0">
    <TooltipTriggerPrimitive>Hover me</TooltipTriggerPrimitive>
    <TooltipContentPrimitive>Tooltip text</TooltipContentPrimitive>
</TooltipPrimitive>

HoverCard

<HoverCardPrimitive OpenDelay="700" CloseDelay="300">
    <HoverCardTriggerPrimitive>Hover for preview</HoverCardTriggerPrimitive>
    <HoverCardContentPrimitive>Rich preview content</HoverCardContentPrimitive>
</HoverCardPrimitive>

Checkbox

<CheckboxPrimitive
    @bind-Checked="isChecked"
    Indeterminate="@isIndeterminate"
    IndeterminateChanged="HandleIndeterminateChange" />

Select

<SelectPrimitive TValue="string" @bind-Value="selected" @bind-Open="isOpen">
    <SelectTriggerPrimitive>
        Choose an option...
    </SelectTriggerPrimitive>
    <SelectContentPrimitive>
        <SelectItemPrimitive Value="@("a")">Option A</SelectItemPrimitive>
        <SelectItemPrimitive Value="@("b")">Option B</SelectItemPrimitive>
    </SelectContentPrimitive>
</SelectPrimitive>

Select is generic (TValue). Supports both value and open state binding.

Table

<Table TData="Person">
    <TableHeader>
        <TableRow>
            <TableHeaderCell>Name</TableHeaderCell>
            <TableHeaderCell>Email</TableHeaderCell>
        </TableRow>
    </TableHeader>
    <TableBody>
        @foreach (var person in people)
        {
            <TableRow>
                <TableCell>@person.Name</TableCell>
                <TableCell>@person.Email</TableCell>
            </TableRow>
        }
    </TableBody>
</Table>

Sortable

<SortablePrimitive TItem="MyItem"
                   Items="@items"
                   OnItemsReordered="@(r => items = r)"
                   GetItemId="@(i => i.Id)">
    <SortableContentPrimitive class="flex flex-col gap-2">
        @foreach (var item in items)
        {
            <SortableItemPrimitive @key="@item.Id" Value="@item.Id"
                                   class="flex items-center gap-3 rounded border px-4 py-3">
                <SortableItemHandlePrimitive class="cursor-grab" />
                <span>@item.Name</span>
            </SortableItemPrimitive>
        }
    </SortableContentPrimitive>
    <SortableOverlayPrimitive class="rounded border shadow-lg px-4 py-3" />
</SortablePrimitive>

Cross-list transfer — share a Group name across multiple SortablePrimitive instances. Consumer handles all state mutations via transfer events.

<SortablePrimitive TItem="MyItem" Items="@colA" Group="board"
                   GetItemId="@(i => i.Id)"
                   OnItemsReordered="@(r => colA = r)"
                   OnItemTransferredOut="@(a => colA = colA.Where(i => i.Id != a.ActiveId).ToList())"
                   OnItemTransferredIn="@(a => { var item = FindItem(a.ActiveId); colA.Insert(a.Index, item); })">
    ...
</SortablePrimitive>

SortablePrimitive<TItem> parameters

SortableScope<TItem> — exposed via Context="s" on <SortablePrimitive> or <Sortable>.

SortableItemPrimitive parameters

SortableOverlayPrimitive parameters

MultiSelect

Note: MultiSelect is a fully styled component with no separate primitive — use <MultiSelect> directly from NeoUI.Blazor.

🚀 Usage Example

@using NeoUI.Blazor.Primitives

<DialogPrimitive>
    <DialogTriggerPrimitive class="my-custom-button-class">
        Open Dialog
    </DialogTriggerPrimitive>
    <DialogPortal>
        <DialogOverlay class="my-overlay-styles" />
        <DialogContentPrimitive class="my-custom-dialog-styles">
            <DialogTitlePrimitive class="my-title-styles">
                Custom Styled Dialog
            </DialogTitlePrimitive>
            <DialogDescriptionPrimitive class="my-description-styles">
                This is a fully customizable dialog.
            </DialogDescriptionPrimitive>
            <p class="my-content-styles">Your content here</p>
            <DialogClosePrimitive class="my-close-button">Close</DialogClosePrimitive>
        </DialogContentPrimitive>
    </DialogPortal>
</DialogPrimitive>

🔄 Controlled vs Uncontrolled

All stateful primitives support both controlled and uncontrolled modes:

Uncontrolled (Component manages its own state)

<DialogPrimitive>
    <DialogTriggerPrimitive>Open</DialogTriggerPrimitive>
    <DialogPortal>
        <DialogOverlay />
        <DialogContentPrimitive>
            
        </DialogContentPrimitive>
    </DialogPortal>
</DialogPrimitive>

Controlled (Parent component manages state)

<DialogPrimitive @bind-Open="isDialogOpen">
    <DialogTriggerPrimitive>Open</DialogTriggerPrimitive>
    <DialogPortal>
        <DialogOverlay />
        <DialogContentPrimitive>
            <button @onclick="() => isDialogOpen = false">Close</button>
        </DialogContentPrimitive>
    </DialogPortal>
</DialogPrimitive>

@code {
    private bool isDialogOpen = false;
}

🏗️ Design Philosophy

NeoUI.Blazor.Primitives follows the "headless component" pattern popularized by Radix UI and Headless UI:

1. Separation of Concerns: Primitives handle behavior and accessibility; you handle the design
2. Composability: Build complex components by composing simple primitives
3. No Style Opinions: Zero CSS included - bring your own design system
4. Accessibility by Default: ARIA attributes and keyboard navigation built-in

🎯 When to Use

Use NeoUI.Blazor.Primitives when:

• Building a custom design system from scratch
• Need complete control over component styling
• Want to match a specific brand or design language
• Integrating with existing CSS frameworks or design tokens

Consider NeoUI.Blazor when:

• Want beautiful defaults with shadcn/ui design
• Prefer zero-configuration setup with pre-built CSS
• Need to ship quickly without custom styling

📖 Documentation

For full documentation, examples, and API reference, visit:

• Live Demo - Interactive examples and documentation
• GitHub Repository

📄 License

MIT License - see LICENSE file for details

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🙏 Acknowledgments

• Initial Blazor primitives inspiration by Mathew Taylor
• Design patterns inspired by Radix UI and Headless UI
• Built with ❤️ for the Blazor community

📊 Version Information

• Current Version: 4.0.0
• Target Framework: .NET 10
• Package ID: NeoUI.Blazor.Primitives
• Assembly Name: NeoUI.Blazor.Primitives