htmx 4.0 is under construction — migration guide

hx-headers

View as Markdown Open this page as Markdown
For LLMs
llms.txt htmx overview for LLMs
llms-full.txt Complete htmx docs for LLMs

Adds custom headers to the request

The hx-headers attribute allows you to add to the headers that will be submitted with an AJAX request.

By default, the value of this attribute is a list of name-expression values in JSON (JavaScript Object Notation) format.

Syntax

<div hx-get="/data" hx-headers='{"myHeader": "My Value"}'>Get Data</div>

If you wish for hx-headers to evaluate the values given, you can prefix the values with javascript: or js:.

  <div hx-get="/example" hx-headers='{"myHeader": "My Value"}'>Get Some HTML, Including A Custom Header in the Request</div>

  <div hx-get="/example" hx-headers='js:{myVal: calculateValue()}'>Get Some HTML, Including a Dynamic Custom Header from Javascript in the Request</div>

Inheritance

By default, hx-headers does not inherit to child elements. Use the :inherited modifier to apply headers to all htmx requests within a subtree. This is useful for propagating a CSRF token across a section of the page:

<div hx-headers:inherited='js:{"X-CSRF-Token": getCsrfToken()}'>
  <button hx-post="/transfer">Submit</button>
  <button hx-delete="/item/1">Delete</button>
</div>

A child declaration of a header overrides a parent declaration.

Security Considerations

  • By default, the value of hx-headers must be valid JSON. It is not dynamically computed. If you use the javascript: prefix, be aware that you are introducing security considerations, especially when dealing with user input such as query strings or user-generated content, which could introduce a Cross-Site Scripting (XSS) vulnerability.

  • Whilst far from being a foolproof solution to Cross-Site Request Forgery, the hx-headers attribute can support backend services to provide CSRF prevention. For more information see the CSRF Prevention section.