Chapter 08 Tricks Of The Htmx Masters

We’ll start with the hx-swap attribute. This is often not included on elements that issue htmx-driven requests because its default behavior — innerHTML, which swaps the inner HTML of the element — tends to cover most use cases.

We earlier saw situations where we wanted to override the default behavior and use outerHTML, for example. And, in chapter 2, we discussed some other swap options beyond these two, beforebegin, afterend, etc.

In chapter 5, we also looked at the swap delay modifier for hx-swap, which allowed us to fade some content out before it was removed from the DOM.

In addition to these, hx-swap offers further control with the following modifiers:

So, for example, if we had a button that issued a GET request, and we wished to scroll to the top of the body element when the request completed, we would write the following HTML:

More details and examples can be found online in the hx-swap documentation.

Like hx-swap, hx-trigger can often be omitted when you are using htmx, because the default behavior is typically what you want. Recall the default triggering events are determined by an element’s type:

There are times, however, when you want a more elaborate trigger specification. A classic example is the active search example we implemented in Contact.app:

This example took advantage of two modifiers available for the hx-trigger attribute:

hx-trigger has several additional modifiers. This makes sense, because events are fairly complex and we want to be able to take advantage of all the power they offer. We will discuss events in more detail below.

Here are the other modifiers available on hx-trigger:

Htmx offers many other less commonly used attributes for fine-tuning the behavior of your Hypermedia-Driven Application.

Here are some of the most useful ones:

Let’s take a look at hx-sync, which allows us to synchronize AJAX requests between two or more elements. Consider a simple case where we have two buttons that both target the same element on the screen:

This is fine and will work, but what if a user clicks the “Get Contacts” button and then the request takes a while to respond? And, in the meantime the user clicks the “Get Settings” button? In this case we would have two requests in flight at the same time.

If the /settings request finished first and displayed the user’s setting information, they might be very surprised if they began making changes and then, suddenly, the /contacts request finished and replaced the entire body with the contacts instead!

To deal with this situation, we might consider using an hx-indicator to alert the user that something is going on, making it less likely that they click the second button. But if we really want to guarantee that there is only one request at a time issued between these two buttons, the right thing to do is to use the hx-sync attribute. Let’s enclose both buttons in a div and eliminate the redundant hx-target specification by hoisting the attribute up to that div. We can then use hx-sync on that div to coordinate requests between the two buttons.

Here is our updated code:

.Syncing two buttons

By placing the hx-sync attribute on the div with the value this, we are saying “Synchronize all htmx requests that occur within this div element with one another.” This means that if one button already has a request in flight, other buttons within the div will not issue requests until that has finished.

The hx-sync attribute supports a few different strategies that allow you to, for example, replace an existing request in flight, or queue requests with a particular queuing strategy. You can find complete documentation, as well as examples, at the htmx.org page for hx-sync.

As you can see, htmx offers a lot of attribute-driven functionality for more advanced Hypermedia-Driven Applications. A complete reference for all htmx attributes can be found on the htmx website.

In addition to making it easy to respond to events, htmx also emits many useful events. You can use these events to add more functionality to your application, either via htmx itself, or by way of scripting.

Here are some of the most commonly used events triggered by htmx:

Let’s look at an example of how to work with htmx-emitted events. We’ll use the htmx:configRequest event to configure an HTTP request.

Consider the following scenario: your server-side team has decided that they want you to include a server-generated token for extra security on every request. The token is going to be stored in localStorage in the browser, in the slot special-token.

The token is being set via some JavaScript (don’t worry about the details yet) when the user first logs in:

The server-side team wants you to include this special token on every request made by htmx, as the X-SPECIAL-TOKEN header. How could you achieve this? One way would be to catch the htmx:configRequest event and update the detail.headers object with this token from localStorage.

In VanillaJS, it would look something like this, placed in a <script> tag in the <head> of our HTML document:

As you can see, we add a new value to the headers property of the event’s detail property. After the event handler executes, this headers property is read by htmx and used to construct the request headers for the AJAX request it makes.

The detail property of the htmx:configRequest event contains a slew of useful properties that you can update to change the "shape" of the request, including:

So, for example, if the server-side team decided they wanted the token included as a parameter, rather than as a request header, you could update your code to look like this:

As you can see, this gives you a lot of flexibility in updating the AJAX request that htmx makes.

The full documentation for the htmx:configRequest event (and other events you might be interested in) can be found on the htmx website.

