#4108·htmx

Title: metaCharacter silently renames dispatched event names, but is documented as scoping to attribute modifiers only — and logAll still logs the old names

Author: kunambiCreated Sep 27, 2026Updated Sep 27, 2026

Description

htmx.config.metaCharacter is documented as replacing the : character used in attribute modifiers only (e.g. hx-get:inherited → hx-get-inherited when metaCharacter: "-"). In practice, it also renames the :-separated segments of dispatched event names (e.g. htmx:after:settle → htmx-after-settle), which is not mentioned anywhere in the config docs.

This makes any htmx.on(...) / addEventListener(...) call written against the documented event names (htmx:before:request, htmx:after:settle, etc.) silently fail to fire — no error, no warning — as soon as a custom metaCharacter is configured.

Compounding this, htmx.config.logAll — the primary tool for debugging exactly this kind of "why isn't my listener firing" issue — continues to log events under their original colon-separated names, even though the actually-dispatched event uses the renamed, dash-separated form. This makes logAll actively misleading in this scenario: it shows htmx:before:request firing at the correct time, giving the strong (and incorrect) impression that a listener registered for htmx:before:request should be receiving it.

Reproduction

xml
<!DOCTYPE html>
<html>
<head>
  <meta name="htmx-config" content='{"metaCharacter":"-"}'>
  <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/htmx.min.js"></script>
</head>
<body>
  <button hx-get="/anything" hx-swap="none">test</button>

  <script>
    htmx.config.logAll = true;

    // Never fires, despite logAll showing "htmx:before:request" in the console
    htmx.on('htmx:before:request', () => console.log('COLON LISTENER FIRED'));

    // Fires correctly
    htmx.on('htmx-before-request', () => console.log('DASH LISTENER FIRED'));
  </script>
</body>
</html>

Expected behavior

One of the following:

  • metaCharacter should not affect dispatched event names at all, matching the current documentation (attribute modifiers only), or
  • If renaming event names is intentional, the config docs for metaCharacter should explicitly say so, and logAll should log the actual (renamed) event name that was dispatched, not the default colon-separated one.

Actual behavior

  • Listeners registered under the documented colon-separated event names never fire once a custom metaCharacter is set.
  • logAll logs the unmodified colon-separated name regardless, making it look like the listener should have fired.

Environment

  • htmx version: 4.0.0 (via jsDelivr: https://cdn.jsdelivr.net/npm/[email protected]/dist/htmx.min.js)
  • Config: <meta name="htmx-config" content='{"metaCharacter":"-"}'>
  • Reproduced in isolation (no other libraries loaded)

Related

This may share root cause with #4084 (extension event names inconsistent under metaCharacter), since both point to metaCharacter substitution being applied inconsistently across different internal event-name/dispatch code paths.