DEV Community: Jimmy Petrus

The beauty of component composability — and why NeoUI does it differently

Jimmy Petrus — Sat, 28 Mar 2026 06:08:44 +0000

There's a question every UI library author eventually has to answer: when you need to add a new capability to an existing component, what do you do?

It sounds simple. But how you answer it reveals everything about how your library is architected — and whether it will age well or collapse under its own weight.

NeoUI v3.8.0 ships a new Sortable drag-and-drop component. The way it was built is a better answer to that question than most UI libraries give — and a recent refinement takes the idea one step further. Let me show you why.

The traditional approach — and where it breaks

Let's say you have a list view component. It renders a list of items. Works great.

A designer asks: "Can we make the items draggable to reorder?"

In most UI libraries, you have two options.

Option A: Add the feature directly to the component.

Add a Draggable prop. Add a OnReorder event. Add drag handle rendering logic. Add drag-over state. Add keyboard handling. Add the overlay. Now your ListView has grown a second responsibility — it's both a list renderer and a drag-and-drop manager. Every future capability request adds another flag, another event, another conditional render path. Two years later your component has 40 parameters and a 2,000-line implementation.

Option B: Create a new variant.

Ship a SortableListView. Now you have ListView and SortableListView — two components to maintain, two sets of documentation, two places to fix bugs, two implementations to keep in sync. And when the next request comes — "Can the data table rows also be sortable?" — you're back to the same decision: add it to DataTable, or ship a SortableDataTable?

This is how UI libraries end up with enormous surface areas and inconsistent behaviour across component variants. It's also how they become resistant to change — every new capability requires modifying existing code rather than composing new behaviour alongside it.

Enter composability

The shadcn/ui philosophy that NeoUI is built on says something different: capabilities should be composable around components, not baked into them.

Rather than modifying ListView or DataTable to support sorting, you build a Sortable wrapper that can be layered around any component. The existing components stay unchanged. The new behaviour lives in new code. And the same Sortable works for every list-like component — today and in the future.

This is exactly how NeoUI's new Sortable component works.

Sortable in NeoUI — the basic case

The simplest use case looks like this:

<Sortable TItem="TaskItem"
          Items="@items"
          OnItemsReordered="@(r => items = r)"
          GetItemId="@(i => i.Id)">
    <SortableContent>
        @foreach (var item in items)
        {
            <SortableItem Value="@item.Id">
                <SortableItemHandle />
                <span class="flex-1 text-sm font-medium select-none">@item.Name</span>
            </SortableItem>
        }
    </SortableContent>
    <SortableOverlay />
</Sortable>

Sortable wraps your content. SortableContent defines the droppable region. SortableItem marks each draggable element. SortableItemHandle is the grip — the six-dot handle users grab. SortableOverlay is the floating ghost shown while dragging.

When a drag completes, OnItemsReordered fires with the new ordered list. Your state updates. Blazor re-renders. Done.

The interaction model is complete: pointer, touch, and full keyboard support (Space/Enter to grab, arrow keys to move, Escape to cancel) — all built into the primitive layer.

Now the interesting part — composing with DataTable

Here's where the design philosophy becomes visible. The question was: how do you make DataTable rows sortable?

The answer is not to add drag-and-drop support to DataTable. Instead, you wrap DataTable with Sortable. DataTable exposes AdditionalRowAttributes — a general-purpose hook for stamping attributes onto each rendered row — and Sortable uses it to wire up drag identity. Neither component knows anything about the other.

<Sortable TItem="TaskItem"
          Items="@items"
          OnItemsReordered="@(r => items = r)"
          GetItemId="@(i => i.Id)"
          Context="s">
    <SortableContent Class="block">
        <DataTable TData="TaskItem" Data="@items"
                   AdditionalRowAttributes="@s.RowAttributes"
                   ShowPagination="false"
                   ShowToolbar="false">
            <Columns>
                <DataTableColumn TData="TaskItem" TValue="string"
                                 Property="@(i => i.Id)"
                                 Header=""
                                 Width="40px">
                    <CellTemplate Context="row">
                        <SortableItemHandle Class="mx-auto" />
                    </CellTemplate>
                </DataTableColumn>
                <DataTableColumn TData="TaskItem" TValue="string"
                                 Property="@(i => i.Name)"
                                 Header="Task" />
                <DataTableColumn TData="TaskItem" TValue="string"
                                 Property="@(i => i.Status)"
                                 Header="Status" />
            </Columns>
        </DataTable>
    </SortableContent>
    <SortableOverlay Class="rounded" />
</Sortable>

