Skip to content

HTMX Overview

When to Use

Use HTMX when you're building interactive Drupal features that update page regions without full page reloads and want a simpler approach than traditional AJAX. Use traditional AJAX when you need complex command sequences or contrib module compatibility.

Decision

Situation Choose Why
Content replacement, simple swap HTMX Declarative attributes, less code
Forms with dependent fields HTMX Automatic form_build_id, cleaner DX
Complex AJAX command sequences Traditional AJAX Fine-grained DOM control
Contrib module integration Traditional AJAX Maintain compatibility
Heavy client-side processing Traditional AJAX HTMX is server-driven

Pattern

<button data-hx-get="/contacts/1" data-hx-target="#contact-ui">
  Fetch Contact
</button>

HTMX extends HTML with attributes that enable dynamic content updates without extensive JavaScript. Elements issue HTTP requests and swap content directly in the DOM.

Key benefits:

  • Declarative: HTML attributes replace imperative JavaScript
  • Smaller footprint: Up to 71% less JavaScript compared to traditional AJAX
  • Progressive enhancement: Forms/links work without JavaScript
  • Hypermedia-driven: Aligns with web platform patterns
  • Seamless integration: Works with Drupal's render system and behaviors

Reference: Change record "Ajax subsystem now includes HTMX" — Drupal 11.3.0 (September 10, 2025) Reference: /core/lib/Drupal/Core/Htmx/Htmx.php

Common Mistakes

  • Wrong: Assuming HTMX replaces all AJAX → Right: Traditional AJAX still needed for complex command sequences and contrib module compatibility
  • Wrong: Not using _htmx_route: TRUE or onlyMainContent() → Right: Without these, routes return full page renders instead of minimal responses
  • Wrong: Forgetting progressive enhancement → Right: Always provide a non-JavaScript fallback for forms and links
  • Wrong: Using HTMX for heavy client-side processing → Right: HTMX is server-driven; complex JS logic belongs in traditional patterns

See Also