Axios Automatic URI Encoding for Query Params

This article explains how the Axios HTTP client manages automatic URI encoding when passing query parameter values. By understanding how Axios serializes the params configuration object, when it applies encodeURIComponent, and how to customize this behavior using paramsSerializer, developers can ensure their request URLs are formatted accurately and safely across different environments.

Automatic Encoding with the params Object

When making HTTP requests in Axios, query parameters are typically passed using the params option in the request configuration:

axios.get('https://api.example.com/search', {
  params: {
    query: 'hello world & special/chars',
    page: 2
  }
});

When using the params configuration, Axios automatically applies URI encoding to both keys and values. Under the hood, Axios converts values using standard encoding rules similar to JavaScript's native encodeURIComponent() function, producing a final request URL:

https://api.example.com/search?query=hello%20world%20%26%20special%2Fchars&page=2

How Axios Encodes Special Characters

Axios uses an internal serializer that encodes characters to make them safe for HTTP transmission, with minor adjustments for specific standard characters.

The default encoding logic:

• Replaces unsafe characters (such as spaces, ampersands, slashes, and non-ASCII characters) with their percent-encoded hexadecimal representations (e.g., space becomes %20 or +).
• Preserves specific standard characters that are often valid in query strings, such as commas (,), colons (:), dollar signs ($), and brackets ([ and ]), depending on the specific Axios version and targeted spec.

Query Strings in Direct URLs vs. params

Axios only automatically encodes query parameters passed through the params configuration object.

If query parameters are written directly into the URL string, Axios does not encode them:

// NOT automatically encoded by Axios:
axios.get('https://api.example.com/search?query=hello world');

// Automatically encoded by Axios:
axios.get('https://api.example.com/search', {
  params: { query: 'hello world' }
});

If you construct the URL string manually, you must apply encodeURIComponent() yourself before sending the request.

Handling Arrays and Nested Objects

By default, Axios serializes arrays in the params object by repeating the key with bracket notation:

axios.get('/api/filter', {
  params: {
    tags: ['javascript', 'web dev']
  }
});
// Serializes to: /api/filter?tags[]=javascript&tags[]=web%20dev

Nested objects and complex structures are serialized according to standard URL-encoded rules, but complex structures may require custom formatting depending on the target backend API.

Customizing Encoding with paramsSerializer

If your backend expects a different encoding format (such as comma-separated values for arrays or omitting bracket encoding), you can override default serialization using the paramsSerializer option.

Using Native URLSearchParams

In modern browser and Node.js environments, you can pass a custom function or use URLSearchParams:

axios.get('/api/search', {
  params: { query: 'react & node', filter: 'active' },
  paramsSerializer: (params) => {
    return new URLSearchParams(params).toString();
  }
});

Using the qs Library

For advanced control over encoding indices, array formats, and nested objects, Axios allows third-party serializers like qs:

import qs from 'qs';

axios.get('/api/search', {
  params: { categories: ['books', 'movies'] },
  paramsSerializer: {
    serialize: (params) => qs.stringify(params, { arrayFormat: 'repeat', encode: true })
  }
});