---
name: htmx-development-b2b198face9c
description: Use when implementing HTMX in Drupal, migrating from AJAX to HTMX, building dynamic forms, dependent dropdowns, infinite scroll, real-time validation, or multi-step wizards. Use when user says "HTMX", "migrate AJAX", "dependent dropdown", "dynamic form", "infinite scroll", "load more", "real-time validation", "multi-step wizard", "hx-get", "hx-post", "Htmx class". Use PROACTIVELY for any Drupal 11.3+ dynamic interaction that could use HTMX instead of AJAX. MUST check HTMX patterns before implementing AJAX callbacks.
version: 1.6.0
allowed-tools: Read, Glob, Grep
user-invocable: true
---

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

```php
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:

```php
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


---
Source attribution: camoa
Original project: https://github.com/camoa/claude-skills/blob/2643eff65f4e8b44c7608ebbbdc85c9ad277871e/drupal-htmx/skills/htmx-development/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2025 Carlos Ospina

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: camoa
Original project: https://github.com/camoa/claude-skills/blob/2643eff65f4e8b44c7608ebbbdc85c9ad277871e/drupal-htmx/skills/htmx-development/SKILL.md
Attribution basis: Source repository record

Fields of work: Design, Development & Engineering, Product Management
Roles: Frontend Developer, Product Manager, UX Designer
Specialties: API, Word Documents, Frontend, Testing
Tools: Drupal
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: f08abe0f7408aae8b1b6f1f810edefe289955a0c43260dda5773014d337ca777