htmx Head Tag Support Extension

The head-support extension adds support for head tags in responses to htmx requests.

htmx began as a library focused on partial replacement of HTML within the body tag. As such, merging additional information such as the head tag was not a focus of the library. (This is in contrast with, for example, TurboLinks, which was focused on merging entire web pages retrieved via AJAX into the browser.)

The hx-boost attribute moved htmx closer to this world of full HTML-document support & support for extracting the title tag out of head elements was eventually added, but full head tag support has never been a feature of the library. This extension addresses that shortcoming.

Installing

The fastest way to install head-support is to load it via a CDN. Remember to always include the core htmx library before the extension and enable the extension.

<head>
    <script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
    <script src="https://unpkg.com/htmx-ext-head-support@2.0.2" integrity="sha384-cvMqHzjCJsOHgGuyB3sWXaUSv/Krm0BdzjuI1rtkjCbL1l1oHJx+cHyVRJhyuEz0" crossorigin="anonymous"></script>
</head>
<body hx-ext="head-support">
...

An unminified version is also available at https://unpkg.com/htmx-ext-head-support/dist/head-support.js.

While the CDN approach is simple, you may want to consider not using CDNs in production. The next easiest way to install head-support is to simply copy it into your project. Download the extension from https://unpkg.com/htmx-ext-head-support, add it to the appropriate directory in your project and include it where necessary with a <script> tag.

For npm-style build systems, you can install head-support via npm:

npm install htmx-ext-head-support

After installing, you’ll need to use appropriate tooling to bundle node_modules/htmx-ext-head-support/dist/head-support.js (or .min.js). For example, you might bundle the extension with htmx core from node_modules/htmx.org/dist/htmx.js and project-specific code.

If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):

import `htmx.org`;
import `htmx-ext-head-support`;

Usage

<body hx-ext="head-support">
...
</body>

With this installed, all responses that htmx receives that contain a head tag in them (even if they are not complete HTML documents with a root <html> element) will be processed.

How the head tag is handled depends on the type of htmx request.

If the htmx request is from a boosted element, then the following merge algorithm is used:

If the htmx request is from a non-boosted element, then all content will be appended to the existing head element.

If you wish to override this behavior in either case, you can place the hx-head attribute on the new <head> tag, with either of the following two values:

Controlling Merge Behavior

Beyond this, you may also control merging behavior of individual elements with the following attributes:

Example

As an example, consider the following head tag in an existing document:

<head>
<link rel="stylesheet" href="https://the.missing.style">
<link rel="stylesheet" href="/css/site1.css">
<script src="/js/script1.js"></script>
<script src="/js/script2.js"></script>
</head>

If htmx receives a request containing this new head tag:

<head>
<link rel="stylesheet" href="https://the.missing.style">
<link rel="stylesheet" href="/css/site2.css">
<script src="/js/script2.js"></script>
<script src="/js/script3.js"></script>
</head>

Then the following operations will occur:

The final head element will look like this:

<head>
<link rel="stylesheet" href="https://the.missing.style">
<script src="/js/script2.js"></script>
<link rel="stylesheet" href="/css/site2.css">
<script src="/js/script3.js"></script>
</head>

Events

This extension triggers the following events: