htmx チートシート

htmxは、JavaScriptを書かずにHTML属性だけでインタラクティブなWeb UIを構築できる軽量（gzipで約14KB）なJavaScriptライブラリです。通常のHTML要素にhx-get、hx-target、hx-swapといった属性を追加すると、htmxがイベントを捕捉し、AJAXリクエストを送信し、サーバーから返されたHTMLフラグメントをDOMに差し替えます。サーバーレンダリングHTMLによって駆動されるSPAライクな体験が得られます。

どちらも要素がトリガーされた際にAJAXリクエストを発行しますが、HTTPメソッドが異なります。hx-getはGETリクエスト（冪等、ボディなし、パラメータはURLに付与）を送ります——データの取得、ナビゲーション、フラグメントの更新に使います。hx-postはPOSTリクエスト（非冪等、パラメータはボディに含まれる）を送ります——フォーム、データの変更、作成・更新を伴うアクションに使います。htmxは対応するRESTメソッドとしてhx-put、hx-patch、hx-deleteもサポートしています。

ほぼ互換性がありますが、いくつかの破壊的変更があります。htmx 2.0（2024年リリース）はIE11サポートを廃止し、レガシーなhx-vars属性を削除（代わりにhx-valsをjs:プレフィックス付きで使う）、単一のhx-on属性をイベントごとに分割（例：hx-on:click、hx-on:htmx:after-request）しました。デフォルト動作も厳格化され、たとえば非アンカー要素ではhx-*属性のみで暗黙のGETが発行されなくなりました。既存の1.xアプリのほとんどは変更なしで動作しますが、完全なリストは公式の2.0移行ガイドを確認してください。

デフォルトのトリガーは要素によって異なります：ボタンや多くの要素ではclick、フォームではsubmit、入力やセレクトではchangeです。任意のDOMイベント名（keyup、change、focus、mouseenterなど）またはhtmx独自のイベント（load、revealed、intersect）で上書きできます。'changed'（値が変わったときだけ発火）、'delay:300ms'（デバウンス）、'throttle:500ms'（レート制限）、'from:#other'（別の要素で待ち受け）、'every 5s'（ポーリング）といった修飾子を組み合わせられます。検索しながら入力するUIの定番パターンはhx-trigger="keyup changed delay:300ms"です。

hx-targetはレスポンスを受け取る要素を選択します（CSSセレクター、または'closest tr'、'find .body'、'next'、'previous'などの相対セレクター）。hx-swapはレスポンスをターゲットに対してどう配置するかを制御します——innerHTMLは中身を置き換え、outerHTMLは要素全体を置き換え、beforeendは中の末尾に追加、beforebeginは要素の前に挿入、deleteはターゲットを削除、noneはスワップせずイベントだけ発火します。両者を組み合わせることで、コンテンツ更新の場所と方法を細かく制御できます。

サーバーはレスポンスにHX-*ヘッダを含めることで、JavaScriptを書かずにクライアント側の動作を制御できます。HX-Triggerはクライアント側のイベントを発火（JSONで詳細データ付きイベントも可）、HX-Redirectはフルページリダイレクト、HX-Locationはhtmx経由のクライアントサイドリダイレクト、HX-Refreshはページリロード、HX-Push-Urlはブラウザ履歴の更新、HX-Reswap/HX-Retarget/HX-Reselectはそのレスポンスのスワップ設定を上書きします。サーバーロジックとhtmxクライアントを橋渡しする仕組みです。

はい。このチートシートはローカルデータセットからクライアントサイドJavaScriptのみでレンダリングされる静的リファレンスです。属性名、検索クエリ、コピーしたスニペットがブラウザの外に出ることはなく、個別エントリと紐づくアナリティクスもありません。ページはオフラインでも動作するため、エアギャップ環境でもブックマークして恒久的なリファレンスとして使えます。