From 53c564c48f5f052f7709763e06e0c80e83f5f469 Mon Sep 17 00:00:00 2001
From: yujiteshima <yuji.teshima@gmail.com>
Date: Sat, 10 Jan 2026 01:23:42 +0900
Subject: [PATCH] docs: improve hx-vals documentation for use with hx-post

- Add section explaining hx-vals works with all HTTP methods (POST, PUT, etc.)
- Document the difference between GET (query params) and non-GET (request body)
- Add JSON syntax requirements section with common pitfalls
- Clarify that malformed JSON is silently ignored

Fixes #1134
---
 www/content/attributes/hx-vals.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/www/content/attributes/hx-vals.md b/www/content/attributes/hx-vals.md
index ebe02852a..1cb7f42ff 100644
--- a/www/content/attributes/hx-vals.md
+++ b/www/content/attributes/hx-vals.md
@@ -33,6 +33,36 @@ You can also use the spread operator to dynamically specify values. This allows
 
 In this example, if `foo()` returns an object like `{name: "John", age: 30}`, both `name` and `age` will be included as parameters in the request.
 
+## Using hx-vals with hx-post
+
+The `hx-vals` attribute works with all HTTP methods, including `hx-post`, `hx-put`, `hx-patch`, and `hx-delete`:
+
+```html
+  <button hx-post="/submit" hx-vals='{"action": "save", "draft": "true"}'>
+    Save as Draft
+  </button>
+```
+
+When used with non-GET requests (POST, PUT, PATCH, DELETE), the values from `hx-vals` are included in the request body.
+When used with GET requests, they are appended as query parameters.
+
+## JSON Syntax Requirements
+
+The `hx-vals` attribute requires **valid JSON syntax**. A common mistake is using single quotes inside the JSON, which will cause the values to be silently ignored:
+
+```html
+  <!-- WRONG: Single quotes inside JSON are invalid -->
+  <div hx-post="/example" hx-vals="{'myVal': 'value'}">This will NOT work</div>
+
+  <!-- CORRECT: Use double quotes inside JSON, single quotes for the attribute -->
+  <div hx-post="/example" hx-vals='{"myVal": "value"}'>This works correctly</div>
+
+  <!-- CORRECT: Or escape the double quotes if using double quotes for the attribute -->
+  <div hx-post="/example" hx-vals="{&quot;myVal&quot;: &quot;value&quot;}">This also works</div>
+```
+
+If your `hx-vals` JSON is malformed, htmx will silently ignore it without any error message, which can make debugging difficult.
+
 ## Security Considerations
 
 * By default, the value of `hx-vals` must be valid [JSON](https://developer.mozilla.org/en-US/docs/Glossary/JSON).