We can listen for any of the many useful events from htmx, and we can respond to those events using hx-trigger. What else can we do with events?

It turns out that htmx itself listens for one special event, htmx:abort. When htmx receives this event on an element that has a request in flight, it will abort the request.

Consider a situation where we have a potentially long-running request to /contacts, and we want to offer a way for the users to cancel the request. What we want is a button that issues the request, driven by htmx, of course, and then another button that will send an htmx:abort event to the first one.

Here is what the code might look like:

So now, if a user clicks on the “Get Contacts” button and the request takes a while, they can click on the “Cancel” button and end the request. Of course, in a more sophisticated user interface, you may want to disable the “Cancel” button unless an HTTP request is in flight, but that would be a pain to implement in pure JavaScript.

Thankfully this isn’t too bad to implement in hyperscript, so let’s take a look at what that would look like:

Now we have a “Cancel” button that is disabled only when a request from the contacts-btn button is in flight. And we are taking advantage of htmx-generated and handled events, as well as the event-friendly syntax of hyperscript, to make it happen. Slick!

We are going to talk more about the various ways that htmx enhances regular HTTP requests and responses in the next section, but, since it involves events, we are going to discuss one HTTP Response header that htmx supports: HX-Trigger. We have discussed before how HTTP requests and responses support headers, name-value pairs that contain metadata about a given request or response. We took advantage of the HX-Trigger request header, which includes the id of the element that triggered a given request.

In addition to this request header, htmx also supports a response header also named HX-Trigger. This response header allows you to trigger an event on the element that submitted an AJAX request. This turns out to be a powerful way to coordinate elements in the DOM in a decoupled manner.

To see how this might work, let’s consider the following situation: we have a button that grabs new contacts from some remote system on the server. We will ignore the details of the server-side implementation, but we know that if we issue a POST to the /sync path, it will trigger a synchronization with the system.

Now, this synchronization may or may not result in new contacts being created. In the case where new contacts are created, we want to refresh our contacts table. In the case where no contacts are created, we don’t want to refresh the table.

To implement this we could conditionally add an HX-Trigger response header with the value contacts-updated:

This value would trigger the contacts-updated event on the button that made the AJAX request to /sync. We can then take advantage of the from: modifier of the hx-trigger attribute to listen for that event. With this pattern we can effectively trigger htmx requests from the server side.

Here is what the client-side code might look like:

The table listens for the contacts-updated event, and it does so on the body element. It listens on the body element since the event will bubble up from the button, and this allows us to not couple the button and table together: we can move the button and table around as we like and, via events, the behavior we want will continue to work fine. Additionally, we may want other elements or requests to trigger the contacts-updated event, so this provides a general mechanism for refreshing the contacts table in our application.

Even more important than response headers, in terms of information conveyed to the client, is the HTTP Response Code. We discussed HTTP Response Codes in Chapter 3. By and large htmx handles various response codes in the manner that you would expect: it swaps content for all 200-level response codes and does nothing for others. There are, however, two “special” 200-level response codes:

You can override the behavior of htmx with respect to response codes by, you guessed it, responding to an event! The htmx:beforeSwap event allows you to change the behavior of htmx with respect to various status codes.

Let’s say that, rather than doing nothing when a 404 occurred, you wanted to alert the user that an error had occurred. To do so, you want to invoke a JavaScript method, showNotFoundError(). Let’s add some code to use the htmx:beforeSwap event to make this happen:

You can also use the htmx:beforeSwap event to configure if the response should be swapped into the DOM and what element the response should target. This gives you quite a bit of flexibility in choosing how you want to use HTTP Response codes in your application. Full documentation on the htmx:beforeSwap event can be found at htmx.org.

The first option, and the simplest, is to “expand the target.” That is, rather than simply replacing a small part of the screen, expand the target of your htmx-driven request until it is large enough to enclose all the elements that need to be updated on a screen. This has the tremendous advantage of being simple and reliable. The downside is that it may not provide the user experience that you want, and it may not play well with a particular server-side template layout. Regardless, we always recommend at least thinking about this approach first.

A second option, a bit more complex, is to take advantage of “Out Of Band” content support in htmx. When htmx receives a response, it will inspect it for top-level content that includes the hx-swap-oob attribute. That content will be removed from the response, so it will not be swapped into the DOM in the normal manner. Instead, it will be swapped in for the content that it matches by id.

Let’s look at an example. Consider the situation we had earlier, where a contacts table needs to be updated if an integration pulls down any new contacts. Previously we solved this by using events and a server-triggered event via the HX-Trigger response header.

