Claude Skill

htmx-development

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

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download camoa-claude-skills-drupal-htmx_skills_htmx-development-c73ba2a.zip · 13 KB

Install

skills CLI npx skills add https://github.com/camoa/claude-skills/tree/main/drupal-htmx/skills/htmx-development
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install camoa-claude-skills@llmmart
Git git clone https://github.com/camoa/claude-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole camoa/claude-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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
Files (claude-skills)
  • references
    • ajax-reference.md 7.3 KB
      Loading…
    • htmx-implementation.md 7.8 KB
      Loading…
    • migration-patterns.md 9.7 KB
      Loading…
    • quick-reference.md 4.2 KB
      Loading…
  • SKILL.md 6.4 KB
    ---
    name: htmx-development
    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
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.