htmx

HTMX

HTMX の実装と統合には、このスキルを使用してください。htmx 2.x（現在の安定版）と htmx 4.x（ベータ版）を対象としています。リファレンスファイルには、[htmx 4]、[htmx 4 change]、[htmx 4 removed] の注意書きが付いています。タスクに必要なリファレンスファイルのみを読んでください。

クイックスタート

1. タスクの領域を特定します（属性、リクエスト、スワップ、イベント、パターン）。
2. references/ から該当するファイルを開きます。
3. HTML を中心とした、ハイパーメディア駆動のパターンを使用して実装します。
4. サーバーのレスポンスが JSON ではなく HTML フラグメントを返すことを確認します。

GET でコンテンツを読み込むボタンの最小限の例：

<button hx-get="/contacts" hx-target="#results" hx-swap="innerHTML">
    Load Contacts
</button>
<div id="results"></div>

サーバーのエンドポイント（/contacts）は、JSON ではなく HTML フラグメントを返す必要があります：

<ul>
    <li>Alice</li>
    <li>Bob</li>
</ul>

デフォルトのスワップは innerHTML です。レスポンスによってターゲットの子要素が置き換えられます。ターゲット要素自体を置き換えるには、hx-swap="outerHTML" を使用します。

重要なルール

1. HTML レスポンス - HTMX はサーバーからの JSON ではなく、HTML レスポンスを想定します
2. 属性の継承 - （v2）ほとんどの属性は子要素に継承されます。停止するには hx-disinherit または unset を使用します。（v4）継承は明示的です。継承を有効にするには :inherited サフィックスを使用します。どちらのバージョンでも継承されない属性： hx-trigger、hx-on*、hx-swap-oob、hx-preserve、hx-history-elt、hx-validate
3. デフォルトのスワップは innerHTML - 意図したスワップ方法であることを必ず確認します
4. フォーム値は自動的に含まれる - GET 以外のリクエストには、最も近い親フォームの値が自動的に含まれます
5. プログレッシブエンハンスメント - hx-boost="true" を使用します。JS がなくてもページが動作する必要があります
6. ユーザーコンテンツをエスケープする - XSS を防ぐため、ユーザーが提供したすべてのコンテンツをサーバー側でエスケープします。ユーザー生成コンテンツを表示する領域は hx-disable で囲み、挿入された属性が HTMX に処理されないようにします
7. CSS のライフサイクルクラス - HTMX はリクエスト中に CSS クラスを追加・削除します。トランジションやインジケーターに使用します
8. data-prefix に対応 - HTML のバリデーションに準拠するため、すべての hx-* 属性は data-hx-* としても記述できます
9. HTTP 286 でポーリングを停止する - サーバーがステータス 286 を返すと、every または load delay によるポーリングが停止します。条件付きのクライアント側ロジックではなく、ポーリングの終了には必ず 286 を使用します
10. エラースワップ - （v2）デフォルトでは 2xx 以外のレスポンスはスワップされません。有効にするには htmx:beforeSwap リスナーを追加します。（v4）204/304 を除くすべてのレスポンスがデフォルトでスワップされます。コードごとに制御するには hx-status を使用します
11. HX-Trigger ヘッダーで疎結合にする - サーバーのレスポンスで DOM 要素の ID をハードコードする代わりに、HX-Trigger レスポンスヘッダーを使用してクライアント側イベントを発火します
12. サーバー側で HTMX リクエストを検出する - HX-Request ヘッダーを確認し、HTMX リクエストには HTML フラグメントを、ブラウザーからの直接リクエストには完全なページを返します。キャッシュには Vary: HX-Request を設定します

リファレンスマップ

• すべての hx-* 属性、値、修飾子：references/attributes.md
• トリガー、ヘッダー、パラメーター、CSRF、キャッシュ、CORS：references/requests.md
• スワップ方法、ターゲット、OOB スワップ、モーフィング、ビューのトランジション：references/swapping.md
• イベント、JS API、設定、拡張機能、デバッグ：references/events-api.md
• 一般的な UI パターンと例：references/patterns.md
• 公式拡張機能（WS、SSE、Idiomorph、response-targets、head-support、preload、hx-live、hx-prompt）：references/extensions.md
• 注意点、落とし穴、実践的なガイダンス：references/gotchas.md
• ファイル間のインデックスとルーティング：references/REFERENCE.md

タスクの振り分け

• 要素に HTMX の動作を追加する → references/attributes.md
• リクエストを発行する方法やタイミングを設定する → references/requests.md
• レスポンスの描画先や描画方法を制御する → references/swapping.md
• イベント、JavaScript との連携、設定を扱う → references/events-api.md
• よく使われる UI パターン（検索、無限スクロール、モーダルなど）を構築する → references/patterns.md
• WebSockets、SSE、モーフィング、プリロード、レスポンスのターゲティング、head のマージを使用する → references/extensions.md
• よくある落とし穴、アクセシビリティ、エラー処理、アーキテクチャ上の判断を扱う → references/gotchas.md
• 横断的な懸念事項やアーキテクチャ → references/REFERENCE.md、次にドメイン固有のファイル