Notice what didn't change:

DataTable has no Draggable flag
There's no SortableDataTable variant
Column definitions, sorting, selection, toolbar — all work exactly as before
The drag handle lives in a normal CellTemplate using the existing Columns API

Sortable does all the heavy lifting. SortableItemHandle wires itself through the primitive's context — drop it in a CellTemplate and it just works, the same way placing a SortableItemHandle in any other template gives you a grip. DataTable is entirely unaware any of this is happening.

Taking composability further — `SortableScope<TItem>`

This works. But there's still something slightly awkward: the consumer has to manually construct the attributes dictionary and pass it to AdditionalRowAttributes. That's an implementation concern of Sortable leaking into the consumer's code.

This is the kind of friction composable APIs should eliminate. So we took it a step further.

Sortable<TItem> provides a SortableScope<TItem> through its ChildContent — a typed context following the same Blazor-idiomatic pattern as EditForm with Context="ctx" or QuickGrid with Context="item". It's opt-in: you only add Context="s" when you need what the scope exposes. Without it, Sortable works exactly as shown in the basic examples above.

<Sortable TItem="TaskItem"
          Items="@items"
          OnItemsReordered="@(r => items = r)"
          GetItemId="@(i => i.Id)"
          Context="s">
    <SortableContent Class="block">
        <DataTable TData="TaskItem" Data="@items"
                   AdditionalRowAttributes="@s.RowAttributes"
                   ShowPagination="false"
                   ShowToolbar="false">
            <Columns>
                <DataTableColumn TData="TaskItem" TValue="string"
                                 Property="@(i => i.Id)"
                                 Header="" Width="40px">
                    <CellTemplate Context="row">
                        <SortableItemHandle Class="mx-auto" />
                    </CellTemplate>
                </DataTableColumn>
                <DataTableColumn TData="TaskItem" TValue="string"
                                 Property="@(i => i.Name)"
                                 Header="Task" />
                <DataTableColumn TData="TaskItem" TValue="string"
                                 Property="@(i => i.Status)"
                                 Header="Status" />
            </Columns>
        </DataTable>
    </SortableContent>
    <SortableOverlay Class="rounded" />
</Sortable>

s.RowAttributes is all you pass to AdditionalRowAttributes. Everything Sortable needs to track each row is encapsulated inside it — the consumer never sees the wiring. The same applies to SortableItemHandle — drop it anywhere in your template and it finds its context automatically. You don't configure it, you don't pass IDs to it. It just works.

SortableScope<TItem> exposes three properties:

Property	Type	Description
`RowAttributes`	`Func<TItem, Dictionary<string, object>?>`	Sortable attributes for each row. Pass directly to `AdditionalRowAttributes`.
`ActiveId`	`string?`	The ID of the item currently being dragged. `null` when not dragging.
`IsDragging`	`bool`	`true` while any drag is in progress.
`IsItemDragging(item)`	`bool`	Returns `true` if the given item is the one currently being dragged.

The last three are bonus capabilities — they give you live drag state in your template with zero extra event wiring. Want to dim non-dragged items during a drag? Render a custom placeholder? Show a drag count badge?

<Sortable TItem="TaskItem"
          Items="@items"
          OnItemsReordered="@(r => items = r)"
          GetItemId="@(i => i.Id)"
          Context="s">
    <SortableContent>
        @foreach (var item in items)
        {
            <SortableItem Value="@item.Id"
                          Class="@(s.IsItemDragging(item) ? "opacity-40" : "")">
                <SortableItemHandle />
                <span class="flex-1">@item.Name</span>
                @if (s.IsDragging)
                {
                    <Badge Variant="BadgeVariant.Secondary">Moving...</Badge>
                }
            </SortableItem>
        }
    </SortableContent>
    <SortableOverlay />
</Sortable>

And critically — s.RowAttributes is not DataTable-specific. Any future component that exposes a row/item attribute hook works the same way:

<Sortable TItem="TaskItem" ... Context="s">
    <SortableContent Class="block">
        <DataTable AdditionalRowAttributes="@s.RowAttributes" ... />
        <MyFutureGrid RowAttrs="@s.RowAttributes" ... />   <!-- works too -->
    </SortableContent>
</Sortable>

Sortable doesn't know what DataTable is. DataTable doesn't know what Sortable is. SortableScope is the typed bridge between them — and it works for every downstream component, forever, without either side needing to change.

The same pattern with DataView

The same composability applies to DataView — and DataView required zero changes:

