027. hx-vals（通信に「おまけのデータ」を添えて送る）

原理：リクエストに隠された「追加の指示」

フォームの枠を超えたデータ送信

通常のWeb開発において、サーバーにデータを送る手段といえば「入力フォーム（<input> や <select>）」が一般的でした。ユーザーが文字を打ち、ボタンを押して送る。これが基本です。

しかし、実際の開発では「フォームには入っていないけれど、このボタンを押した時に一緒にこのIDも送りたい」「今のユーザーの設定状態を、裏側でこっそり添えて送りたい」という場面が多々あります。

hx-vals（ヴァルズ / バリューズ）は、HTMXが通信を行う際に、「あなたが決めた追加のデータ」を魔法のリュックサックに詰め込んで、一緒に届けてくれる属性です。 JSON形式で書かれたデータを属性に置くだけで、どんな要素からの通信であっても、豊かな情報を持たせることが可能になります。

JSONが語るデータの形

hx-vals では、{"key": "value"} という形式（JSON形式）でデータを書きます。 - "key": サーバー側でデータを受け取る時の名前（ラベル） - "value": 実際に送りたい中身

これらはサーバーに届くと、通常のフォームからの入力と同じように扱えます。サーバー側のプログラムを複雑に変える必要はありません。

実践：動的な「引数」を手軽に渡す

1. ボタンごとに異なるIDを送信する

同じURLに対して、どのボタンが押されたかによって異なる情報を送る例です。

<!-- 
  hx-post: "/api/vote" に送信するが、
  hx-vals: 「選択肢は A だよ」という情報を付け足す
-->
<button hx-post="/api/vote" hx-vals='{"choice": "A"}'>
    選択肢 A に投票
</button>

<button hx-post="/api/vote" hx-vals='{"choice": "B"}'>
    選択肢 B に投票
</button>

2. JavaScriptを使って「今の状態」を計算して送る

固定の値だけでなく、送信する瞬間にJavaScriptで計算した値を送ることもできます（属性に js: 接頭辞をつけます）。

<button hx-get="/search" 
        hx-vals='js:{"currentTime": new Date().getTime(), "screenSize": window.innerWidth}'>
    今の状況で検索
</button>

3. ステップ・バイ・ステップ解説

情報の整理: 「サーバーに、あと何の情報を伝えれば処理ができるだろう？」と考えます。
属性の記述: hx-vals='{"名前": "中身"}' の形式で書きます。引用符（' と "）の使い分けに注意してください。
サーバーでの受け取り: サーバー側（PHP, Python, Ruby, Goなど）では、通常のフォーム送信（POST/GETパラメータ）として、その名前でデータを取り出すだけです。

比較：hiddenタグによる埋め込み vs hx-vals

従来のHTML（hiddenタグ）

<form action="/save" method="POST">
    <input type="hidden" name="user_id" value="123">
    <button type="submit">保存</button>
</form>

ボタン一つを動かしたいだけなのに、タグを何層も重ねて書く必要があり、HTMLが読みにくくなります。

HTMXの hx-vals

<button hx-post="/save" hx-vals='{"user_id": "123"}'>
    保存
</button>

ボタンそのものの中に情報がスッキリと収まります。どこに行けばどんなデータが送られるのかが、一目瞭然です。

まとめ：初心者のための「メッセージ」の添え方

hx-vals は、あなたのHTMLに「文脈（コンテキスト）」を与える属性です。

引用符の罠に注意: HTMLの属性をダブルクォート " で囲むなら、中のJSONはシングルクォート ' にするか、その逆にしましょう。逆になるとブラウザが混乱してしまいます。 hx-vals='{"a": 1}' がおすすめです。
動的データも怖くない: js: を使えば、今のページにあるどんな情報でもサーバーへ届けることができます。
サーバーとの密な対話: 「これと、これも教えておくね」という気遣いのデータを送ることで、サーバーサイドのプログラムはもっと賢く、シンプルに振る舞うことができるようになります。

ただURLを叩くだけじゃない。hx-vals という荷物に大切な情報を詰め込んで、サーバーとの対話をより豊かなものにしてください。次の記事では、データの「中身」ではなく「封筒の外側」に情報を書くための hx-headers（028. hx-headers）をご紹介します。