Supercharging HTMX with a Custom Event Bus

HTMX is fantastic at simplifying server interactions. With a few HTML attributes, you can replace a mountain of JavaScript boilerplate for handling clicks, form submissions, and content swaps. But what happens when a server response needs to trigger multiple, unrelated actions on the client?

This is a common scenario. A successful form submission might need to close a modal, refresh a data table, and display a success notification. You could try to cram all that logic into the server’s response, maybe using out-of-band swaps, but that can get messy and tightly couples your server’s view logic to very specific UI behaviors.

There’s a cleaner way: by bridging HTMX’s own event system into a custom, application-wide event bus. This lets you use HTMX for what it’s great at, server communication, while, using a decoupled event system for coordinating complex UI side effects. Here’s how you can set it up.

The Problem with Direct Logic

Let’s take our form submission example. The server responds to a hx-post with a new piece of HTML for HTMX to swap. Great. But how do we tell the modal to close? And how do we trigger the notification?

HTMX provides its own set of lifecycle events, like htmx:afterRequest or htmx:afterSwap. You could listen for these directly:

// This works, but it can get complicated fast
document.body.addEventListener("htmx:afterRequest", function (evt) {
  // Was the request successful?
  const wasSuccessful = evt.detail.successful;
  // Was it from our specific form?
  const triggerId = evt.detail.requestConfig.elt.id;

  if (wasSuccessful && triggerId === "my-special-form") {
    // Okay, now find the modal and close it
    const modal = document.getElementById("my-modal");
    modal.close();

    // Now, find the notification system and show a message
    showSuccessToast("Form submitted!");
  }
});

This works, but it has a few problems. Our global listener now needs to know about modals, forms, and notification systems. It’s becoming a god object, a central point of coupling that will grow more complex with every new feature.

A Better Way: Bridge to an Event Bus

In our previous post, we discussed building a central event bus. This bus, appEvents, knows nothing about our application’s specific features; it just emits and listens for named events.

The key to supercharging HTMX is to create a simple “bridge” that listens for all HTMX events and simply re-broadcasts them onto our own event bus. This HTMXEventIntegration is the only piece of our application that is directly coupled to HTMX’s event system.

Here’s a simplified look at the bridge:

// From htmx-event-integration.ts

import { appEvents } from "./app-events";

// A list of all the HTMX events we care about
const HTMX_EVENTS = [
  "htmx:beforeRequest",
  "htmx:afterRequest",
  "htmx:beforeSwap",
  "htmx:afterSwap",
  "htmx:responseError",
  "htmx:sendError",
  "htmx:swapError",
];

export class HTMXEventIntegration {
  constructor() {
    this.setupEventListeners();
  }

  private setupEventListeners(): void {
    // For each HTMX event, add a listener
    HTMX_EVENTS.forEach((eventName) => {
      document.body.addEventListener(eventName, (evt: Event) => {
        // Re-broadcast it on our own event bus
        appEvents.emit(eventName as any, (evt as CustomEvent).detail);
      });
    });
  }
}

// Initialize it once when the application starts
new HTMXEventIntegration();

That’s it. This small class is the glue. It listens for every raw HTMX event and immediately emits it on our appEvents bus. Now, the rest of our application doesn’t need to know about HTMX’s event system at all. They only need to listen to appEvents.

The Power of Decoupled Coordination

Let’s revisit our form submission problem. With the bridge in place, our feature-specific handlers can now listen for HTMX lifecycle events from a single, clean source.

// In our form-handler.ts
appEvents.on("htmx:afterRequest", (data) => {
  // Is this event from our form?
  if (data.elt.id !== "my-special-form") return;

  if (data.successful) {
    // The form submission was successful.
    // Emit events to trigger side effects.
    appEvents.emit("modal:close", { modalId: "my-modal" });
    appEvents.emit("notification:show", {
      type: "success",
      message: "Form submitted!",
    });
    appEvents.emit("table:refresh", { tableId: "main-data-table" });
  } else {
    // Handle the error
    appEvents.emit("notification:show", {
      type: "error",
      message: "Submission failed.",
    });
  }
});

Look at how clean that is. The form-handler’s job is to orchestrate the results of the HTMX request. It doesn’t know how to close a modal or show a notification; it just emits events describing what should happen next.

Our other handlers, ModalHandler, NotificationHandler, and TableHandler, are listening for their own specific events and will act accordingly.

• ModalHandler hears modal:close and closes the modal.
• NotificationHandler hears notification:show and displays the toast.
• TableHandler hears table:refresh and triggers a refresh of the data table.

The Payoff: Clean, Testable, and Scalable

By bridging HTMX events into your own event bus, you gain several major advantages:

1. Decoupling: Your application logic is no longer directly tied to HTMX. If you ever needed to change how you make server requests, you would only need to update the integration bridge and your feature handlers would remain untouched.
2. Single Responsibility: Each handler minds its own business. The form-handler is responsible for form workflows, not for managing modal visibility.
3. Testability: Testing the form workflow is now trivial. You can trigger a fake htmx:afterRequest event on your bus and assert that the correct sequence of modal:close and notification:show events are emitted. You don’t need a real DOM or a running server.
4. Clarity: The flow of logic is easy to follow. HTMX handles the request, and the results are orchestrated through a series of clear, semantic events on the application bus.

This pattern allows you to keep the simplicity and power of HTMX for server communication while enabling the complex, client-side coordination that modern web applications demand, all without falling into a tangled mess of tightly coupled code.