<Sortable TItem="ProjectItem"
          Items="@items"
          OnItemsReordered="@(r => items = r)"
          GetItemId="@(i => i.Id)">
    <SortableContent Class="block">
        <DataView TItem="ProjectItem" Items="@items">
            <ListTemplate Context="item">
                <SortableItem Value="@item.Id" Class="mb-2">
                    <SortableItemHandle />
                    <Item>
                        <ItemContent>
                            <ItemTitle>@item.Name</ItemTitle>
                            <ItemDescription>@item.Description</ItemDescription>
                        </ItemContent>
                    </Item>
                </SortableItem>
            </ListTemplate>
        </DataView>
    </SortableContent>
    <SortableOverlay />
</Sortable>

Place <SortableItem> directly inside <ListTemplate> or <GridTemplate>. That's it. DataView doesn't know anything about drag-and-drop. It doesn't need to.

The architecture behind this: the two-layer model

NeoUI's composability works because every complex component is built in two layers.

Sortable              → Styled wrapper with sensible defaults
SortablePrimitive     → Headless, zero visual opinion

The headless primitive handles all the hard parts: pointer capture, touch events, keyboard navigation, focus management, ARIA attributes, drag overlay positioning, and the reorder algorithm. It exposes only the behaviour, with zero styling attached.

The styled component layers pre-built CSS on top — the flex flex-col gap-2 layout, the rounded-lg border bg-card item styling, the shadow-lg opacity-90 scale-[1.05] overlay animation. Sensible defaults for the common case.

When you need full control, you escape to the primitive:

<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 Value="@item.Id"
                                   class="flex items-center gap-3 rounded-lg border bg-card px-4 py-3">
                <SortableItemHandlePrimitive class="cursor-grab active:cursor-grabbing text-muted-foreground" />
                <span class="flex-1 text-sm font-medium select-none">@item.Name</span>
            </SortableItemPrimitive>
        }
    </SortableContentPrimitive>
    <SortableOverlayPrimitive class="rounded-lg shadow-lg opacity-90
                                     data-[state=dragging]:scale-[1.05]
                                     transition-transform duration-150" />
</SortablePrimitive>

Every CSS class here is yours. The primitive supplies the behaviour, accessibility, and interaction model. You supply the appearance.

The overlay: a detail worth appreciating

The drag overlay — the ghost that floats under your cursor while dragging — is handled through SortableOverlay / SortableOverlayPrimitive. The implementation is worth understanding because it illustrates another NeoUI design choice.

By default, when ChildContent is null, the JS sensor auto-clones the dragged element (cloneNode(true)) into the overlay frame. The clone fills the frame at 100×100% and carries over the source element's styles — so the ghost looks exactly like the item being dragged, with no extra work.

For <tr> elements (DataTable rows), the sensor snapshots each td/th computed width before cloning and stamps it as an inline width on the clone cells. This preserves the shared table layout geometry even though the clone lives outside its parent <table>. It's a subtle problem and a clean solution.

Visual effects — shadow, opacity, scale — live entirely in CSS via the data-[state=dragging] attribute. JS sets data-state="dragging" after positioning the overlay; Tailwind's data-attribute variants do the rest. No JS inline transforms. No animation logic in JavaScript.

When you want a fully custom ghost, provide a ChildContent:

<SortableOverlay>
    @* ChildContent context is the active item ID *@
    <SortableOverlay ChildContent="@(activeId => @<div class="my-custom-ghost">
        Dragging: @activeId
    </div>)" />
</SortableOverlay>

Why this matters beyond drag-and-drop

The Sortable component is a concrete example of a principle that runs through every NeoUI component.

When v3.6.0 shipped Timeline, it didn't add timeline rendering to Card or create a TimelineCard variant. Timeline is its own composable set of sub-components — TimelineItem, TimelineHeader, TimelineConnector, TimelineContent — that you assemble however your layout requires.

When DynamicForm shipped, it didn't modify Input or Select or DatePicker. It reads a schema and renders the existing components exactly as you'd write them by hand — because those components are already composable enough to be driven by data.

When DataView shipped with list/grid switching, it didn't rebuild table or card rendering. It exposed ListTemplate and GridTemplate slots where you compose existing components inside.

SortableScope<TItem> takes this a step further: it's not just composing components together, it's encapsulating the integration contract itself. The consumer gets a typed scope object rather than raw implementation details. Sortable and DataTable remain completely independent — SortableScope is the only shared surface between them, and it's intentionally minimal.

The pattern is always the same: new behaviour as new components, composed around existing ones, with minimal surgical hooks where genuine integration is required — and those hooks encapsulated so consumers never see the machinery.

