Rizzy Documentation
Rizzy Documentation

Getting Started

This document provides a comprehensive guide on setting up and configuring HTMX within your application using Rizzy.

To add the Rizzy.Htmx NuGet package to your project, follow these steps:

Installation

Install the NuGet Package

You can add the Rizzy.Htmx NuGet package using either Visual Studio or the .NET CLI.

Using Visual Studio

  1. Open your project in Visual Studio.
  2. Right-click on the Dependencies node in the Solution Explorer.
  3. Select Manage NuGet Packages.
  4. In the NuGet Package Manager, search for Rizzy.Htmx.
  5. Click Install.

Using the .NET CLI

If you prefer using the command line, navigate to your project directory and run the following command:

dotnet add package Rizzy.Htmx

Customizing HTMX Configuration

Note

The configuration portion or Rizzy was constructed based on HTMX head configuration. You can find more information about HTMX head configuration on the official Htmx documentation site.

Adding HTMX Configuration in Program.cs

In Program.cs, you can add custom HTMX configurations using the AddHtmx() method. This configures the default HtmxConfig object. You can also add named configurations for your app if needed (though less common). Here’s an example:

Program.cs
using Rizzy.Htmx;

// Add HTMX Configuration Services
builder.Services.AddHtmx(config =>
{
    // Example: Set the default swap delay for all HTMX swaps
    config.DefaultSwapDelay = TimeSpan.FromMilliseconds(100);

    // Example: Enable global view transitions (HTMX 2.0+)
    // config.GlobalViewTransitions = true;

    // Note: config.SelfRequestsOnly defaults to true in Rizzy
    // config.SelfRequestsOnly = true;
});

Setting Configuration in HTML

To include configurations inside the <head> tag of your HTML document (usually in your main layout file like AppLayout.razor), use the <HtmxConfigHeadOutlet /> component. This component renders a <meta name="htmx-config" ...> tag containing the serialized JSON of your HtmxConfig object (either the default one configured in Program.cs or a named one if specified).

AppLayout.razor
<head>
    ...
    <HtmxConfigHeadOutlet />
    ...
</head>

HTMX Configuration Properties

Here is a description of the HTMX configuration properties that can be customized via HtmxConfig in Rizzy.

Rizzy Defaults

A Rizzy Default of unset means Rizzy does not set a specific value by default for that configuration property. In these cases, HTMX’s own default value will apply unless you explicitly configure it in Program.cs using AddHtmx(config => ...).

PropertyRizzy DefaultHTMX DefaultDescription
HistoryEnabledunsettrueEnables history tracking (pushing URLs automatically via hx-boost or hx-push-url).
HistoryCacheSizeunset10Sets the size of the history cache (number of pages stored).
RefreshOnHistoryMissunsetfalseDetermines whether to refresh the page on history misses instead of making an AJAX request.
DefaultSwapStyleunsetinnerHTMLSets the default swap style (e.g., innerHTML, outerHTML).
DefaultSwapDelayunset0msSets the default delay between receiving a response and swapping content.
DefaultSettleDelayunset20msSets the default delay between swapping content and settling it (processing scripts, etc.).
IncludeIndicatorStylesunsettrueSpecifies whether to include the default CSS for indicator styles.
IndicatorClassunsethtmx-indicatorSets the class added to elements while a request is active (when using hx-indicator).
RequestClassunsethtmx-requestSets the class added to the element making the request while the request is active.
AddedClassunsethtmx-addedSets the class added to newly added elements during the settle phase.
SettlingClassunsethtmx-settlingSets the class added to target elements during the settling phase.
SwappingClassunsethtmx-swappingSets the class added to target elements during the swap phase.
AllowEvalunsettrueSpecifies whether to allow eval() for features like trigger filters (use false for stricter CSP).
AllowScriptTagsunsettrueSpecifies whether to process <script> tags found in AJAX responses.
InlineScriptNonceunset''Sets the nonce to add to inline scripts injected by HTMX (use with CSP).
InlineStyleNonceunset''Sets the nonce to add to inline styles injected by HTMX (use with CSP).
GenerateScriptNoncefalseN/ARizzy specific: If true, uses IRizzyNonceProvider to set InlineScriptNonce automatically.
GenerateStyleNoncefalseN/ARizzy specific: If true, uses IRizzyNonceProvider to set InlineStyleNonce automatically.
AttributesToSettleunset["class", "style", "width", "height"]Specifies attributes to settle (copy from old to new elements) during the settling phase.
UseTemplateFragmentsunsetfalseSpecifies whether to use HTML <template> tags for parsing content (not IE11 compatible).
WsReconnectDelayunset"full-jitter"Sets the WebSocket reconnect delay strategy (e.g., "full-jitter", "1s").
WsBinaryTypeunset"blob"Sets the type of binary data received over WebSocket ("blob" or "arraybuffer").
DisableSelectorunset[hx-disable], [data-hx-disable]Sets the selector for disabling HTMX processing on elements or their children.
WithCredentialsunsetfalseSpecifies whether to allow cross-site Access-Control requests with credentials (cookies, auth headers).
Timeoutunset0Sets the request timeout in milliseconds (0 means no timeout).
ScrollBehaviorunsetsmoothSets the scroll behavior (smooth or auto) for boosted links on page transitions.
DefaultFocusScrollunsetfalseSpecifies whether the focused element should be scrolled into view by default after a swap.
GetCacheBusterParamunsetfalseSpecifies whether to include a cache-busting parameter (_={timestamp}) in GET requests.
GlobalViewTransitionsunsetfalseSpecifies whether to use the View Transition API (if available) when swapping content globally.
MethodsThatUseUrlParamsunset['get']Specifies HTTP methods whose parameters should be encoded in the URL instead of the request body.
SelfRequestsOnlytruefalseRizzy specific default: If true, allows only AJAX requests to the same domain. HTMX allows cross-origin.
IgnoreTitleunsetfalseSpecifies whether to ignore the <title> tag found in new content during swaps.
ScrollIntoViewOnBoostunsettrueSpecifies whether the target of a boosted element is scrolled into view after the request.

Conclusion

By following this documentation, you can effectively install Rizzy.Htmx and configure HTMX behavior within your ASP.NET Core application according to your requirements. Remember to place the <HtmxConfigHeadOutlet /> in your layout to apply the configuration.

Edit this page on GitHub
Prev
Content
Next
Form