Getting Started

Get up and running with NeoUI in your Blazor project in minutes. No Tailwind CSS setup required.

New Project? Use the Template

The NeoUI project template scaffolds a complete Blazor app with all components, layout, and Tailwind CSS pre-wired — skip the manual steps below entirely:

Terminal

$ dotnet new install NeoUI.Blazor.Templates && dotnet new neoui -n MyApp

View template docs →

1. Install the Package

Install NeoUI.Blazor from NuGet. It automatically includes the Primitives layer and all three icon libraries.

Terminal

$ dotnet add package NeoUI.Blazor --version 4.0.0

2. Add Namespace Imports

Add the following to your _Imports.razor. These two lines cover every styled component and service for most projects:

RZ_Imports.razor

@using NeoUI.Blazor
@using NeoUI.Blazor.Services

All components and their enums (e.g. ButtonVariant, InputType) live in the single NeoUI.Blazor namespace — no per-component imports needed.

Optional: Lucide Icons (highly recommended)

@using NeoUI.Icons.Lucide      @* 1,640+ high-quality stroke icons *@

Optional: Primitives (for custom headless styling only)

@using NeoUI.Blazor.Primitives
@using NeoUI.Blazor.Primitives.Services

Only add these if you are building your own styled components on top of the headless Primitives layer. They are not needed when using NeoUI.Blazor styled components.

Chart Components

Chart components live in their own sub-namespace. Add @using NeoUI.Blazor.Charts to any file or global imports file that uses chart components.

3. Register Services

C#Program.cs

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

// Server project (Program.cs)
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents()
    .AddInteractiveWebAssemblyComponents();

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

4. Add CSS References

Add the pre-built NeoUI stylesheet to your App.razor. The @Assets[...] directive is the .NET 10 way to reference static web assets — it adds a fingerprint hash to the URL for automatic cache invalidation on each deployment. No Tailwind installation or build process required.

RZApp.razor

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

    <!-- 2. Base color (pick one of 10) -->
    <link rel="stylesheet" href="@Assets["_content/NeoUI.Blazor/css/themes/base/zinc.css"]" />

    <!-- 3. Primary accent color (pick one of 17) -->
    <link rel="stylesheet" href="@Assets["_content/NeoUI.Blazor/css/themes/primary/blue.css"]" />

    <!-- 4. Style variant — optional, pick one (vega · nova · maia · lyra · mira · luma) -->
    <!-- <link rel="stylesheet" href="@Assets["_content/NeoUI.Blazor/css/themes/styles/nova.css"]" /> -->

    <!-- 5. Radius preset — optional, pick one (none · small · large) -->
    <!-- <link rel="stylesheet" href="@Assets["_content/NeoUI.Blazor/css/themes/radius/small.css"]" /> -->

    <!-- 6. Font preset — optional, pick one (inter · geist · calsans · dmsans · plusjakarta) -->
    <!-- <link rel="stylesheet" href="@Assets["_content/NeoUI.Blazor/css/themes/fonts/geist.css"]" /> -->

    <!-- 8. Theme initialization script (must be last — prevents FOUC) -->
    <script src="@Assets["_content/NeoUI.Blazor/js/theme.js"]"></script>
</head>

Dynamic Theme Switching

To enable the ThemeSwitcher component (170 color combinations at runtime), include all base, primary, style variant, radius, and font files. See the Theming guide for details.

5. Add AppProvider & Portal Hosts

AppProvider (new in v4) wraps your layout content and provides Theme v2's StyleVariant cascading value to all child components. Portal hosts go inside AppProvider so toasts, dialogs, popovers, and drawers inherit the active style variant. Place them after @Body, still inside AppProvider but outside any scrollable or clipping container:

RZMainLayout.razor

@inherits LayoutComponentBase

@* AppProvider is required for Theme v2 — provides StyleVariant CascadingValue to all components.
   Portal hosts go INSIDE AppProvider so toasts/dialogs/popovers inherit the active style variant. *@
<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

ToastViewport — renders toast notification messages. Position is configurable (e.g. BottomRight, TopCenter).
DialogHost — required when using DialogService for programmatic dialogs.
ContainerPortalHost — inline overlays: Popover, Tooltip, DropdownMenu.
OverlayPortalHost — full-screen overlays: Dialog, Sheet, Drawer.

6. Start Using Components

That's it — you're ready to build:

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

<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>

New

Error

Next Steps

Installation

All packages and install options explained.

Theming

170 color combinations and custom CSS themes.

Components

Browse 100+ components with live examples.