Update CSRF recommendation

yawaramin · yawaramin · commit 5a386af1d945 · 2025-07-20T20:26:01.000-04:00
Recommend using a form with a hidden input or an adjacent CSRF token in the header. Stop recommending a global token in the `html` or `body` tags as those may not work with `hx-boost`. Fix #3379
diff --git a/www/content/docs.md b/www/content/docs.md
@@ -1695,22 +1695,38 @@ for exploring this topic.
 
 ### CSRF Prevention
 
-The assignment and checking of CSRF tokens are typically backend responsibilities, but `htmx` can support returning the CSRF token automatically with every request using the `hx-headers` attribute. The attribute needs to be added to the element issuing the request or one of its ancestor elements. This makes the `html` and `body` elements effective global vehicles for adding the CSRF token to the `HTTP` request header, as illustrated below. 
+The assignment and checking of CSRF tokens are typically backend responsibilities.
+For example, using Django, a popular Python web framework
+[documentation](https://docs.djangoproject.com/en/5.2/howto/csrf/#using-csrf):
 
 ```html
-<html lang="en" hx-headers='{"X-CSRF-TOKEN": "CSRF_TOKEN_INSERTED_HERE"}'>
-    :
-</html>
+<form method="post" action="/foo" hx-boost="true">{% csrf_token %}
+  <input name="foo-name">
+  <button type="submit">Add Foo</button>
+</form>
 ```
 
+Htmx will ensure the CSRF 'token' (a hidden input) is submitted along with the
+form so that the Django backend can check it.
+
+Or if you're not using a form, you can set the token in a header:
+
 ```html
-    <body hx-headers='{"X-CSRF-TOKEN": "CSRF_TOKEN_INSERTED_HERE"}'>
-        :
-    </body>
+<span id="delete-foo-token">{% csrf_token %}</span>
+<button
+  hx-delete="/orders/1234"
+  hx-headers="js:{'X-CSRFToken': document.querySelector('#delete-foo-token > [name=csrfmiddlewaretoken]').value}"
+>
+  Delete Order 1234
+</button>
 ```
 
-The above elements are usually unique in an HTML document and should be easy to locate within templates. 
+It's typically not a good idea to set the CSRF token in the `html` or `body`
+elements, because those are not updated by `hx-boost`. So, they could lead to
+form validation errors in the backend.
 
+Remember, these are just examples–you will need to adapt them to your backend
+framework.
 
 ## Configuring htmx {#config}
 
