How to Modify an htmx Request Configuration Before It Is Sent

Listen for the htmx:configRequest event and mutate the event.detail object containing the HtmxRequestConfig to change headers, URL, timeout, or HTTP verb before the XMLHttpRequest opens.

htmx fires a configurable event called htmx:configRequest immediately before opening any AJAX connection. According to the bigskysoftware/htmx source code in src/htmx.js, this event exposes a mutable configuration object that allows you to intercept and modify every aspect of the outgoing request. Whether you need to inject authentication tokens, version your API paths, or adjust timeouts dynamically, this hook provides complete control over the final request parameters.

Understanding the htmx:configRequest Event

When htmx prepares to send a request, it assembles a HtmxRequestConfig object containing the HTTP verb, path, headers, form data, timeout, and credentials. In src/htmx.js at lines 4470-4495, the library creates this configuration and immediately dispatches the htmx:configRequest event, passing the configuration as event.detail.

The event is cancellable. Returning false from your handler or calling event.preventDefault() aborts the request entirely before the XMLHttpRequest opens. After the event callback completes, htmx proceeds with the (possibly mutated) values to open the connection (lines 4496-4505).

Modifying Global Request Configuration

To apply changes to every htmx request in your application, attach a listener to the document. The event.detail object exposes properties including verb, path, headers, parameters, and timeout.

// In your global JavaScript
document.addEventListener('htmx:configRequest', function (evt) {
  const cfg = evt.detail;  // The HtmxRequestConfig object
  
  // Add custom headers to every request
  cfg.headers = Object.assign(cfg.headers || {}, {
    'X-My-App': 'Demo',
    'X-Requested-With': 'htmx'
  });
  
  // Increase timeout for slow endpoints
  cfg.timeout = 8000;
  
  // Prepend API versioning to all paths
  cfg.path = '/api/v2' + cfg.path;
});

This approach ensures consistent header injection across your entire application without modifying individual HTML elements.

Targeting Specific Elements

For element-specific modifications, use the hx-on attribute or attach listeners directly to specific DOM nodes. This is useful when only certain requests require special handling, such as search filters or form-specific transformations.

<div id="search-box">
  <input id="q" name="q" type="text">
  <button hx-get="/search" 
          hx-target="#search-results"
          hx-on="htmx:configRequest: handleSearchConfig(event)">
    Search
  </button>
</div>

<script>
  function handleSearchConfig(event) {
    const cfg = event.detail;
    
    // Append extra query parameters dynamically
    const extra = new URLSearchParams({ lang: 'en', sort: 'relevance' });
    const url = new URL(cfg.path, location);
    url.search = url.search ? url.search + '&' + extra : extra;
    cfg.path = url.toString();
    
    // Dynamically change the HTTP method
    cfg.verb = 'post';
  }
</script>

Listening at the element level prevents global event pollution and keeps request logic colocated with your markup.

Working with the Low-Level API

The htmx:configRequest event fires even when using the programmatic htmx.ajax() API. This ensures consistent request modification regardless of whether the request originates from HTML attributes or JavaScript calls.

// This triggers the same config event as attribute-based requests
htmx.ajax('GET', '/data', {
  target: '#info',
  swap: 'innerHTML'
});

// Your global listener will still execute and can modify this request

This symmetry allows you to centralize request configuration logic while using both declarative and imperative htmx patterns.

Key Request Configuration Properties

The event.detail object passed to htmx:configRequest contains the following mutable properties:

• verb – The HTTP method (GET, POST, PUT, DELETE, etc.)
• path – The request URL or path string
• headers – An object containing request headers
• timeout – The timeout value in milliseconds
• credentials – Boolean indicating whether to send cookies
• parameters – Form data or parameters being sent

Modifying any of these properties immediately affects the outgoing XMLHttpRequest that htmx opens immediately after the event concludes.

Summary

• Event name: htmx:configRequest fires in src/htmx.js immediately before opening the XMLHttpRequest (lines 4470-4495).
• Mutable config: Access and modify event.detail to change headers, path, verb, timeout, and parameters.
• Cancellation: Return false or call event.preventDefault() to abort the request entirely.
• Scope: Listen on document for global changes or attach to specific elements for targeted modifications.
• API coverage: Works with both declarative attributes and the htmx.ajax() programmatic API.

Frequently Asked Questions

Can I cancel a request using htmx:configRequest?

Yes. The htmx:configRequest event is cancellable. If you return false from your event handler or invoke event.preventDefault(), htmx will abort the request and not open the XMLHttpRequest. This is implemented in src/htmx.js immediately after the event dispatch.

What properties can I modify in the request configuration?

You can modify verb, path, headers, timeout, credentials, and parameters. These properties map directly to the internal HtmxRequestConfig object that htmx uses to configure the final XMLHttpRequest instance.

Does htmx:configRequest work with htmx.ajax()?

Yes. The event fires consistently regardless of whether the request originates from an HTML attribute (like hx-get) or a JavaScript call to htmx.ajax(). This ensures your request modification logic remains centralized across both declarative and imperative usage patterns.

How do I add authentication headers to every htmx request?

Attach a global event listener to the document and modify event.detail.headers. Because the headers property is a standard JavaScript object, you can use Object.assign() to merge your authentication tokens or API keys into the existing header collection before the request transmits.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}