How to Send URL Search Params in Axios

This guide explains how to append custom URL search parameters to your HTTP requests using the params configuration object in Axios. You will learn the basic syntax for sending query strings, how Axios handles URL encoding automatically, and how to customize the serialization of complex data types like arrays and nested objects using paramsSerializer.

Basic Usage of the params Option

When making requests with Axios—most commonly GET requests—you can pass an options object containing a params property. Axios automatically formats these key-value pairs into a properly encoded query string and appends them to the request URL.

import axios from 'axios';

axios.get('https://api.example.com/users', {
  params: {
    role: 'admin',
    status: 'active',
    limit: 25
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

The request above will be sent to: https://api.example.com/users?role=admin&status=active&limit=25

Sending Parameters with Axios Request Config

The params option works across all HTTP methods (GET, POST, PUT, DELETE) by supplying the configuration object.

// Using the generic axios function
axios({
  method: 'get',
  url: 'https://api.example.com/products',
  params: {
    category: 'electronics',
    inStock: true
  }
});

Handling Arrays and Custom Serialization

By default, Axios serializes array parameters using bracket notation:

axios.get('https://api.example.com/filter', {
  params: {
    tags: ['javascript', 'web']
  }
});
// Result: https://api.example.com/filter?tags[]=javascript&tags[]=web

If your target API requires a different format (such as repeated keys tags=javascript&tags=web or comma-separated values tags=javascript,web), you can customize the behavior using the paramsSerializer option.

Using paramsSerializer with Built-in Indexes/Repeat Options

Modern versions of Axios support defining how indexes are handled:

axios.get('https://api.example.com/filter', {
  params: {
    tags: ['javascript', 'web']
  },
  paramsSerializer: {
    indexes: null // Serializes as: tags=javascript&tags=web
  }
});

Using a Custom Serializer Function

You can pass a custom function to paramsSerializer to control the serialization logic using native URLSearchParams or third-party libraries like qs:

import qs from 'qs';

axios.get('https://api.example.com/filter', {
  params: {
    tags: ['javascript', 'web'],
    filter: { active: true }
  },
  paramsSerializer: (params) => {
    return qs.stringify(params, { arrayFormat: 'repeat' });
  }
});

Setting Default Parameters in Axios Instances

If you need to send specific search parameters with every request (such as an API key), define them in an Axios instance:

const apiClient = axios.create({
  baseURL: 'https://api.example.com',
  params: {
    apiKey: 'your_api_key_here'
  }
});

// Sends request to: https://api.example.com/posts?apiKey=your_api_key_here&page=2
apiClient.get('/posts', {
  params: {
    page: 2
  }
});