This time, we’ll use the hx-swap-oob attribute in the response to the POST to /integrations/1. The new contacts table content will “piggyback” on the response.

Next, the response to the POST to /integrations/1 will include the content that needs to be swapped into the button, per the usual htmx mechanism. But it will also include a new, updated version of the contacts table, which will be marked as hx-swap-oob="true". This content will be removed from the response so that it is not inserted into the button. Instead, it is swapped into the DOM in place of the existing table since it has a matching id.

Using this piggybacking technique, you can update content wherever needed on a page. The hx-swap-oob attribute supports other additional features, all of which are documented.

Depending on how exactly your server-side templating technology works, and what level of interactivity your application requires, out of band swapping can be a powerful mechanism for content updates.

Finally, the most complex mechanism for updating content is the one we saw back in the events section: using server-triggered events to update elements. This approach can be very clean, but also requires a deeper conceptual knowledge of HTML and events, and a commitment to the event-driven approach. While we like this style of development, it isn’t for everyone. We typically recommend this pattern only if the htmx philosophy of event-driven hypermedia really speaks to you.

If it does speak to you, however, we say: go for it. We’ve created some very complex and flexible user interfaces using this approach, and we are quite fond of it.

All of these approaches to the “Updating Other Content” problem will work, and will often work well. However, there may come a point where it would just be simpler to use a different approach for your UI, like the reactive one. As much as we like the hypermedia approach, the reality is that there are some UX patterns that simply cannot be implemented easily using it. The canonical example of this sort of pattern, which we have mentioned before, is something like a live online spreadsheet: it is simply too complex a user interface, with too many interdependencies, to be done well via exchanges of hypermedia with a server.

In cases like this, and any time you feel like an htmx-based solution is proving to be more complex than another approach might be, we recommend that you consider a different technology. Be pragmatic, and use the right tool for the job. You can always use htmx for the parts of your application that aren’t as complex and don’t need the full complexity of a reactive framework, and save that complexity budget for the parts that do.

We encourage you to learn many different web technologies, with an eye to the strengths and weaknesses of each one. This will give you a deep tool chest to reach into when problems present themselves. Our experience is that, with htmx, hypermedia is a tool you can reach for frequently.

The first technique, provided by htmx itself, is to call the htmx.logAll() method. When you do this, htmx will log all the internal events that occur as it goes about its business, loading up content, responding to events and so forth.

This can be overwhelming, but with judicious filtering can help you zero in on a problem. Here are what (a bit of) the logs look like when clicking on the “docs” link on https://htmx.org, with logAll() enabled:

Not exactly easy on the eyes, is it?

But, if you take a deep breath and squint, you can see that it isn’t that bad: a series of htmx events, some of which we have seen before (there’s htmx:configRequest!), get logged to the console, along with the element they are triggered on.

After a bit of reading and filtering, you will be able to make sense of the event stream, and it can help you debug htmx-related issues.

The preceding technique is useful if the problem is occurring somewhere within htmx, but what if htmx is never getting triggered at all? This comes up some times, like when, for example, you have accidentally typed an event name incorrectly somewhere.

In cases like this you will need recourse to a tool available in the browser itself. Fortunately, the Chrome browser by Google provides a very useful function, monitorEvents(), that allows you to monitor all events that are triggered on an element.

This feature is available only in the console, so you can’t use it in code on your page. But, if you are working with htmx in Chrome, and are curious why an event isn’t triggering on an element, you can open the developers console and type the following:

This will then print all the events that are triggered on the element with the id some-element to the console. This can be very useful for understanding exactly which events you want to respond to with htmx, or troubleshooting why an expected event isn’t occurring.

Using these two techniques will help you as you (infrequently, we hope) troubleshoot event-related issues when developing with htmx.

A Content Security Policy (CSP) is a browser technology that allows you to detect and prevent certain types of content injection-based attacks. A full discussion of CSPs is beyond the scope of this book, but we refer you to the Mozilla Developer Network article on the topic for more information.

A common feature to disable using a CSP is the eval() feature of JavaScript, which allows you to evaluate arbitrary JavaScript code from a string. This has proven to be a security issue and many teams have decided that it is not worth the risk to keep it enabled in their web applications.

Htmx does not make heavy use of eval() and, thus, a CSP with this restriction in place will be fine. The one feature that does rely on eval() is event filters, discussed above. If you decide to disable eval() for your web application, you will not be able to use the event filtering syntax.