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 3.6.7

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>
    <!-- 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"]" />

    <!-- Theme initialization script (prevents flash of unstyled content) -->
    <script src="@Assets["_content/NeoUI.Blazor/js/theme.js"]"></script>
</head>

Dynamic Theme Switching

To enable the ThemeSwitcher component (85 color combinations at runtime), include all base and primary theme files. See the Theming guide for details.

5. Add Portal Hosts

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

RZMainLayout.razor

@inherits LayoutComponentBase

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

@* All four hosts must be outside any scrollable or clipping container *@
<ToastViewport />
<DialogHost />
<ContainerPortalHost />
<OverlayPortalHost />

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

85 color combinations and custom CSS themes.

Components

Browse 100+ components with live examples.