HTMX helper library for ASP.NET Core MVC applications. Provides SwapController base class, middleware, event helpers, and extension methods for seamless HTMX integration. (Realtime features moved to Swap.Htmx.Realtime.)
public class ProductsController : SwapController
{
public IActionResult Index()
{
var products = GetProducts();
return SwapView(products); // Auto-detects HTMX vs full page
}
[HttpPost]
public IActionResult Add(Product product)
{
SaveProduct(product);
return SwapResponse()
.WithView("_ProductRow", product) // Main response
.AlsoUpdate("product-count", "_Count", GetCount()) // OOB update
.WithSuccessToast("Product added!") // Toast notification
.Build();
}
}
That's it! You're ready to build interactive UIs.
Core Concepts
1. SwapController & SwapView
SwapController auto-detects HTMX requests:
public class HomeController : SwapController
{
public IActionResult Index()
{
// Normal request → View with layout
// HTMX request → PartialView (no layout)
return SwapView(model);
}
}
Don't want to inherit? Use extensions:
public class HomeController : Controller
{
public IActionResult Index()
{
return this.SwapView(model); // Extension method
}
}
Instead: Use event handlers or let components refresh themselves:
<div hx-get="/notifications" hx-trigger="load, every 30s"></div>
7. Performance & Security
OOB swaps render in parallel. When a response contains multiple AlsoUpdate() calls, all partial views are rendered concurrently via Task.WhenAll(). A dashboard with 12+ OOB swaps benefits from this — ordering is preserved.
Target IDs are validated. IDs must start with a letter and contain only letters, digits, hyphens, and underscores. Invalid IDs (XSS payloads, empty strings, special characters) throw ArgumentException at build time, not at render time.
Redirect URLs are validated.WithRedirect() and WithNavigation() reject javascript:, data:, and vbscript: URL schemes.
Feature Reference
Feature
Usage
Auto HTMX detection
SwapView() / this.SwapView()
Multiple updates
SwapResponse().AlsoUpdate()
SPA navigation
<swap-nav to="/path">
State management
<swap-state> + [FromSwapState]
Toast notifications
.WithSuccessToast(), .WithErrorToast()
Client events
.WithTrigger("eventName")
Event handlers
ISwapEventHandler<T>
Form validation
<swap-validation> + SwapValidationErrors()
Real-time (SSE)
ServerSentEvents()
Real-time (WebSocket)
WebSocket registry
Source generators
[SwapEventSource], auto SwapViews/SwapElements
Source Generators
Eliminate magic strings with compile-time code generation:
1. Type-Safe Event Keys
// Define your events
[SwapEventSource]
public static partial class CartEvents
{
public const string ItemAdded = "cart.itemAdded";
public const string CheckoutCompleted = "cart.checkoutCompleted";
}
// Generated at build time:
// CartEvents.Cart.ItemAdded → EventKey("cart.itemAdded")
// CartEvents.Cart.CheckoutCompleted → EventKey("cart.checkoutCompleted")
// Use in controller
return SwapEvent(CartEvents.Cart.ItemAdded, item).Build();
2. Auto-Generated View & Element Constants (Zero Config)
With zero configuration, the generators scan your .cshtml files and group by controller folder:
// Auto-generated from your views
public static class SwapViews
{
public static class Products
{
public const string Index = "Index";
public const string Details = "Details";
public const string _Grid = "_Grid"; // Partials keep underscore
public const string _Pagination = "_Pagination";
}
}
public static class SwapElements
{
public const string ProductGrid = "product-grid";
public const string CartCount = "cart-count";
}
// Use instead of magic strings
builder.AlsoUpdate(SwapElements.CartCount, SwapViews.Cart._Count, count);
3. Setup (Zero Config!)
No configuration required! The Swap.Htmx.targets auto-includes common folders:
Views/**/*.cshtml
Modules/**/Views/**/*.cshtml
Pages/**/*.cshtml
Components/**/*.cshtml
Areas/**/Views/**/*.cshtml
Just reference Swap.Htmx and build — views are scanned automatically.
