RizzyUI

Getting Started

The quickest way to start is the dotnet new rizzyui template. It creates an ASP.NET Core app with a sidebar layout, a few starter pages, and the Tailwind CSS build already wired up, so you can run it and start replacing the sample pages with your own.

Requirements

  • The .NET 10 SDK or later.
  • Node.js 20 or later. RizzyUI is styled with Tailwind CSS, which the project builds with npm.

Create a Project

Install the template package once, then create and run an app:

Terminal
dotnet new install RizzyUI.Templates
dotnet new rizzyui -o MyApp
cd MyApp
dotnet run

The first build runs npm install, and every build compiles Styles/app.css to wwwroot/css/app.css. Open the URL that dotnet run prints.

Template Options

OptionValuesDescription
-f, --frameworknet10.0 (default), net11.0The target framework.
--themeArctic (default), VercelThe RizzyUI theme set in Program.cs. See Themes.
--no-restoreflagSkip dotnet restore after the project is created.

What's in the Project

The app is server-rendered: pages are Razor components returned from controllers, htmx swaps parts of the page, and Alpine.js (loaded by RizzyUI) handles behavior in the browser such as the sidebar and dialogs.

PathWhat it does
Program.csRegisters Rizzy and RizzyUI, sets the theme, maps the controllers and the fragment endpoints.
Components/Layout/AppLayout.razorThe HTML document: the stylesheet, <RzHeadOutlet />, <RzScripts /> (htmx and Rizzy), rizzyui.js, and RzThemeProvider.
Components/Layout/MainLayout.razorThe page shell: RzSidebarProvider, the header with the sidebar trigger and dark mode toggle, and the content area.
Components/Layout/AppSidebar.razorThe sidebar navigation. Add your pages to its Items list.
Features/HomeThe dashboard: stat cards, a table, and an activity feed loaded after the page.
Features/CustomersA searchable, paged table. The search box and pager fetch only the table.
Features/SettingsA validated form posted with htmx. Invalid input comes back with status 422 and the errors next to each field.
Features/ActivityMinimal API endpoints that return htmx fragments.
Features/ErrorsThe 404 and error pages.
Styles/app.cssThe Tailwind entry point. It imports RizzyUI's theme and plugin from the npm package.

Pages and Fragments

A page is a Razor component that a controller action returns with View<T>(). Rizzy wraps it in MainLayout for normal requests and boosted navigation. A fragment is a component returned with PartialView<T>(); htmx swaps it into the element named by hx-target. The customers page uses both:

Features/Customers/CustomersController.cs
public sealed class CustomersController(CustomerStore store) : RzController
{
    // The full page: the layout, the search box and the first page of results.
    [HttpGet("/customers")]
    public IResult Index(string? q, int page = 1) =>
        View<CustomersPage>(new { Result = store.Search(q, page) });

    // Only the table, for the search box and the pager.
    [HttpGet("/customers/table")]
    public IResult Table(string? q, int page = 1) =>
        PartialView<CustomerTable>(new { Result = store.Search(q, page) });
}
Features/Customers/CustomersPage.razor
<input type="search" name="q"
       hx-get="/customers/table"
       hx-trigger="input changed delay:300ms, search"
       hx-target="#customer-table"
       hx-swap="outerHTML" />

<CustomerTable Result="Result" />

Minimal API endpoints render components the same way through IRizzyService, so endpoints and controllers can share components:

Features/Activity/ActivityEndpoints.cs
var fragments = endpoints.MapGroup("/fragments");

fragments.MapGet("/activity", ([FromServices] IRizzyService rizzy) =>
    rizzy.PartialView<ActivityFeed>(new { Items = LoadActivity() }));

Forms and Validation

The settings form posts with hx-post. The controller validates the model; on errors it answers with status 422 and the form again, which htmx swaps in place. RzModelStateProvider shows each error next to its field, and each input shows the value the user posted. The antiforgery token is added to htmx requests for you.

Features/Settings/SettingsController.cs
[HttpPost("/settings"), ValidateAntiForgeryToken]
public IResult Save([FromForm] ProfileSettings profile)
{
    if (!ModelState.IsValid)
    {
        // 422 with the form and its errors.
        // htmx 4 swaps 4xx responses into the target.
        Response.Htmx().ValidationFailed();
        return PartialView<SettingsForm>();
    }

    // Save the profile here.
    return PartialView<SettingsForm>(new { Saved = true });
}
Features/Settings/SettingsForm.razor
<EditForm Model="Profile" FormName="Profile"
          hx-post="/settings"
          hx-target="#settings-form"
          hx-swap="outerHTML">
    <RzModelStateProvider />

    <Field>
        <FieldLabel For="@(() => Profile!.Email)" />
        <RzInputText For="@(() => Profile!.Email)"
                     Role="TextRole.Email" />
        <RzValidationMessageBase For="@(() => Profile!.Email)"
                                 class="text-destructive text-sm" />
    </Field>

    <RzButton type="submit">Save profile</RzButton>
</EditForm>

Add a Page

  1. Create a folder under Features, for example Features/Reports.
  2. Add a component, ReportsPage.razor, with your markup.
  3. Add a controller that returns it.
  4. Add the page to the Items list in Components/Layout/AppSidebar.razor.
Features/Reports/ReportsController.cs
public sealed class ReportsController : RzController
{
    [HttpGet("/reports")]
    public IResult Index() => View<ReportsPage>();
}
Components/Layout/AppSidebar.razor
private static readonly NavItem[] Items =
[
    new("Dashboard", "/", Lucide.LayoutDashboard),
    new("Customers", "/customers", Lucide.Users),
    new("Reports", "/reports", Lucide.ChartBar),
    new("Settings", "/settings", Lucide.Settings),
];

Styling

Tailwind scans the project for class names on every build. While you edit markup, keep it watching in a second terminal so new classes show up without a rebuild:

Terminal
npm run watch:css

Styles/app.css imports RizzyUI's plugin, which brings the theme tokens, the dark mode variant, and the classes RizzyUI's components use. Add your own CSS below the imports.

Styles/app.css
@import "tailwindcss";
@import "@jalexsocial/rizzyui/dist/css/rizzyui-plugin.css";

@plugin "@tailwindcss/forms";

To build without Node.js (for example in a .NET-only CI step that already has the compiled CSS), pass -p:SkipTailwind=true.

Next Steps

  • Browse the components and copy examples into your pages.
  • Change the look with a different theme.
  • Add browser behavior with Alpine.js: start with Interactivity.
  • Adding RizzyUI to an existing app instead? Follow the installation steps in the README.