URLSearchParams: Safely Build and Parse URL Queries

Why it exists

Before this API, developers manually parsed query strings with string splits and regular expressions. This was tedious, error-prone, and often forgot to handle URL encoding and decoding correctly, leading to bugs and security issues. URLSearchParams provides a standardized, safe, and convenient way to handle this common task.

The mental model

Treat URLSearchParams as a helper object that turns a messy query string like ?q=search&page=2 into a structured, map-like object you can safely read from and write to. It handles all the tricky encoding and formatting details for you. Instead of building a string, you call methods like set('page', 3), and it takes care of the rest.

How it works

You create a URLSearchParams object from a query string (e.g., new URLSearchParams("q=api&topic=js")). It provides methods to manipulate the parameters. get(key) retrieves the first value for a key. getAll(key) retrieves all values as an array, which is critical for keys that can appear multiple times. set(key, value) replaces any existing values for that key, while append(key, value) adds a new value, allowing for duplicate keys. has(key) checks for existence. Finally, toString() converts the object back into a URL-safe query string.

When to use it

Use it anytime you need to interact with URL query parameters. Three key places are: first, reading initial state from the URL when a page loads (e.g., search terms, filters); second, constructing URLs for API calls with fetch; third, updating the URL in the browser's address bar without a full page reload, in combination with the History API.

When not to use it

It is specifically for the ?key=value part of a URL. Do not use it to parse the path, domain, or hash fragment. It is not a general-purpose key-value store; while it acts like a Map, it has specific behaviors tailored to URL query strings, like the distinction between set and append.

One canonical example

To build a search URL for an API, you can do this:

const params = new URLSearchParams();
params.append('q', 'TypeScript');
params.append('sort', 'stars');
const url = https://api.example.com/search?${params.toString()};

This correctly generates the string q=TypeScript&sort=stars and appends it to the base URL, handling all necessary encoding.