This is how a library stays maintainable as it grows. It's why NeoUI can ship 100+ components without each one becoming a monolith.

Using Sortable in your project

Available in NeoUI.Blazor v3.8.0:

dotnet add package NeoUI.Blazor --version 3.8.0

The headless primitive is in NeoUI.Blazor.Primitives (included transitively).

Key parameters at a glance:

Parameter	Description
`Items`	The list to sort. Required.
`GetItemId`	Extracts a unique string ID from each item. Required.
`OnItemsReordered`	Fires after a drop with the new ordered list.
`Orientation`	`Vertical` (default), `Horizontal`, `Grid`, or `Mixed`.
`OnDragStart`	Fires when drag begins. Receives the active item ID.
`OnDragEnd`	Fires when drag ends. Carries `ActiveId`, `OverId`, `FromIndex`, `ToIndex`, `Moved`.
`OnDragCancel`	Fires when drag is cancelled (Escape or pointer cancel).

Live demos at demos.neoui.io cover vertical lists, horizontal chips, full-item drag, custom handle icons, DataView composability, DataTable integration, and the primitive escape hatch.

I wanted shadcn/ui for Blazor. It didn’t exist. So I built it.

Jimmy Petrus — Wed, 25 Mar 2026 14:03:11 +0000

If you've spent any time in the React ecosystem over the past two years, you've seen shadcn/ui everywhere. And for good reason — it solved something fundamental that every other component library got wrong.

I'm a Blazor developer. And for the longest time, watching shadcn/ui take over the React world felt like watching a party happening through a window.

This is the story of why I built NeoUI, what I learned, and how Blazor developers can now have the same thing.

The shadcn/ui moment

When shadcn/ui launched, it didn't just ship a set of components. It shipped a philosophy.

The insight was simple but radical: you shouldn't be fighting your component library. Most UI libraries are configuration-first — you install them, accept their design system, and spend half your time overriding their opinions. Customising a MUI component to not look like MUI is a rite of passage every React developer has suffered through.

shadcn/ui flipped this. Instead of locking you into a package you can't modify, it gives you the source. Components live in your project. You own them. You change them however you want. There's no node_modules black box to fight.

The other half of the philosophy — composability over configuration — borrowed from Radix UI's headless primitives model. Behaviour (accessibility, keyboard navigation, ARIA) is separated from appearance. You get the hard parts for free, and the visual layer is entirely yours.

The React ecosystem embraced it almost immediately. By early 2024, shadcn/ui had become the de-facto starting point for new React projects. Every design system article, every SaaS starter kit, every "how I built my dashboard" post referenced it.

The Blazor gap

Here's what the Blazor ecosystem looked like during that same period.

The main options were MudBlazor, Radzen, Blazorise, and the Microsoft Fluent UI library. Each of them is genuinely good at what it does. MudBlazor has excellent documentation and a passionate community. Radzen ships a remarkable number of components for a free library. But they all share the same fundamental model:

Install the package. Accept the design system. Style within their constraints.

MudBlazor looks like Material Design because it is Material Design. That's not a criticism — it's a deliberate, coherent choice. But if you're building a SaaS product with its own brand, or a dashboard that needs to look nothing like any other Blazor app, you're immediately in override territory. You end up writing more CSS to fight the library than you would have written starting from scratch.

I kept looking at the React world and thinking: Blazor deserves better than this. C# on the frontend is genuinely a superpower — strongly typed components, the full .NET ecosystem, no context-switching between languages. Why should the UI layer be the weak point?

So I went looking. And I did find a few attempts at bringing shadcn/ui to Blazor. But none of them were what I needed.

Some were early experiments that had gone dormant — a handful of components, last commit months ago, clearly abandoned before they got anywhere near production-ready. Others took an approach that felt fundamentally wrong for the platform: wrapping React components and calling them Blazor. That's not Blazor UI — that's JavaScript with a C# facade bolted on. You lose IntelliSense, type safety, the Razor component model, and any real integration with Blazor's rendering pipeline. It defeats the entire point of using Blazor in the first place.

What I couldn't find was anything that was simultaneously serious, well-architected, and comprehensive. Something built natively on Blazor from the ground up, with a proper two-layer architecture, real accessibility, a maintainable codebase, and enough components to actually ship a production application. Not a proof of concept. Not a wrapper. A real library.

The answer wasn't to build another component library with another design system. The answer was to bring the shadcn/ui philosophy to Blazor — properly, natively, completely.

