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

| Choose HTMX | Choose AJAX | |-------------|-------------| | New features | Existing AJAX code | | Declarative HTML preferred | Complex command sequences | | Returns HTML fragments | Dialog commands needed | | Progressive enhancement needed | Contrib expects 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

| Use Case | Pattern | Key Methods | |----------|---------|-------------| | Dependent dropdown | Form partial update | select(), target(), swap('outerHTML') | | Load more | Append content | swap('beforeend'), trigger('click') | | Infinite scroll | Auto-load | swap('beforeend'), trigger('revealed') | | Real-time validation | Blur check | trigger('focusout'), field update | | Multi-step wizard | URL-based steps | pushUrl(), route parameters | | Multiple updates | OOB swap | swapOob('outerHTML:#selector') |

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}:

| ${CLAUDE_EFFORT} | Depth | |--------------------|-------| | low | Emit the HTMX scaffolding (Quick Start + the relevant Core Pattern) and stop. | | medium and above | Also run the Validation Checklist below inline against what was produced. | | high / xhigh / max | Additionally delegate to /dev-guides-navigator for drupal/forms and drupal/js-development to cross-reference FAPI and behavior patterns. |

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

| Problem | Solution | |---------|----------| | Content not swapping | Check target() selector exists | | Wrong content extracted | Check select() selector | | JS not running | Verify htmx:drupal:load fires | | Form not submitting | Check post() and URL | | Multiple swaps fail | Add swapOob('true') to elements | | History broken | Use pushUrlHeader() |

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