hx-config ~ htmx

The hx-config attribute allows you to configure request behavior using JSON.

Syntax


<button hx-post="/api/users" hx-config='{"timeout": 5000}'>
    Create User
</button>

Available Options

Option	Type	Description	Example
`timeout`	number	Request timeout in milliseconds	5000
`credentials`	string	Fetch credentials mode: “omit”, “same-origin”, “include"	"include”
`cache`	string	Fetch cache mode: “default”, “no-cache”, “reload”, etc.	”no-cache”
`redirect`	string	Fetch redirect mode: “follow”, “error”, “manual"	"follow”
`referrer`	string	Referrer URL or “no-referrer"	"no-referrer”
`integrity`	string	Subresource integrity value	”sha384-…”
`validate`	boolean	Whether to validate form before submission	true

These options map to the Fetch API.

Security note: The mode option is intentionally excluded from hx-config. It is always reset to the global htmx.config.mode value (default: "same-origin") to prevent injection attacks from widening request scope. To change the fetch mode, set it globally via htmx.config.mode or a <meta name="htmx-config"> tag. See the mode config reference and security best practices for details.

Merging Configuration

By default, child hx-config values replace parent configurations entirely. Use the + prefix to merge with parent config instead:


<div hx-config='{"timeout": 5000}'>
    <button hx-get="/data"
            hx-config='{"+headers": {"X-Custom": "value"}}'>
        Load Data
    </button>
</div>

The button inherits the timeout and adds a custom header.

Without +, the child config replaces the parent config entirely.

Examples

Set timeout for slow endpoint


<button hx-get="/slow-report"
        hx-config='{"timeout": 30000}'>
    Generate Report
</button>

Include credentials


<button hx-get="/api/data"
        hx-config='{"credentials": "include"}'>
    Load Data
</button>

Disable cache


<button hx-get="/live-data"
        hx-config='{"cache": "no-cache"}'>
    Get Live Data
</button>