htmx Tutorial · Going Further · Lesson 25 of 30
The htmx JavaScript API
Call htmx from your own scripts: htmx.ajax, htmx.process for new HTML, htmx.on, htmx.trigger and htmx.config.
You rarely need it, but it's there
Most htmx pages need no JavaScript. When you do, the global htmx object helps:
| Function | Does |
|---|---|
htmx.ajax("GET", "/url", "#target") |
send an htmx-style request from code; returns a promise |
htmx.ajax("POST", "/url", {target: "#t", swap: "beforeend", values: {a: 1}}) |
the same with options |
htmx.process(element) |
activate hx- attributes in HTML you added with JavaScript |
htmx.on("htmx:afterSwap", fn) |
listen to an event (on document.body by default) |
htmx.trigger(element, "myEvent") |
fire an event that hx-trigger can respond to |
htmx.config |
settings such as defaultSwapStyle, timeout, responseHandling |
<select id="country">
<option value="">Choose a country</option><option>Japan</option><option>Kenya</option><option>Peru</option>
</select>
<p id="facts"></p>
<script>
// Plain JavaScript decides when to call htmx.
document.getElementById("country").addEventListener("change", (e) => {
if (e.target.value) htmx.ajax("GET", "/facts?country=" + encodeURIComponent(e.target.value), "#facts");
});
</script>
<!-- The pretend server: on a real site this part is your backend (Python, PHP, Node, Go...) -->
<script>
const capitals = { Japan: "Tokyo", Kenya: "Nairobi", Peru: "Lima" };
server.get("/facts", (req) => `The capital of ${server.escape(req.query.country)} is ${capitals[req.query.country]}.`);
</script>
htmx.process
htmx automatically processes HTML it swaps in. If your own code inserts HTML containing hx- attributes (for
example a third-party widget or innerHTML), call htmx.process(element) or the attributes do nothing:
<button id="add">Add a widget with JavaScript</button>
<div id="area"></div>
<script>
document.getElementById("add").addEventListener("click", () => {
const box = document.createElement("div");
box.innerHTML = '<button hx-get="/hi" hx-swap="outerHTML">I was added by JavaScript: click me</button>';
document.getElementById("area").append(box);
htmx.process(box); // remove this line and the new button does nothing
});
</script>
<!-- The pretend server: on a real site this part is your backend (Python, PHP, Node, Go...) -->
<script>
server.get("/hi", () => "<p>It works, because htmx.process() activated the button.</p>");
</script>
Configuration
Set options in code (htmx.config.defaultSwapStyle = "outerHTML") or, better, in a <meta> tag so they apply before
htmx starts:
<meta name="htmx-config" content='{"defaultSwapStyle": "outerHTML", "timeout": 10000}'>
Test yourself
You insert HTML with hx-get using element.innerHTML, but clicking does nothing. What's missing?
Calling htmx.process() on the new contentReloading htmxAdding hx-boostUsing hx-trigger="load"
Show answer
Answer: Calling htmx.process() on the new content
htmx only scans content it swaps in itself; process() activates content you inserted.