GitHub

Getting Started

htmxRazor is a library of server-rendered UI components for ASP.NET Core. Every component is a Tag Helper that outputs semantic HTML with CSS custom properties for theming and first-class htmx attribute support.

Installation

Add the htmxRazor NuGet package to your project:

dotnet add package htmxRazor

Configuration

Register htmxRazor services and middleware in your Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddhtmxRazor();

var app = builder.Build();

app.UseStaticFiles();
app.UsehtmxRazor();      // Serves component CSS, JS, and htmx from /_rhx/
app.MapRazorPages();

app.Run();

AddhtmxRazor() registers the tag helper component that auto-injects design tokens, reset, core, and utility CSS plus the htmx script into every page's <head>.

UsehtmxRazor() sets up the embedded file provider that serves all component assets from the /_rhx/ path.

Register Tag Helpers

Add the htmxRazor tag helpers to your _ViewImports.cshtml:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, htmxRazor

Import Component CSS

AddhtmxRazor() auto-injects the foundation stylesheets (design tokens, reset, core utilities, and theme) into every page's <head>. However, each component has its own CSS file that you must import separately.

Add <link> tags in your _Layout.cshtml for the components you use: 

<head>
    <!-- Foundation CSS is auto-injected by AddhtmxRazor() -->

    <!-- Import CSS for each component you use -->
    <link rel="stylesheet" href="/_rhx/css/components/rhx-button.css" />
    <link rel="stylesheet" href="/_rhx/css/components/rhx-input.css" />
    <link rel="stylesheet" href="/_rhx/css/components/rhx-dialog.css" />
    <!-- Add more as needed -->
</head>

The naming convention is /_rhx/css/components/rhx-{component}.css. For example:

Tip: Without component CSS, your components will render correctly but appear unstyled. If a component looks generic, check that you've imported its CSS file.

Some components with interactive behavior also need their JavaScript file: 

<script src="/_rhx/js/components/rhx-dialog.js" defer></script>
<script src="/_rhx/js/components/rhx-tabs.js" defer></script>

Your First Component

With the button CSS imported, use the <rhx-button> tag helper in any Razor page: 

<!-- In _Layout.cshtml <head> -->
<link rel="stylesheet" href="/_rhx/css/components/rhx-button.css" />

<!-- In your Razor page -->
<rhx-button rhx-variant="brand">Click Me</rhx-button>

This renders as:

Theming

htmxRazor supports light and dark themes via the data-rhx-theme attribute on the <html> element. Toggle between themes using the built-in JavaScript function: 

<html data-rhx-theme="light">

<!-- Toggle with JavaScript -->
<button onclick="RHX.toggleTheme()">Toggle Theme</button>

All components use CSS custom properties (design tokens) that automatically adapt to the active theme. You can override any token in your own CSS.

htmx Integration

Every htmxRazor component natively supports htmx attributes. Simply add hx-get, hx-post, hx-target, hx-swap, and other htmx attributes directly on any component tag: 

<rhx-button rhx-variant="brand"
            hx-get="/api/greeting"
            hx-target="#result"
            hx-swap="innerHTML">
    Load Greeting
</rhx-button>

<rhx-input rhx-label="Search"
           hx-get="/search"
           hx-trigger="input changed delay:300ms"
           hx-target="#results" />

The htmx script is automatically injected by AddhtmxRazor() — no additional script tags needed.

What's Next

Explore the component reference to learn about each component's properties, examples, and accessibility features: