Axios URL Encoding for Non-ASCII Characters

This article examines how the Axios HTTP client processes non-ASCII and Unicode characters within request URLs, distinguishing between URL path endpoints and query parameters. It explains the default encoding behavior across browser and Node.js environments, highlights potential serialization pitfalls, and demonstrates how to ensure reliable percent-encoding for international characters.

Default Encoding for Query Parameters

When passing non-ASCII characters inside the params configuration object, Axios automatically handles the percent-encoding process using standard UTF-8 encoding.

Axios uses an internal helper function that calls JavaScript's encodeURIComponent() on each parameter key and value. This converts multi-byte Unicode characters into their respective percent-encoded hex sequences (for example, é becomes %C3%A9 and 日本語 becomes %E6%97%A5%E6%9C%AC%E8%AA%9E).

// Axios automatically encodes the query parameters
axios.get('/search', {
  params: {
    query: 'café'
  }
});
// Resulting request URL: /search?query=caf%C3%A9

Axios retains specific characters in query strings that are valid according to RFC 3986, such as @, :, $, ,, [, and ], while ensuring non-ASCII characters are safely encoded.

Encoding in the Direct URL Path

Unlike query parameters supplied via params, Axios does not automatically parse and re-encode the main URL path string supplied in the request config (such as axios.get('/api/users/münchen')).

The handling of non-ASCII characters directly inside the URL string depends on the underlying runtime environment:

• Browser Environment: The browser’s native XMLHttpRequest or fetch implementation automatically converts non-ASCII characters in the path to valid percent-encoded UTF-8 sequences before sending the HTTP request over the network.
• Node.js Environment: Axios relies on Node.js core modules (http and https). In modern Node.js versions, the native URL parser handles percent-encoding for non-ASCII characters. However, passing unescaped non-ASCII characters directly into the URL path can lead to inconsistencies or ERR_UNESCAPED_CHARACTERS errors in specific networking configurations.

To guarantee cross-platform consistency, dynamic path segments containing non-ASCII characters should be encoded explicitly using encodeURIComponent() or encodeURI():

const city = 'münchen';
const endpoint = `/api/locations/${encodeURIComponent(city)}`;

axios.get(endpoint);
// Safely executes: /api/locations/m%C3%BCnchen

Customizing Parameter Encoding with paramsSerializer

If your API requires specific handling for non-ASCII characters or complex nested objects, Axios allows you to override the default parameter serialization logic using the paramsSerializer configuration option.

By integrating serialization libraries like qs, you can enforce strict RFC 3986 or RFC 1738 encoding standards:

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

axios.get('/filter', {
  params: { tag: 'über' },
  paramsSerializer: (params) => {
    return qs.stringify(params, { encode: true });
  }
});

Best Practices

1. Use params for Dynamic Values: Always pass dynamic, search, or filter strings containing non-ASCII characters through the params object rather than manually concatenating them onto the URL query string.
2. Explicitly Encode Path Parameters: Wrap dynamic path variables with encodeURIComponent() before interpolating them into endpoint strings.
3. Use a Consistent Serializer: If handling complex nested structures with non-ASCII keys or values, use a custom paramsSerializer with the qs library to ensure standardized percent-encoding across all client platforms.