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:
dotnet new install RizzyUI.Templates
dotnet new rizzyui -o MyApp
cd MyApp
dotnet runThe 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 versions
Each template release pins the RizzyUI NuGet package and the @jalexsocial/rizzyui npm package to its own version. To pick up a newer RizzyUI for new projects, run dotnet new install RizzyUI.Templates again.
Template Options
| Option | Values | Description |
|---|---|---|
-f, --framework | net10.0 (default), net11.0 | The target framework. |
--theme | Arctic (default), Vercel | The RizzyUI theme set in Program.cs. See Themes. |
--no-restore | flag | Skip 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.
| Path | What it does |
|---|---|
Program.cs | Registers Rizzy and RizzyUI, sets the theme, maps the controllers and the fragment endpoints. |
Components/Layout/AppLayout.razor | The HTML document: the stylesheet, <RzHeadOutlet />, <RzScripts /> (htmx and Rizzy), rizzyui.js, and RzThemeProvider. |
Components/Layout/MainLayout.razor | The page shell: RzSidebarProvider, the header with the sidebar trigger and dark mode toggle, and the content area. |
Components/Layout/AppSidebar.razor | The sidebar navigation. Add your pages to its Items list. |
Features/Home | The dashboard: stat cards, a table, and an activity feed loaded after the page. |
Features/Customers | A searchable, paged table. The search box and pager fetch only the table. |
Features/Settings | A validated form posted with htmx. Invalid input comes back with status 422 and the errors next to each field. |
Features/Activity | Minimal API endpoints that return htmx fragments. |
Features/Errors | The 404 and error pages. |
Styles/app.css | The 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:
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) });
}<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:
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.
[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 });
}<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
- Create a folder under
Features, for exampleFeatures/Reports. - Add a component,
ReportsPage.razor, with your markup. - Add a controller that returns it.
- Add the page to the
Itemslist inComponents/Layout/AppSidebar.razor.
public sealed class ReportsController : RzController
{
[HttpGet("/reports")]
public IResult Index() => View<ReportsPage>();
}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:
npm run watch:cssStyles/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.
@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.