HTMX
htmx
Provides developer tools for building dynamic content in Drupal using the HTMX library.
Overview
The HTMX module provides comprehensive tooling for Drupal developers to build dynamic, interactive content using the HTMX library. HTMX allows developers to access modern browser features directly from HTML attributes, enabling dynamic page updates without writing JavaScript.
This module extends Drupal's core HTMX integration (introduced in Drupal 11) with PHP classes for building HTMX attributes and response headers, a custom block entity system for dynamically loadable blocks, Views integration with HTMX-specific display and pager plugins, and Twig extensions for template-level HTMX integration.
The module follows hypermedia-driven application principles, enabling server-rendered HTML fragments to be swapped into the DOM based on user events, creating responsive single-page application experiences while maintaining progressive enhancement and accessibility.
Install
composer require 'drupal/htmx:^1.5'
composer require 'drupal/htmx:^1.4'
Features
- HtmxAttribute class providing fluent API for building all HTMX attributes (hx-get, hx-post, hx-swap, hx-target, hx-trigger, etc.) with full type safety and documentation
- HtmxResponseHeaders class for building HTMX response headers (HX-Location, HX-Push-Url, HX-Redirect, HX-Trigger, etc.)
- HTMX Block config entity system for creating blocks that can be dynamically loaded via HTMX requests
- HTMX Loader Block plugin that triggers loading of HTMX Blocks based on configurable events
- Views HTMX display plugin providing simple page variant rendering for HTMX requests
- Views HTMX Mini Pager plugin for HTMX-powered pagination
- Automatic transformation of Views exposed forms for HTMX submission
- Twig extension providing create_htmx() function for template-level HTMX attribute creation
- Event subscriber enabling SimplePageVariant rendering for routes with _htmx_route option
- Off-canvas dialog system for inline admin forms
- Route for rendering entities in specific view modes via HTMX
- Debug submodule for development with unminified HTMX library and console logging
Use Cases
Lazy Loading Content Blocks
Use the HTMX Loader block with the 'revealed' or 'intersect' event trigger to defer loading of heavy content blocks until they scroll into view. Configure an HTMX Block with your content block, then place an HTMX Loader in your theme region that loads it on viewport intersection.
Event-Triggered Content Updates
Configure HTMX Blocks to load on specific events like 'click', 'change', or custom HTMX events. Use the HtmxAttribute class to add HTMX attributes to buttons or links that trigger content loading, or use the HTMX Loader block for declarative configuration.
HTMX-Powered Views Pagination
Create a View with the HTMX display type and HTMX mini pager. The pager will load subsequent pages via HTMX without full page reloads, with optional URL push support for browser history integration.
HTMX-Enhanced Forms
Use HtmxAttribute to add HTMX attributes to form submit buttons for inline form submission. Use HtmxResponseHeaders to control post-submission behavior like triggering events, redirecting, or updating specific page elements.
Building Admin Interfaces with Off-Canvas Dialogs
The module's admin interface demonstrates using HTMX for off-canvas dialogs. Use HtmxAttribute with on() for event handlers and the dialog.off-canvas library for building similar admin experiences.
Entity View Mode Loading
Use the htmx.htmx_entity_view route to load any entity rendered in a specific view mode via HTMX. The route /htmx/{entityType}/{entity}/{viewMode} returns just the entity HTML for swapping into your page.
Tips
- Use HtmxAttribute's fluent interface to chain multiple attribute methods for clean, readable code
- Always call toArray() on HtmxAttribute when adding to render arrays that may be altered by other modules
- Use the create_htmx() Twig function with Twig Tweak's drupal_url() for template-level HTMX integration
- Set swap('outerHTML') with ignoreTitle:true (default) to prevent unwanted page title changes
- Use the 'revealed' trigger with HTMX Loader for lazy-loading below-fold content to improve initial page performance
- For Views using the HTMX display, exposed forms are automatically converted to submit via HTMX
- Enable htmx_debug during development but disable in production for better performance
Related Projects
Provides HTMX display plugin for Views that renders without theme wrappers, HTMX mini pager for HTMX-powered pagination, and automatic transformation of exposed forms for HTMX submission
HTMX Block entities use the core block plugin system, allowing any standard block to be configured as an HTMX Block that can be dynamically loaded
Recommended for use with the create_htmx() Twig function to obtain URL objects via drupal_url() for HTMX attribute configuration in templates
Admin Pages
| Title | Path | Description |
|---|---|---|
| HTMX Blocks | /admin/structure/htmx-block |
Administration page for managing HTMX Block entities. HTMX Blocks are special block configurations that can be dynamically loaded via HTMX requests. Unlike standard blocks, HTMX Blocks are not assigned to regions but are loaded on-demand based on events. |
Permissions
| Permission | Description |
|---|---|
|
Allows users to create, edit, and delete HTMX Block entities and access related autocomplete endpoints |
Hooks
| Hook | Description |
|---|---|
hook_form_views_exposed_form_alter |
Alters Views exposed forms when used with HTMX display to submit via HTMX instead of traditional form submission |
hook_theme |
Registers the htmx_mini_pager theme hook for the HTMX mini pager template |
hook_preprocess_htmx_mini_pager |
Preprocesses variables for the HTMX mini pager template, adding HTMX attributes for navigation |
hook_preprocess_views_view |
Adds data-htmx-display attribute to Views for targeting by HTMX pager |
hook_page_top |
Removes toolbar from page_top region during HTMX requests except for the toolbar_only route |
Troubleshooting
Ensure your route has the _htmx_route: true option set, or use the HTMX Views display. This triggers the SimplePageVariant which renders without theme wrappers.
The htmx.block.view service uses the HX-Current-URL header to simulate the original page context. Ensure your HTMX requests include this header (automatically included by HTMX library).
Enable the htmx_debug submodule which loads the unminified HTMX library and enables the debug extension for comprehensive console logging of all HTMX events.
The module removes the toolbar from HTMX responses by default. If you need the toolbar, use the /htmx/toolbar-only route which specifically includes it.
Security Notes
- HTMX Blocks respect standard Drupal access controls through the BlockAccessControlHandler
- The administer htmx_block permission is required to create, edit, and delete HTMX Block configurations
- Entity view routes check entity access before rendering content
- Always validate and sanitize any user input that might be used in HTMX attribute values