What NeoUI is (and isn't)

NeoUI is not a port of shadcn/ui. It's a Blazor component library that adopts shadcn/ui's design principles:

Composability over configuration — components are built to be composed, not configured through a wall of parameters
You own your UI — primitives give you headless behaviour you can style completely
Zero lock-in — no mandatory design system, no "MudBlazor aesthetic"
Pre-built is optional — use the styled layer for speed, or drop to primitives for full control

And critically — it's fully compatible with shadcn/ui and tweakcn themes. If you copy a theme from ui.shadcn.com/themes and paste it into your wwwroot/styles/theme.css, NeoUI uses it immediately. The same theme your React colleagues use. The same customisation tools. The same mental model.

Architecture: the two-layer model

The design that makes this possible is a two-package architecture.

NeoUI.Blazor           → Styled components (pre-built CSS, ready to use)
NeoUI.Blazor.Primitives → Headless components (no CSS, full control)

The styled layer is what most developers will use. Install NeoUI.Blazor, add two lines to App.razor, and you have 100+ production-ready components that look great out of the box. No Tailwind setup. No Node.js. No build tooling.

The primitives layer is for teams who need complete control. Every complex component — Dialog, Dropdown, Select, Tooltip, Sheet — has a corresponding headless primitive that handles all the accessibility, keyboard navigation, and ARIA attributes, with zero styling attached. You bring your own CSS.

This is directly analogous to how Radix UI underlies shadcn/ui in the React world.

shadcn/ui vs NeoUI — side by side

The parallel is easiest to see in code. Here's the same Dialog component in both ecosystems.

shadcn/ui (React)

import {
  Dialog,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogTrigger,
  DialogClose,
} from "@/components/ui/dialog"
import { Button } from "@/components/ui/button"

export function ConfirmDialog() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="outline">Open</Button>
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Are you sure?</DialogTitle>
          <DialogDescription>
            This action cannot be undone.
          </DialogDescription>
        </DialogHeader>
        <DialogFooter>
          <DialogClose asChild>
            <Button variant="outline">Cancel</Button>
          </DialogClose>
          <Button>Continue</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}

NeoUI (Blazor)

<Dialog>
    <DialogTrigger AsChild>
        <Button Variant="ButtonVariant.Outline">Open</Button>
    </DialogTrigger>
    <DialogContent>
        <DialogHeader>
            <DialogTitle>Are you sure?</DialogTitle>
            <DialogDescription>
                This action cannot be undone.
            </DialogDescription>
        </DialogHeader>
        <DialogFooter>
            <DialogClose AsChild>
                <Button Variant="ButtonVariant.Outline">Cancel</Button>
            </DialogClose>
            <Button>Continue</Button>
        </DialogFooter>
    </DialogContent>
</Dialog>

The structural parallel is intentional and precise. If you've used shadcn/ui, NeoUI feels immediately familiar. The same AsChild pattern from Radix UI — allowing a trigger to render as your own element rather than a default button — is fully implemented.

Another example: Select

shadcn/ui (React)

<Select>
  <SelectTrigger>
    <SelectValue placeholder="Pick a framework" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="blazor">Blazor</SelectItem>
    <SelectItem value="react">React</SelectItem>
    <SelectItem value="vue">Vue</SelectItem>
  </SelectContent>
</Select>

NeoUI (Blazor)

<Select>
    <SelectTrigger>
        <SelectValue Placeholder="Pick a framework" />
    </SelectTrigger>
    <SelectContent>
        <SelectItem Value="blazor">Blazor</SelectItem>
        <SelectItem Value="react">React</SelectItem>
        <SelectItem Value="vue">Vue</SelectItem>
    </SelectContent>
</Select>

Same component tree. Same mental model. The only difference is C# conventions — PascalCase attributes, strongly typed values. For a team that works across React and Blazor, this means near-zero context switching.

Headless primitive: Dialog

When you need full control, drop to the primitive layer:

@using NeoUI.Blazor.Primitives.Dialog

<DialogPrimitive>
    <DialogPrimitiveTrigger AsChild>
        <button class="my-custom-trigger">Open settings</button>
    </DialogPrimitiveTrigger>
    <DialogPrimitiveContent class="my-dialog-panel">
        <DialogPrimitiveTitle class="my-dialog-title">
            Settings
        </DialogPrimitiveTitle>
        <!-- Your completely custom markup and styles -->
        <div class="my-dialog-body">
            <p>Everything here is yours. NeoUI handles focus trapping,
               Escape key, scroll lock, and ARIA — you handle the rest.</p>
        </div>
        <DialogPrimitiveClose class="my-close-button">✕</DialogPrimitiveClose>
    </DialogPrimitiveContent>
