package html_of_jsx

  1. Overview
  2. Docs

Htmx support

html_of_jsx provides two packages for working with htmx:

  • html_of_jsx.ppx -htmx: Enables htmx attributes (hx_get, hx_post, hx_swap, etc.) on all HTML elements
  • html_of_jsx.htmx: A runtime library with JSX components for loading the htmx script and its extensions

Setup

  (libraries html_of_jsx html_of_jsx.htmx)
  (preprocess (pps html_of_jsx.ppx -htmx))

Attributes

The -htmx ppx flag enables htmx attributes on all HTML elements, scoped with the prefix hx_.

JSX.render(<div hx_boost=true />)
(* <div hx-boost="true"></div> *)

Script and extensions

The html_of_jsx.htmx library provides JSX components to load the htmx script and its extensions from a CDN.

Loading htmx

Use <Htmx /> to render a script tag that loads htmx:

<head>
  <Htmx version="2.0.4" />
</head>
(* <head><script src="https://unpkg.com/htmx.org@2.0.4"></script></head> *)

For subresource integrity, pass the integrity prop:

<Htmx
  version="2.0.4"
  integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+"
/>

Loading extension scripts

Each htmx extension has its own JSX component under Htmx.Extensions that renders a <script> tag loading the extension from a CDN:

<head>
  <Htmx version="2.0.4" />
  <Htmx.Extensions.SSE version="2.2.2" />
  <Htmx.Extensions.WS version="2.2.0" />
</head>

Available extensions:

All extension components accept an optional ?version prop. Without it, the latest version is loaded from unpkg.

Full example

let make = (~name, ()) => {
  <html lang="en">
    <head>
      <title> "My App" </title>
      <Htmx version="2.0.4" />
      <Htmx.Extensions.SSE version="2.2.2" />
    </head>
    <body>
      <h1> {JSX.string("Hello, " ++ name)} </h1>
      <button hx_get="/clicked" hx_swap=`outerHTML>
        "Click me"
      </button>
      <div hx_ext="sse" sse_connect="/events" sse_swap="message">
        "Waiting for events..."
      </div>
    </body>
  </html>;
};

Extension attributes reference

htmx extensions add custom behaviors and require additional attributes. To use an extension, you need to:

  1. Load the extension script
  2. Add the hx_ext attribute to enable it
  3. Use extension-specific attributes

SSE (Server-Sent Events)

The SSE extension allows you to connect to a Server-Sent Events source and update content when events are received.

Attributes:

  • sse_connect: URL to connect to for SSE
  • sse_swap: event name to swap content on
  • sse_close: event name to close the connection on

Example:

<div hx_ext="sse" sse_connect="/events" sse_swap="message">
  {JSX.string("Loading...")}
</div>

WebSocket

The WebSocket extension enables WebSocket communication.

Attributes:

  • ws_connect: URL to connect to for WebSocket
  • ws_send: when true, sends a message to the WebSocket server on trigger

Example:

<div hx_ext="ws" ws_connect="/chat">
  <form ws_send=true>
    <input type_="text" name="message" />
  </form>
</div>

Class-tools

The Class-tools extension allows you to add, remove, or toggle CSS classes on a schedule.

Attributes:

  • classes: a run list of class operations (e.g., "add highlight:1s")

Example:

<div hx_ext="class-tools" classes="add highlight:1s">
  {JSX.string("This will be highlighted after 1 second")}
</div>

Preload

The Preload extension preloads linked resources to make page navigation feel instant.

Attributes:

  • preload: when to preload ("mousedown" or "mouseover")

Example:

<a hx_ext="preload" preload="mouseover" href="/page">
  {JSX.string("Hover to preload")}
</a>

Path-deps

The Path-deps extension refreshes elements when paths they depend on are modified.

Attributes:

  • path_deps: path(s) this element depends on

Example:

<div hx_ext="path-deps" path_deps="/api/todos" hx_get="/todos" hx_trigger="path-deps">
  {JSX.string("Todo list")}
</div>

Loading-states

The Loading-states extension provides fine-grained control over loading indicators.

Attributes:

  • data_loading: show element during request
  • data_loading_class: add CSS class during request
  • data_loading_class_remove: remove CSS class during request
  • data_loading_disable: disable element during request
  • data_loading_aria_busy: set aria-busy during request
  • data_loading_delay: delay before applying loading state (e.g., "200ms")
  • data_loading_target: CSS selector for target element
  • data_loading_path: only trigger for requests to this path
  • data_loading_states: marker to enable the extension

Example:

<button hx_post="/submit" data_loading_disable=true>
  {JSX.string("Submit")}
</button>
<div data_loading=true data_loading_delay="200ms">
  {JSX.string("Loading...")}
</div>