Basic Usage Patterns

This guide covers common usage patterns for Htmx.Components. For installation and initial setup, see the Getting Started Guide.

Prerequisites

Htmx.Components installed and configured (see Getting Started)
Basic understanding of ASP.NET Core MVC and HTMX

Layout Integration

For setup instructions, see the Getting Started Guide. This section covers usage patterns.

JavaScript Behaviors

The <htmx-runtime> TagHelper provides a unified way to include the packaged Htmx.Components browser runtime:

<!-- Include all behaviors (default) -->
<htmx-runtime></htmx-runtime>

<!-- Include only specific behaviors -->
<htmx-runtime include-behaviors="page-state-headers,table-inline-editing"></htmx-runtime>

<!-- Exclude specific behaviors -->
<htmx-runtime exclude-behaviors="authentication-retry"></htmx-runtime>

Available Behaviors:

page-state-headers: Automatic page state management for HTMX requests
table-inline-editing: Enhanced table interactions and editing
blur-save-coordination: Prevents form submission race conditions
request-lifecycle: Default pending UI behavior for HTMX requests
error-handling: Scoped/global error display for HTMX failures
authentication-retry: Handles authentication retry with popup windows
modal: Opens HTMX-loaded modal dialogs, handles close triggers, resets modal body content, and restores focus

The behaviors are delivered by the packaged htmx-components.js static web asset with a small JSON configuration block emitted by the TagHelper.

The default runtime also registers the first-party custom elements used by components:

htmx-table: scopes table identity, edit state, and table lifecycle events
htmx-request-scope: applies pending UI to the relevant region during HTMX requests
htmx-error-region: receives safe, user-facing HTMX error messages

Set Up Tailwind CSS (Recommended)

Htmx.Components is designed to work with Tailwind CSS and DaisyUI for its default styling. The library package includes a Tailwind source file at content/extracted-css-classes.css so the component classes used by the Razor views are included in your app's generated CSS.

Create Build Tooling

Create a tools directory in your project root with the following files:

tools/package.json:

{
    "name": "build",
    "version": "1.0.0",
    "scripts": {
        "build:css": "npx tailwindcss -i input.css -o ../wwwroot/css/site.css --minify",
        "watch:css": "npx tailwindcss -i input.css -o ../wwwroot/css/site.css --watch"
    },
    "devDependencies": {
        "@tailwindcss/cli": "^4.1.10",
        "daisyui": "^5.0.46",
        "tailwindcss": "^4.1.10"
    }
}

tools/input.css:

@import "tailwindcss" source(none);
@source "../Views/**/*.{html,cshtml}";
@source "../wwwroot/**/*.{html,cshtml}";
@import "../../Htmx.Components/content/extracted-css-classes.css";
@plugin "daisyui";

Adjust the @import path if your application consumes Htmx.Components from a NuGet package cache rather than a sibling project or repository checkout.

Configure MSBuild Integration

Add the following to your .csproj file to automatically build Tailwind CSS during compilation.

  <!-- Tailwind CSS Build -->
  <PropertyGroup>
    <TailwindOutputFile>wwwroot/css/site.css</TailwindOutputFile>
    <TailwindInputFile>tools/input.css</TailwindInputFile>
  </PropertyGroup>
  <Target Name="BuildTailwind" AfterTargets="ResolveProjectReferences" Inputs="$(TailwindInputFile)" Outputs="$(TailwindOutputFile)">
    <Exec Command="npm run build:css" WorkingDirectory="tools" />
    <Touch Files="$(TailwindOutputFile)" AlwaysCreate="true" />
  </Target>

You might also want to ensure that npm packages are installed before building Tailwind CSS. Add the following target to your .csproj file:

  <!-- Only run npm install when package.json has been modified or .install-stamp doesn't exist -->
  <PropertyGroup>
    <NpmInstallStampFile>tools/node_modules/.install-stamp</NpmInstallStampFile>
  </PropertyGroup>
  <Target Name="EnsureNpmPackages" BeforeTargets="BuildTailwind" Inputs="tools/package.json" Outputs="$(NpmInstallStampFile)">
    <Exec Command="npm install" WorkingDirectory="tools" />
    <Touch Files="$(NpmInstallStampFile)" AlwaysCreate="true" />
  </Target>

Manual Build Commands

You can also run Tailwind CSS manually:

# Navigate to the tools directory
cd tools

# Install dependencies (first time only)
npm install

# Build CSS once
npm run build:css

# Watch for changes and rebuild automatically
npm run watch:css

Create Your First Controller

Create a controller with navigation attributes:

using Htmx.Components.NavBar;
using Microsoft.AspNetCore.Mvc;

public class HomeController : Controller
{
    [NavAction(DisplayName = "Home", Icon = "fas fa-home", Order = 0, PushUrl = true, ViewName = "_Content")]
    public IActionResult Index()
    {
        return Ok(new { message = "Welcome to your app!" });
    }
}

[Route("Admin")]
[NavActionGroup(DisplayName = "Admin", Icon = "fas fa-cogs", Order = 1)]
public class AdminController : Controller
{
    [HttpGet("Users")]
    [NavAction(DisplayName = "Users", Icon = "fas fa-users", Order = 0, PushUrl = true, ViewName = "_Users")]
    public IActionResult Users()
    {
        // Your logic here
        return Ok(new { });
    }
}

Create Views

Create corresponding view files:

Views/Home/_Content.cshtml:

<div id="main-content">
    <h1>Welcome to Your App</h1>
    <p>This content is loaded via HTMX!</p>
</div>

Views/Admin/_Users.cshtml:

<div id="admin-users">
    <h2>User Management</h2>
    <!-- Your user management UI here -->
</div>

What You Get

With this setup, you automatically get:

Dynamic Navigation: The NavBar component automatically discovers your [NavAction] and [NavActionGroup] decorated controller actions
HTMX Integration: Navigation uses HTMX for smooth page transitions without full reloads
Authentication Support: The AuthStatus component handles login/logout states
Page State Management: Browser history and URL updates work seamlessly
Table Components: Ready-to-use data table functionality (see advanced guides)

Next Steps

Getting Started - Complete installation and configuration guide
Tables - Interactive data tables with CRUD operations
Navigation - Advanced navigation patterns
Authorization - Permission-based access control
Authentication - OIDC and auth status management

For technical details and extension points, see the Developer Guide.

Key Features

Controller actions marked with [NavAction] are automatically registered in the navigation system. Group related actions using [NavActionGroup].

ViewComponent Integration

Components like NavBar and AuthStatus integrate seamlessly with ASP.NET Core's ViewComponent system.

HTMX Enhancement

The library provides out-of-the-box HTMX integration for dynamic content updates, form handling, and navigation.

Table of Contents