</DialogPrimitive>

No NeoUI styles apply. No CSS variables referenced. The primitive gives you:

Focus trapping inside the dialog
Escape key to close
Scroll lock on body
role="dialog", aria-modal, aria-labelledby wired automatically
Keyboard navigation and screen reader support

You provide everything visual.

Theming: drop in any shadcn/ui theme

This is one of NeoUI's most practical advantages. The entire ecosystem of shadcn/ui themes works out of the box.

Go to ui.shadcn.com/themes or tweakcn.com, pick or customise a theme, copy the CSS variables, and paste them into wwwroot/styles/theme.css:

@layer base {
  :root {
    --background: oklch(1 0 0);
    --foreground: oklch(0.145 0 0);
    --primary: oklch(0.205 0 0);
    --primary-foreground: oklch(0.985 0 0);
    --secondary: oklch(0.97 0 0);
    --secondary-foreground: oklch(0.205 0 0);
    --muted: oklch(0.97 0 0);
    --muted-foreground: oklch(0.556 0 0);
    --accent: oklch(0.97 0 0);
    --accent-foreground: oklch(0.205 0 0);
    --destructive: oklch(0.577 0.245 27.325);
    --border: oklch(0.922 0 0);
    --radius: 0.5rem;
    /* ... */
  }

  .dark {
    --background: oklch(0.145 0 0);
    --foreground: oklch(0.985 0 0);
    /* ... */
  }
}

Reference it before NeoUI's CSS in App.razor:

<link rel="stylesheet" href="styles/theme.css" />
<link href="@Assets["_content/NeoUI.Blazor/components.css"]" rel="stylesheet" />
<script src="@Assets["_content/NeoUI.Blazor/js/theme.js"]"></script>

Every NeoUI component picks up your theme variables automatically. Dark mode works by adding .dark to <html> — no JavaScript required, no flicker (theme.js applies the saved preference before Blazor loads, preventing FOUC).

Beyond static themes, NeoUI ships a ThemeService and ThemeSwitcher component for runtime switching across 85 combinations — 5 base colours × 17 primary colours — all without a page reload.

What's inside

After 828 commits, NeoUI currently ships:

100+ styled components covering every UI pattern a real application needs:

Forms: Button, Input, Select, Combobox, DatePicker, DateRangePicker, ColorPicker, MaskedInput, CurrencyInput, NumericInput, OTP, Rating, RangeSlider, MultiSelect and more
Layout: Sidebar, Accordion, Tabs, Resizable, Carousel, NavigationMenu, Breadcrumb
Overlays: Dialog, Sheet, Drawer, AlertDialog, ContextMenu, DropdownMenu, Toast, Popover, Tooltip, HoverCard, Command palette
Data: DataTable (with sorting, filtering, column pinning, virtualisation, tree rows, server-side), Filter builder, RichTextEditor, MarkdownEditor
Charts: 12 types including Candlestick, Gauge, Heatmap, Funnel, Radar
Animation: Declarative Motion system with 20+ presets, scroll-triggered, spring physics

15 headless primitives for every complex interaction pattern

3,200+ icons across three packages: Lucide (1,640), Heroicons (1,288), Feather (286)

Built-in localisation via ILocalizer — works across Server, WebAssembly, and Auto modes

Full .NET 10 support with Auto rendering mode — fast server-side initial load, seamless WebAssembly takeover

Getting started

There are two paths depending on whether you're starting fresh or adding NeoUI to an existing project.

New project — use the template

If you're starting a new Blazor app, the NeoUI project template is by far the fastest path. One command scaffolds a complete production-ready app with sidebar layout, theme switcher, dark mode toggle, Spotlight command palette (Ctrl+K), and a full Tailwind CSS v4 pipeline pre-wired — all supporting .NET 10's Auto, Server, or WebAssembly rendering modes.

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

The Tailwind build runs automatically on every dotnet build — Node.js just needs to be on your PATH. No manual configuration.

The template supports all three rendering modes as a first-class option:

dotnet new neoui -n MyApp                    # Auto (default) — Server + WASM
dotnet new neoui -n MyApp -in Server         # Server-side only, single project
dotnet new neoui -n MyApp -in WebAssembly    # WebAssembly only
dotnet new neoui -n MyApp --empty            # Auto, skip sample pages

What you get out of the box:

Component	What it does
`Sidebar`	Collapsible sidebar with icon-only collapsed state
`ThemeSwitcher`	Runtime base color selector
`DarkModeToggle`	Light / dark / system mode toggle
`SpotlightCommandPalette`	`Ctrl+K` command palette
`ReconnectModal`	Custom SignalR reconnect UI (Server + Auto)
`AppLoader`	WASM initialization progress overlay

