htmxでAJAXリクエスト時に送信されるパラメータをフィルタリングする方法

こんにちは。エキサイトでデザイナーをしている齋藤です。

今回は、htmxでAJAXリクエスト時に送信されるパラメータをフィルタリングする方法をご紹介します。

なお、本稿の内容は v2.0.4（2025年4月28日時点の最新版）のhtmxを前提とします。

htmxとは

冒頭、簡単にhtmxについてご説明します。

htmxは、HTMLタグに専用の属性を記述することで、複雑なJSを記述せずにAJAXリクエストの発行を可能にするライブラリです。

htmx.org

<!-- クリックするとPOSTリクエストが発行される -->
<button
type="button"
hx-post="/sample"
hx-trigger="click"
hx-target="#target"
>
  送信
</button>

<!-- レスポンスのHTMLに置き換わる -->
<div id="target"></div>

上述の例では、「button要素のクリックイベントにより/sampleに対してPOSTリクエストを発行し、id="target"が付与されている要素をレスポンスとして帰ってきたHTMLに置き換える」という処理が行われます。

このように、マークアップの延長のような感覚でAJAXリクエストが実装できるのがhtmxの強みです。

実現したいこと

以下のようにform要素内でリクエストを発行する場合、兄弟のinput要素の値はパラメータとして送信されます。

<form>
  <!-- パラメータとして送信される -->
  <input type="hidden" name="param1" value="value1" />
  <input type="hidden" name="param2" value="value2" />

  <button
  hx-post="/sample"
  hx-trigger="click"
  >
    送信
  </button>
</form>

一方で今回実現したいのは、form要素内の一部のinput要素の値のみがリクエスト時に送信されるようにパラメータをフィルタリングすることです。

<form>
  <!-- param1は送信する -->
  <input type="hidden" name="param1" value="value1" />

  <!-- param2は送信しない -->
  <input type="hidden" name="param2" value="value2" />

  ...
</form>

hx-paramsで実現可能

htmxの専用属性のうち、hx-paramsを使用することで、AJAXリクエスト時に送信されるパラメータをフィルタリングできます。

htmx.org

hx-params="not <param-list>"の形式で、排除したいパラメータのkeyを指定します。

<form>
  <input type="hidden" name="param1" value="value1" />

  <!-- 指定されたparam2は送信されない -->
  <input type="hidden" name="param2" value="value2" />

  <!-- hx-paramsに`not param2`を指定 -->
  <button
  hx-params="not param2"
  hx-post="/sample"
  hx-trigger="click"
  >
    送信
  </button>
</form>

ブラウザにてリクエストのPayloadを確認すると次のようになります。

hx-paramsの指定なし	hx-params="not param2"を指定

複数のkeyを指定したい場合はhx-params="not param1,param2のようにコンマ続きで記述します。

なお、hx-paramsのデフォルト値は*であり、これはすべてのパラメータを含むことを指します。

まとめ

今回は、htmxでAJAXリクエスト時に送信されるパラメータをフィルタリングする方法をご紹介しました。

hx-parmsにより、同一form内でリクエスト先を変えたい + 一部のパラメータのみを送信したい といった場合に有用です。

htmxを使用される方の一助となれば幸いです。ご精読ありがとうございました。

参考文献

• </> htmx ~ hx-params Attribute