dom / latest / urlsearchparams.html /

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';
let searchParams = new URLSearchParams(paramsString);

//Iterate the search parameters.
for (let 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
let paramsObj = {foo: 'bar', baz: 'bar'};
let searchParams = new URLSearchParams(paramsObj);

searchParams.toString();                 // "foo=bar&baz=bar"
searchParams.has('foo');                 // true
searchParams.get('foo');                 // bar
// Having duplicate parameters only returns the first value
let paramStr = 'foo=bar&foo=baz';
let searchParams = new URLSearchParams(paramStr);

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

Gotchas

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

It interprets + as a space

const base64 = btoa(String.fromCharCode(19, 224, 23, 64, 31, 128)); // base64 is "E+AXQB+A"
const searchParams = new URLSearchParams('q=foo&bin=' + base64); // q=foo&bin=E+AXQB+A
const getBin = searchParams.get('bin'); // "E AXQB A" + char is replaced by spaces
btoa(atob(getBin)); // "EAXQBA==" no error thrown
btoa(String.fromCharCode(16,5,208,4)) // "EAXQBA==" decodes to wrong binary value
getBin.replace(//g, '+'); // "E+AXQB+A" is one solution

// or use set to add the parameter, but this increases the query string length
searchParams.set('bin2', base64) // "q=foo&bin=E+AXQB+A&bin2=E%2BAXQB%2BA" encodes + as %2B
searchParams.get('bin2'); // "E+AXQB+A"

It 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

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
URLSearchParams
49
17
29
Before version 57 single quotes in URLs were escaped (see bug 1386683).
No
36
10.1
49
49
29
Before version 57 single quotes in URLs were escaped (see bug 1386683).
36
10.3
5.0
URLSearchParams
49
17
29
No
36
10.1
49
49
29
36
10.3
5.0
append
49
17
29
No
36
10.1
49
49
29
36
10.3
5.0
delete
49
17
29
No
36
14
10.1
Removing a non-existent query parameter doesn't remove ? from the URL. See bug 193022.
49
49
29
36
14
10.3
Removing a non-existent query parameter doesn't remove ? from the URL. See bug 193022.
5.0
entries
49
17
44
No
36
10.1
49
49
44
36
10.3
5.0
forEach
49
17
44
No
36
10.1
49
49
44
36
10.3
5.0
get
49
17
29
No
36
10.1
49
49
29
36
10.3
5.0
getAll
49
17
29
No
36
10.1
49
49
29
36
10.3
5.0
has
49
17
29
No
36
10.1
49
49
29
36
10.3
5.0
keys
49
17
44
No
36
10.1
49
49
44
36
10.3
5.0
set
49
17
29
No
36
10.1
49
49
29
36
10.3
5.0
sort
61
17
54
No
48
11
61
61
54
45
11
8.0
toString
49
17
29
No
36
10.1
49
49
29
36
10.3
5.0
values
49
17
44
No
36
10.1
49
49
44
36
10.3
5.0
@@iterator
49
17
44
No
36
10.1
49
49
44
36
10.3
5.0

See also

© 2005–2021 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams