How to Override Global Axios Config Per Request

Axios allows developers to establish global default configurations, such as base URLs, headers, and timeout thresholds, across an entire application. However, individual network requests often require custom parameters that deviate from these baseline settings. This guide explains the Axios configuration hierarchy and demonstrates how to override global defaults directly on a per-request basis with practical code examples.

The Axios Configuration Precedence

Axios applies configuration rules in a specific order of precedence, where later configurations overwrite earlier ones:

1. Library defaults: Built-in settings provided by Axios.
2. Global defaults (axios.defaults): Settings applied globally across the entire Axios module.
3. Instance defaults (instance.defaults): Settings set on a custom instance created via axios.create().
4. Per-request configuration: The config object explicitly passed into a specific request method.

Because per-request configuration sits at the top of the hierarchy, any property defined directly in a request will override the corresponding global default.

Setting Global Defaults

Global configurations are typically defined during application initialization using the axios.defaults object:

import axios from 'axios';

// Set global configuration defaults
axios.defaults.baseURL = 'https://api.example.com/v1';
axios.defaults.headers.common['Authorization'] = 'Bearer global_default_token';
axios.defaults.headers.post['Content-Type'] = 'application/json';
axios.defaults.timeout = 5000; // 5 seconds

Overriding Defaults in Specific Requests

To override these global values, pass a configuration object directly to the request method.

1. Overriding in GET, DELETE, and HEAD Requests

For methods that do not send a request body, the configuration object is passed as the second argument.

// Overriding timeout and headers for a single GET request
axios.get('/users', {
  timeout: 10000, // Extends timeout to 10 seconds
  headers: {
    'Authorization': 'Bearer custom_request_token', // Overrides global token
    'Custom-Header': 'SpecificValue'
  }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

2. Overriding in POST, PUT, and PATCH Requests

For methods that accept a payload, the configuration object is passed as the third argument (after the endpoint URL and data payload).

const payload = { name: 'John Doe' };

// Overriding Content-Type for file uploads or specific payloads
axios.post('/upload', payload, {
  baseURL: 'https://upload.example.com', // Overrides global baseURL
  headers: {
    'Content-Type': 'multipart/form-data'
  }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

3. Overriding Using the Direct axios(config) Method

When using the generic axios() function, specify all request options directly within a single configuration object:

axios({
  method: 'get',
  url: '/reports/annual',
  baseURL: 'https://analytics.example.com', // Overrides global baseURL
  timeout: 30000,                           // Overrides global timeout
  headers: {
    'Authorization': 'Bearer report_access_token'
  }
});

Unsetting Global Headers for a Single Request

Headers are deeply merged by Axios. To completely remove a globally defined header for a single request, set its value to undefined or null in the request's configuration object:

// Make an unauthenticated request by removing the global Authorization header
axios.get('/public-data', {
  headers: {
    'Authorization': undefined
  }
});