Auto and WebAssembly modes scaffold a two-project solution (MyApp + MyApp.Client). Server mode is a single project.

Existing project — manual install

Adding NeoUI to an existing Blazor project takes about five minutes. The primary package is all you need — primitives and all three icon libraries come along as transitive dependencies.

1. Install the package

dotnet add package NeoUI.Blazor --version 3.6.7

2. Add namespace imports to _Imports.razor

@using NeoUI.Blazor
@using NeoUI.Blazor.Services
@using NeoUI.Icons.Lucide      @* optional but highly recommended — 1,640 icons *@

Chart components live in their own sub-namespace — add @using NeoUI.Blazor.Charts to any file that uses them.

3. Register services in Program.cs

using NeoUI.Blazor.Extensions;
using NeoUI.Blazor.Primitives.Extensions;

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

For Auto and WebAssembly projects, register in both the server and client Program.cs files.

4. Add CSS references to App.razor

<head>
    <!-- Pre-built NeoUI styles — no Tailwind setup required -->
    <link rel="stylesheet" href="@Assets["_content/NeoUI.Blazor/components.css"]" />

    <!-- Pick one base color and one primary color -->
    <link rel="stylesheet" href="@Assets["_content/NeoUI.Blazor/css/themes/base/zinc.css"]" />
    <link rel="stylesheet" href="@Assets["_content/NeoUI.Blazor/css/themes/primary/blue.css"]" />

    <!-- Prevents flash of unstyled content on page load -->
    <script src="@Assets["_content/NeoUI.Blazor/js/theme.js"]"></script>
</head>

The @Assets[...] directive is the .NET 10 way to reference static web assets — it adds a fingerprint hash for automatic cache invalidation on each deployment. To enable the full ThemeSwitcher with all 85 runtime theme combinations, include all base and primary theme files (see the Theming guide).

5. Add portal hosts to MainLayout.razor

Overlay and notification components render outside the component tree via a portal system. All four hosts belong at the end of your layout, after @Body and outside any scrollable or clipping container:

@inherits LayoutComponentBase

<div class="min-h-screen bg-background">
    @Body
</div>

<ToastViewport />
<DialogHost />
<ContainerPortalHost />
<OverlayPortalHost />

Each host has a specific role:

ToastViewport — renders toast notifications (position configurable)
DialogHost — required for programmatic DialogService usage
ContainerPortalHost — inline overlays: Popover, Tooltip, DropdownMenu
OverlayPortalHost — full-screen overlays: Dialog, Sheet, Drawer

6. Start building

<Button>Default</Button>
<Button Variant="ButtonVariant.Outline">Outline</Button>
<Button Variant="ButtonVariant.Secondary">Secondary</Button>

<Dialog>
    <DialogTrigger AsChild>
        <Button Variant="ButtonVariant.Outline">Open Dialog</Button>
    </DialogTrigger>
    <DialogContent>
        <DialogHeader>
            <DialogTitle>Welcome to NeoUI</DialogTitle>
            <DialogDescription>Beautiful Blazor components inspired by shadcn/ui.</DialogDescription>
        </DialogHeader>
        <DialogFooter>
            <DialogClose AsChild>
                <Button Variant="ButtonVariant.Outline">Close</Button>
            </DialogClose>
        </DialogFooter>
    </DialogContent>
</Dialog>

No Tailwind. No Node.js. No build tools. Just install and build.

Why now

.NET 10's Auto rendering mode changes what's possible with Blazor. The old friction of choosing between Server and WebAssembly — fast load vs rich interactivity — disappears. Auto mode gives you both: server-rendered first load, WebAssembly takeover after download, seamless to the user.

NeoUI is built for this from the ground up. Every component, the portal system, the theme layer, and the project template all support Auto, Server, and WebAssembly equally. The template scaffolds the two-project Auto solution structure correctly by default — something that's surprisingly fiddly to set up manually.

The timing feels right. Blazor has matured. .NET 10 is compelling. The component library ecosystem just needed something that treated Blazor developers as first-class citizens with first-class taste.

Built for agents and AI-assisted development

Here's something most component libraries haven't thought about yet: your AI coding assistant is only as useful as the documentation it can read.

NeoUI ships a complete set of LLM-optimised docs at neoui.io/llms.txt — structured specifically for consumption by Claude, GitHub Copilot, GPT, and other AI coding tools. This isn't an afterthought. It's a structured documentation index covering every part of the library:

