# How to Modify an htmx Request Configuration Before It Is Sent

> Learn how to modify htmx request configuration before sending. Intercept the htmx:configRequest event to change headers, URL, timeout, or verb for precise control.

- Repository: [Big Sky Software/htmx](https://github.com/bigskysoftware/htmx)
- Tags: how-to-guide
- Published: 2026-08-30

---

**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`](https://github.com/bigskysoftware/htmx/blob/main/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`](https://github.com/bigskysoftware/htmx/blob/main/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`.

```javascript
// 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.

```html
<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.

```javascript
// 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`](https://github.com/bigskysoftware/htmx/blob/main/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`](https://github.com/bigskysoftware/htmx/blob/main/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.