htmxRazor 1.3.0

htmxRazor

[](https://dotnet. microsoft.com/)

Server-rendered UI components for ASP.NET Core with first-class htmx integration.

htmxRazor is a complete UI component library implemented as Razor Tag Helpers. Every component renders clean, semantic HTML styled by its own CSS design system. No client-side framework required — just add htmx attributes to any component for dynamic behavior.

Why htmxRazor?

• Server-rendered — No JavaScript framework. Components are Tag Helpers that render HTML on the server.
• htmx-native — Every component supports hx-get, hx-post, hx-target, hx-swap, and all htmx attributes directly.
• 80+ components — Buttons, forms, data tables, dialogs, command palette, tabs, trees, carousels, toasts, pagination, and more across 11 categories.
• Design tokens — Light/dark themes via CSS custom properties. Toggle with data-rhx-theme or RHX.toggleTheme().
• Accessible — Semantic HTML, ARIA attributes, keyboard navigation, and screen reader support built in.
• Model binding — Form components integrate with ASP.NET Core model binding, validation, and ModelExpression.
• Zero config — One NuGet package. Two lines of setup. Start using components immediately.

Quick Start

1. Install

dotnet add package htmxRazor

2. Configure

// Program.cs
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();

3. Register Tag Helpers

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

4. Use Components

<rhx-button rhx-variant="brand" rhx-size="large">
    Save Changes
</rhx-button>

Feature Highlights

Buttons with Every Variant

<rhx-button rhx-variant="brand">Brand</rhx-button>
<rhx-button rhx-variant="success" rhx-appearance="outlined">Success</rhx-button>
<rhx-button rhx-variant="danger" rhx-appearance="plain">Delete</rhx-button>
<rhx-button rhx-variant="brand" rhx-pill="true">Pill Shape</rhx-button>
<rhx-button rhx-variant="brand" rhx-loading="true">Saving...</rhx-button>

Form Controls with Model Binding

<rhx-input rhx-for="Email" rhx-with-clear="true" />

<rhx-input rhx-label="Password"
           rhx-type="password"
           rhx-password-toggle="true"
           name="password" />

htmx on Any Component

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


<rhx-button rhx-variant="danger"
            hx-delete="/api/items/42"
            hx-confirm="Are you sure?"
            hx-target="#item-list"
            hx-swap="outerHTML">
    Delete
</rhx-button>

Modal Dialogs

<rhx-button rhx-variant="brand" data-rhx-dialog-open="edit-dialog">
    Edit Profile
</rhx-button>

<rhx-dialog id="edit-dialog" rhx-label="Edit Profile">
    <rhx-input rhx-for="DisplayName" />
    <rhx-dialog-footer>
        <rhx-button rhx-variant="neutral" rhx-appearance="outlined"
                    onclick="this.closest('dialog').close()">Cancel</rhx-button>
        <rhx-button rhx-variant="brand" type="submit">Save</rhx-button>
    </rhx-dialog-footer>
</rhx-dialog>

Data Tables with Server-Driven Sort & Pagination

<rhx-data-table id="products" rhx-striped="true" rhx-hoverable="true"
                rhx-sort-url="/Products?handler=TableData"
                rhx-label="Product list">
    <rhx-column rhx-field="name" rhx-header="Name" rhx-sortable="true" />
    <rhx-column rhx-field="price" rhx-header="Price" rhx-sortable="true" />
    <rhx-column rhx-field="stock" rhx-header="Stock" />
    @foreach (var p in Model.Items)
    {
        <tr><td>@p.Name</td><td>@p.Price</td><td>@p.Stock</td></tr>
    }
    <rhx-data-table-pagination rhx-page="1" rhx-page-size="10"
        rhx-total-items="@Model.TotalItems"
        rhx-url="/Products?handler=TableData"
        rhx-target="#products-body" />
</rhx-data-table>

Command Palette (Cmd+K Search)

<rhx-command-palette id="search"
    rhx-placeholder="Search components..."
    hx-get="/Search"
    rhx-debounce="200">
</rhx-command-palette>


<rhx-command-group rhx-heading="Pages">
    <rhx-command-item rhx-value="home" rhx-href="/" rhx-icon="home">
        Home
    </rhx-command-item>
</rhx-command-group>

Theming

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


<rhx-button onclick="RHX.toggleTheme()">Toggle Theme</rhx-button>


<style>
  :root {
    --rhx-color-brand-500: #6366f1;
    --rhx-radius-md: 0.75rem;
  }
</style>

Component Catalog

How It Compares

Solution Structure

Development

# Build
dotnet build

# Run tests
dotnet test

# Run the demo site
dotnet run --project htmxRazor.Demo

# Pack for NuGet
dotnet pack htmxRazor/htmxRazor.csproj --configuration Release

Design System

htmxRazor owns its entire rendering and styling stack:

• CSS Custom Properties for design tokens (colors, spacing, typography, borders, shadows)
• BEM naming with rhx- prefix (rhx-button, rhx-button--brand, rhx-button__label)
• Light/dark themes via data-rhx-theme attribute on <html>
• Utility classes for layout and spacing (rhx-flex, rhx-gap-md, rhx-p-lg)
• Auto-injected assets — AddhtmxRazor() injects tokens, reset, core, and utilities CSS plus the htmx script into <head>

The project uses a custom CSS design system — not Bootstrap or any other CSS framework.

Key details from the codebase instructions:

• BEM naming convention with an rhx- prefix (e.g., .rhx-button, .rhx-button--loading, .rhx-button__icon)
• CSS custom properties (design tokens) defined in rhx-tokens.css — things like --rhx-color-brand-500, --rhx-radius-md, --rhx-font-size-base
• Light/dark theme support via a data-rhx-theme attribute on <html>
• Each component has its own scoped CSS file in Assets/css/components/
• All CSS is embedded and served at /_rhx/ — no external dependencies
• Hardcoded values are not allowed; everything references var(--rhx-*) tokens

It's a fully self-contained design system built specifically for this component library.

Roadmap

Features ranked by user impact and implementation effort. The library is at v1.3.0 with 80+ components; the roadmap below covers what comes next.

v1.2 — Notifications, Pagination & Quick Wins (Shipped)

• Toast Notification System — <rhx-toast-container> + <rhx-toast> with auto-dismiss, severity variants, stacking, and aria-live announcements.
• Pagination — <rhx-pagination> with htmx-powered page navigation, ellipsis, first/last/prev/next buttons, and size variants.
• ARIA Live Region Manager — <rhx-live-region> for screen reader announcements on htmx swaps.
• CSS Cascade Layers — All component CSS wrapped in @layer for easy host app overrides without specificity wars.
• View Transition Support — rhx-transition and rhx-transition-name attributes for the View Transitions API.

v1.3 — Data Table, Accessibility & Modern CSS (Shipped)

• Data Table — <rhx-data-table>, <rhx-column>, <rhx-data-table-pagination> with server-driven sort, filter, and pagination. Includes DataTableRequest model binder auto-registered via AddhtmxRazor().
• Command Palette — <rhx-command-palette> modal search overlay activated via Cmd+K / Ctrl+K with debounced hx-get, grouped results via <rhx-command-group> and <rhx-command-item>, and full keyboard navigation.
• Focus Management After Swaps — rhx-focus-after-swap attribute on the base class. On by default for <rhx-dialog> and <rhx-drawer> (WCAG 2.4.3).
• Skip Nav & Landmarks — <rhx-skip-nav> and <rhx-landmark> for semantic page regions (WCAG 2.4.1).
• Container Queries — Card, dialog, split panel, and data table CSS use @container queries for container-responsive layouts.
• APG Keyboard Audit — Tabs, tree, dropdown, and combobox audited against W3C ARIA Authoring Practices Guide. Added type-ahead, * expand siblings, Alt+Arrow patterns.

v1.4 — Real-time, Wizard & Patterns

v2.0 — Platform & DX

Infrastructure Cleanup (ongoing)

Project Template

A .NET project template for htmxRazor is available in the templates/htmxRazor.Template directory. This template provides a clean starting point with:

• No jQuery or Bootstrap.
• Pre-configured Program.cs for htmxRazor.
• A base _Layout.cshtml including htmxRazor assets.
• A sample Index.cshtml demonstrating htmx and htmxRazor components.

Installation

You can install the template locally from the source or from a NuGet package.

To install the template locally from source, run the following command from the project root:

dotnet new install ./templates/htmxRazor.Template

Alternatively, you can pack and install from the template package:

dotnet pack templates/htmxRazor.Templates.csproj -o nupkg
dotnet new install nupkg/htmxRazor.Templates.1.3.0.nupkg

Usage

To create a new project using the template, run:

dotnet new htmxrazor -n YourProjectName

Contributing

See CONTRIBUTING.md for development setup, PR guidelines, and coding standards.

License

MIT - Copyright (c) 2026 Chris Woody Woodruff