Response

The HtmxResponse class enables developers to manage client-side behavior through response headers in applications that leverage HTMX. This includes navigating, refreshing, and updating parts of the web page without a full reload, as well as triggering client-side events.

Working With HtmxResponse#

HtmxResponse only has a dependency on HttpContext, so you can use it in any scoped dependency service that has access to HttpContext. To manually create an HtmxResponse object you need only to create a new instance of the class as follows:

var response = new HtmxResponse(httpContext);

Or as an HttpContext.Response extension:

var response = HttpContext.Response.Htmx();

If you are familiar with Htmx.net, then you can use a similar syntax under the Rizzy library. Please note that Rizzy uses it’s own HTMX server-side implementation so you will need to use the documentation.

HttpContext.Response(h => {
  h.PushUrl("/new-url")
   .Trigger("show-special-notification")
});

For the purposes of the examples in this guide, we will be using an instance of HtmxResponse that is available as an HttpResponse extension.

Location#

Performs a client-side redirect to the specified path without a full page reload, leveraging HTMX’s ability to handle AJAX navigation seamlessly.

Example

Response.Htmx(h =>
{
    h.Location("/new-path");
});

This method is particularly useful for implementing SPA-like behavior in traditional server-rendered applications, allowing for partial updates and navigation without losing the state of the application.

PushUrl#

Pushes a new URL onto the browser’s history stack. This method leverages HTMX’s support for AJAX-driven navigation while maintaining correct browser history and bookmarkable URLs.

Example

Response.Htmx(h =>
{
    h.PushUrl("/another-path");
});

Use this method to dynamically update the URL in response to partial content updates, ensuring that users can use the browser’s back and forward buttons as expected.

PreventBrowserHistoryUpdate#

Ensures that the browser’s history is not updated following an AJAX request, overriding any previous PushUrl action. This is useful in scenarios where updates should not affect the browser’s history, such as filtering or sorting operations on a page.

Example

Response.Htmx(h =>
{
    h.PreventBrowserHistoryUpdate();
});

PreventBrowserCurrentUrlUpdate#

Stops the browser’s current URL from being updated.

Example

Response.Htmx(h =>
{
    h.PreventBrowserCurrentUrlUpdate();
});

Redirect#

Facilitates a client-side redirection, akin to a traditional HTTP redirect but executed via HTMX, allowing for a smoother user experience without a full page refresh.

Example

Response.Htmx(h =>
{
    h.Redirect("/redirect-path");
});

This method is useful for redirecting the user after actions that do not require a full page reload, such as form submissions or after performing AJAX-based operations.

Refresh#

Triggers a full page refresh from the server-side. This can be particularly beneficial after a sequence of operations where a fresh state from the server is required.

Example

Response.Htmx(h =>
{
    h.Refresh();
});

In HTMX, a full page refresh might be necessary in scenarios where client-side state needs to be completely reset, or when significant changes have been made that require a fresh page load.

ReplaceUrl#

Updates the current URL in the browser’s location bar.

Example

Response.Htmx(h =>
{
    h.ReplaceUrl("/new-url");
});

Reswap#

Specifies how the response will be swapped into the target element. This allows for fine-grained control over how parts of the page are updated with server responses.

Example

Response.Htmx(h =>
{
    h.Reswap(SwapStyle.innerHTML);
});

Example with Modifiers

Response.Htmx(h =>
{
    h.Reswap(SwapStyle.innerHTML.ShowWindow(ScrollDirection.top).Transition(true));
});
// Reswap output: "innerHTML show:window:top transition:true"

Example with Fluent Modifiers

Response.Htmx(h =>
{
    h.Reswap(SwapStyle.beforebegin.ShowWindow(ScrollDirection.top));
});
// Reswap output: "beforebegin show:window:top"

SwapStyle Options#

Here are the SwapStyle options that define how the response is swapped into the target element on the page:

• Default: Uses the application’s default swap style or htmx’s default.
• innerHTML: Replace the inner HTML of the target element.
• outerHTML: Replace the entire target element with the response.
• beforebegin: Insert the response before the target element.
• afterbegin: Insert the response inside the target element, before its first child.
• beforeend: Insert the response inside the target element, after its last child.
• afterend: Insert the response after the target element.
• delete: Deletes the target element, regardless of the response.
• none: Does not append content from the response (though out-of-band items will still be processed).

Retarget#

Changes the target element for the response update using a CSS selector.

Example

Response.Htmx(h =>
{
    h.Retarget("#new-target");
});

Reselect#

Determines which part of the response is swapped in, using a CSS selector.

Example

Response.Htmx(h =>
{
    h.Reselect(".content-part");
});

Trigger#

Initiates custom events on the client side, which can be used to trigger JavaScript actions in response to server-side events. This method makes use of HTMX’s ability to interact with custom JavaScript by triggering events based on server responses.

Example

Response.Htmx(h =>
{
    h.Trigger("customEvent", new { key = "value" }, TriggerTiming.AfterSwap);
});

This functionality is particularly useful for integrating server-side logic with client-side behaviors, allowing developers to create rich, interactive web applications that respond dynamically to server-side changes.

TriggerTiming Options#

Understanding the timing for triggering client-side events is also crucial:

• Default: Trigger events as soon as the response is received.
• AfterSettle: Trigger events after the settling step, which includes processing scripts and styles.
• AfterSwap: Trigger events after the swap step, ensuring the DOM has been updated.

These options can be used with the Trigger method to control when events are fired in response to HTMX actions.