Understanding paramsSerializer in Axios

This article explores the role of the paramsSerializer configuration in modern versions of the Axios HTTP client. You will learn what paramsSerializer does, why custom serialization is necessary for complex query strings, and how modern Axios (version 1.x and newer) handles parameter serialization using updated configuration objects and custom serializer functions.

What is paramsSerializer?

In Axios, the params option allows you to pass a plain JavaScript object representing URL query parameters. By default, Axios serializes this object into a standard query string appended to the request URL:

axios.get('/api/users', {
  params: { role: 'admin', active: true }
});
// Request URL: /api/users?role=admin&active=true

However, web servers differ in how they expect complex data structures—such as arrays, nested objects, and dates—to be formatted in query strings. The paramsSerializer configuration is an Axios setting that gives you full control over how the params object is converted into a serialized query string before the request is dispatched.

Why Custom Parameter Serialization is Needed

The default parameter serialization in Axios may not match the requirements of every backend API. Common scenarios requiring custom serialization include:

1. Array Serialization: Different backends expect arrays in different formats:
   • Brackets: ids[]=1&ids[]=2 (PHP, Ruby on Rails)
   • Indices: ids[0]=1&ids[1]=2
   • Repeat / No brackets: ids=1&ids=2 (Spring, Django)
   • Comma-separated: ids=1,2
2. Nested Objects: Serializing deeply nested objects into formats like user[profile][name]=John.
3. Custom Encoding: Handling special characters or preserving specific characters without percent-encoding.

The paramsSerializer in Modern Axios (v1.x+)

In Axios v1.0.0 and later, paramsSerializer was overhauled. While older versions primarily accepted a single custom function, modern Axios supports both a dedicated configuration object with built-in options and custom function implementations.

1. Modern Object Configuration

Modern Axios provides built-in array formatting rules directly through the paramsSerializer object, reducing the need for third-party libraries:

import axios from 'axios';

axios.get('/api/filter', {
  params: {
    tags: ['javascript', 'react']
  },
  paramsSerializer: {
    // Controls array serialization format
    indexes: null // null: 'tags=javascript&tags=react'
                  // false: 'tags[]=javascript&tags[]=react'
                  // true:  'tags[0]=javascript&tags[1]=react'
  }
});

• indexes: null: Serializes arrays without brackets (tags=javascript&tags=react).
• indexes: false: Serializes arrays with empty brackets (tags[]=javascript&tags[]=react).
• indexes: true: Serializes arrays with numerical indices (tags[0]=javascript&tags[1]=react).
• encode: A custom encoding function to override standard URL encoding.

2. Custom Serializer Function with serialize

For advanced requirements (such as nested objects or comma-separated lists), you can supply a custom serializer function to the serialize property or directly assign a function. Integrating external libraries like qs remains a common approach:

import axios from 'axios';
import qs from 'qs';

// Using the modern serialize property
axios.get('/api/search', {
  params: {
    filters: { status: 'active', sort: 'desc' },
    tags: ['news', 'updates']
  },
  paramsSerializer: {
    serialize: (params) => {
      return qs.stringify(params, { arrayFormat: 'comma' });
    }
  }
});
// Request URL: /api/search?filters%5Bstatus%5D=active&filters%5Bsort%5D=desc&tags=news,updates

You can also assign a custom serialization function directly to paramsSerializer:

axios.get('/api/search', {
  params: { categories: ['books', 'tech'] },
  paramsSerializer: (params) => {
    return qs.stringify(params, { arrayFormat: 'brackets' });
  }
});

Setting Global Defaults

If your backend API requires a consistent query string format across all requests, you can set paramsSerializer globally on an Axios instance:

import axios from 'axios';
import qs from 'qs';

const apiClient = axios.create({
  baseURL: 'https://api.example.com',
  paramsSerializer: {
    serialize: (params) => qs.stringify(params, { arrayFormat: 'repeat' })
  }
});

// All requests using apiClient will now serialize arrays using the 'repeat' style
export default apiClient;

Summary

The paramsSerializer configuration in modern Axios ensures seamless compatibility between your frontend client and backend query parsing expectations. By supporting both built-in serialization options for common array patterns and custom serialization functions via libraries like qs, modern Axios allows developers to format query parameters precisely without manually constructing query strings.