Getting Started   : https://neoui.io/llms/getting-started.txt
Installation      : https://neoui.io/llms/installation.txt
Components        : https://neoui.io/llms/components.txt
Full Reference    : https://neoui.io/llms/components-full.txt
DataGrid          : https://neoui.io/llms/datagrid.txt
Theming           : https://neoui.io/llms/theming.txt
Architecture      : https://neoui.io/llms/architecture.txt
Primitives        : https://neoui.io/llms/primitives.txt
Templates         : https://neoui.io/llms/templates.txt
Patterns          : https://neoui.io/llms/patterns.txt
Icons             : https://neoui.io/llms/icons.txt
Blocks            : https://neoui.io/llms/blocks.txt
Changelog         : https://neoui.io/llms/changelog.txt

In practice this means when you ask Claude Code or Copilot to "add a server-side DataGrid with sorting and filtering", it generates correct NeoUI code — accurate component names, correct parameter casing, the right service registration — instead of hallucinating APIs that don't exist.

The patterns.txt file alone is worth bookmarking. It covers the real-world scenarios developers actually hit: validated forms, server-side DataGrid, programmatic DialogService, runtime theme switching, SidebarProvider with static rendering, keyboard shortcuts, loading/error/empty state patterns, and the render mode gotchas that trip up most Blazor developers new to Auto mode. Here's a taste — the complete validated login form pattern:

<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; } = "";
    }
}

This is what "built for agents" actually means — not a marketing claim, but documented patterns that make AI-assisted development with NeoUI accurate from the first prompt. As agentic coding workflows become standard, the libraries that invested in machine-readable documentation early will have a significant advantage. NeoUI is already there.

What's next

NeoUI is already shipping fast — v3.7.0 (released March 22, 2026) introduced Sidebar Pill Mode, which collapses the sidebar into a floating pill-shaped nav bar on desktop, with five new companion components (SidebarPillNav, SidebarPillNavItem, SidebarPillFade, SidebarPillInset, SidebarPillSpacer). All changes are additive and fully backward-compatible. The roadmap ahead includes:

Figma kit — design tokens and component specs aligned to NeoUI's design system
More primitives — expanding the headless layer with additional accessibility primitives
Blocks — pre-built full-page sections and layout patterns (already in early preview at neoui.io/blocks)
AI-assisted components — exploring integration points for AI-powered form validation and content generation

The project is open source, MIT licensed, and actively maintained. Contributions, issues, and feedback are all welcome.

DEV Community: Jimmy Petrus

The beauty of component composability — and why NeoUI does it differently

The traditional approach — and where it breaks

Enter composability

Sortable in NeoUI — the basic case

Now the interesting part — composing with DataTable

Taking composability further — `SortableScope<TItem>`

The same pattern with DataView

The architecture behind this: the two-layer model

The overlay: a detail worth appreciating

Why this matters beyond drag-and-drop

Using Sortable in your project

Links

I wanted shadcn/ui for Blazor. It didn’t exist. So I built it.

The shadcn/ui moment

The Blazor gap

What NeoUI is (and isn't)

Architecture: the two-layer model

shadcn/ui vs NeoUI — side by side

shadcn/ui (React)

NeoUI (Blazor)

Another example: Select

shadcn/ui (React)

NeoUI (Blazor)

Headless primitive: Dialog

Theming: drop in any shadcn/ui theme

What's inside

Getting started

New project — use the template

Existing project — manual install

Why now

Built for agents and AI-assisted development

What's next

Links

DEV Community: Jimmy Petrus

The beauty of component composability — and why NeoUI does it differently

The traditional approach — and where it breaks

Enter composability

Sortable in NeoUI — the basic case

Now the interesting part — composing with DataTable

Taking composability further — SortableScope<TItem>

The same pattern with DataView

The architecture behind this: the two-layer model

The overlay: a detail worth appreciating

Why this matters beyond drag-and-drop

Using Sortable in your project

Links

I wanted shadcn/ui for Blazor. It didn’t exist. So I built it.

The shadcn/ui moment

The Blazor gap

What NeoUI is (and isn't)

Architecture: the two-layer model

shadcn/ui vs NeoUI — side by side

shadcn/ui (React)

NeoUI (Blazor)

Another example: Select

shadcn/ui (React)

NeoUI (Blazor)

Headless primitive: Dialog

Theming: drop in any shadcn/ui theme

What's inside

Getting started

New project — use the template

Existing project — manual install

Why now

Built for agents and AI-assisted development

What's next

Links

Taking composability further — `SortableScope<TItem>`