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.

Create a free account to save this page, take notes and track your progress. Sign in

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
htmx.ajax from your own codeTry it yourself
<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:

htmx.process for HTML you addTry it yourself
<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?

  1. Calling htmx.process() on the new content
  2. Reloading htmx
  3. Adding hx-boost
  4. Using 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.

Was this page helpful?