URLSearchParams

The URLSearchParams interface defines utility methods to work with the query string of a URL.

An object implementing URLSearchParams can directly be used in a for...of structure to iterate over key/value pairs in the same order as they appear in the query string, for example the following two lines are equivalent:

for (const [key, value] of mySearchParams) {}
for (const [key, value] of mySearchParams.entries()) {}

Note: This feature is available in Web Workers

Constructor

URLSearchParams()

Returns a URLSearchParams object instance.

Methods

URLSearchParams.append()

Appends a specified key/value pair as a new search parameter.

URLSearchParams.delete()

Deletes the given search parameter, and its associated value, from the list of all search parameters.

URLSearchParams.entries()

Returns an iterator allowing iteration through all key/value pairs contained in this object in the same order as they appear in the query string.

URLSearchParams.forEach()

Allows iteration through all values contained in this object via a callback function.

URLSearchParams.get()

Returns the first value associated with the given search parameter.

URLSearchParams.getAll()

Returns all the values associated with a given search parameter.

URLSearchParams.has()

Returns a boolean value indicating if such a given parameter exists.

URLSearchParams.keys()

Returns an iterator allowing iteration through all keys of the key/value pairs contained in this object.

URLSearchParams.set()

Sets the value associated with a given search parameter to the given value. If there are several values, the others are deleted.

URLSearchParams.sort()

Sorts all key/value pairs, if any, by their keys.

URLSearchParams.toString()

Returns a string containing a query string suitable for use in a URL.

URLSearchParams.values()

Returns an iterator allowing iteration through all values of the key/value pairs contained in this object.

Examples

const paramsString = 'q=URLUtils.searchParams&topic=api';
const searchParams = new URLSearchParams(paramsString);

// Iterating the search parameters
for (const p of searchParams) {
  console.log(p);
}

searchParams.has('topic') === true;      // true
searchParams.get('topic') === "api";     // true
searchParams.getAll('topic');            // ["api"]
searchParams.get('foo') === null;        // true
searchParams.append('topic', 'webdev');
searchParams.toString();                 // "q=URLUtils.searchParams&topic=api&topic=webdev"
searchParams.set('topic', 'More webdev');
searchParams.toString();                 // "q=URLUtils.searchParams&topic=More+webdev"
searchParams.delete('topic');
searchParams.toString();                 // "q=URLUtils.searchParams"
// Search parameters can also be an object
const paramsObj = {foo: 'bar', baz: 'bar'};
const searchParams = new URLSearchParams(paramsObj);

searchParams.toString();                 // "foo=bar&baz=bar"
searchParams.has('foo');                 // true
searchParams.get('foo');     

Duplicate search parameters

const paramStr = 'foo=bar&foo=baz';
const searchParams = new URLSearchParams(paramStr);

searchParams.toString();                 // "foo=bar&foo=baz"
searchParams.has('foo');                 // true
searchParams.get('foo');                 // bar, only returns the first value
searchParams.getAll('foo');              // ["bar", "baz"]

No URL parsing

The URLSearchParams constructor does not parse full URLs. However, it will strip an initial leading ? off of a string, if present.

const paramsString1 = 'http://example.com/search?query=%40';
const searchParams1 = new URLSearchParams(paramsString1);

searchParams1.has('query'); // false
searchParams1.has('http://example.com/search?query'); // true

searchParams1.get('query'); // null
searchParams1.get('http://example.com/search?query'); // "@" (equivalent to decodeURIComponent('%40'))

const paramsString2 = '?query=value';
const searchParams2 = new URLSearchParams(paramsString2);
searchParams2.has('query'); // true

const url = new URL('http://example.com/search?query=%40');
const searchParams3 = new URLSearchParams(url.search);
searchParams3.has('query'); // true

Preserving plus signs

The URLSearchParams constructor interprets plus signs (+) as spaces, which might cause problems.

const rawData = '\x13à\x17@\x1F\x80';
const base64Data = btoa(rawData); // 'E+AXQB+A'

const searchParams = new URLSearchParams(`bin=${base64Data}`); // 'bin=E+AXQB+A'
const binQuery = searchParams.get('bin'); // 'E AXQB A', '+' is replaced by spaces

console.log(atob(binQuery) === rawData); // false

You can avoid this by encoding the data with the encodeURIComponent().

const rawData = '\x13à\x17@\x1F\x80';
const base64Data = btoa(rawData); // 'E+AXQB+A'
const encodedBase64Data = encodeURIComponent(base64Data); // 'E%2BAXQB%2BA'

const searchParams = new URLSearchParams(`bin=${encodedBase64Data}`); // 'bin=E%2BAXQB%2BA'
const binQuery = searchParams.get('bin'); // 'E+AXQB+A'

console.log(atob(binQuery) === rawData); // true

Empty value vs. no value

URLSearchParams doesn't distinguish between a parameter with nothing after the =, and a parameter that doesn't have a = altogether.

const emptyVal = new URLSearchParams('foo=&bar=baz');
emptyVal.get('foo'); // returns ''
const noEquals = new URLSearchParams('foo&bar=baz');
noEquals.get('foo'); // also returns ''
noEquals.toString(); // 'foo=&bar=baz'

Specifications

Specification
URL Standard
# urlsearchparams

Browser compatibility

BCD tables only load in the browser

See also