Htmx Development

HTMX Development

Drupal 11.3+ HTMX implementation and AJAX migration guidance.

When to Use

• Implementing dynamic content updates in Drupal
• Building forms with dependent fields
• Migrating existing AJAX to HTMX
• Adding infinite scroll, load more, real-time validation
• NOT for: Traditional AJAX maintenance (use references/ajax-reference.md)

Decision: HTMX vs AJAX

Hybrid OK: Both systems coexist. Migrate incrementally.

Quick Start

Attach HTMX behavior to a render element with the Htmx class:

use Drupal\Core\Htmx\Htmx;
use Drupal\Core\Url;

(new Htmx())
  ->get(Url::fromRoute('my.content'))
  ->onlyMainContent()
  ->target('#result')
  ->swap('innerHTML')
  ->applyTo($build['button']);

The controller returns a render array (['#markup' => '...']); add _htmx_route: TRUE to the route's options for an always-minimal response. Full setup — basic usage, route configuration, dual-purpose routes — is in references/htmx-implementation.md.

Core Patterns

Pattern Selection

Each pattern has full before/after code in references/migration-patterns.md (7 patterns) and references/htmx-implementation.md (dependent dropdowns, OOB updates, URL history).

Htmx Class Reference

• Request: get() / post() / put() / patch() / delete() (take a Url)
• Control: target(), select(), swap(), swapOob(), trigger(), vals(), onlyMainContent()
• Response headers: pushUrlHeader(), redirectHeader(), triggerHeader(), reswapHeader(), retargetHeader()
• Apply: applyTo($element) or applyTo($element, '#wrapper_attributes')

Complete method and header tables: references/quick-reference.md.

Detecting HTMX Requests

Forms include HtmxRequestInfoTrait automatically; controllers add it manually:

if ($this->isHtmxRequest()) {
  $trigger = $this->getHtmxTriggerName();
}

Controller setup and the full 8-method detection API are in references/htmx-implementation.md.

Migration from AJAX

1. Identify #ajax properties
2. Replace with the Htmx class
3. Move callback logic into buildForm()
4. Use getHtmxTriggerName() for conditional logic
5. Replace AjaxResponse with render arrays
6. Test progressive enhancement

The FAPI quick map (#ajax → Htmx equivalents), command-level mappings, and 7 detailed before/after patterns are in references/migration-patterns.md and references/quick-reference.md.

Effort-Adaptive Depth

This skill's work forms a natural gradient — scaffold, validate, cross-reference. Scale it to the active effort level, ${CLAUDE_EFFORT}:

When ${CLAUDE_EFFORT} is unset (model without effort support), default to the medium depth.

Validation Checklist

When reviewing HTMX implementations:

• Htmx class used (not raw attributes)
• onlyMainContent() for minimal response
• Proper swap strategy selected
• OOB used for multiple updates
• Trigger element detection works
• Works without JavaScript (progressive)
• Accessibility: aria-live for dynamic regions
• URL updates for bookmarkable states

Common Issues

Extended troubleshooting: references/htmx-implementation.md.

References

Bundled (HTMX-Specific)

• references/quick-reference.md — command equivalents, method/header tables
• references/htmx-implementation.md — full Htmx class API, detection, routes, JS
• references/migration-patterns.md — 7 patterns with before/after code, FAPI quick map
• references/ajax-reference.md — AJAX commands for understanding existing code

Online Dev-Guides

For deeper Drupal context beyond bundled references, invoke /dev-guides-navigator with keywords like "Drupal forms", "routing", "JS development", or "render API". The navigator handles caching and disambiguation — never fetch dev-guides URLs directly. Relevant topics: drupal/forms, drupal/routing, drupal/js-development, drupal/render-api.

Key Files in Drupal Core

• core/lib/Drupal/Core/Htmx/Htmx.php — Main API
• core/lib/Drupal/Core/Htmx/HtmxRequestInfoTrait.php — Request detection
• core/lib/Drupal/Core/Render/MainContent/HtmxRenderer.php — Response renderer
• core/modules/config/src/Form/ConfigSingleExportForm.php — Production example
• core/modules/system/tests/modules/test_htmx/ — Test examples