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, 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 URLSearchParamsobject 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 iteratorallowing iteration through all key/value pairs contained in this object.
- 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 iteratorallowing 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 iteratorallowing 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
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
| Specification | 
|---|
| URL Standard (URL) # urlsearchparams | 
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 | 10.1 Removing a non-existent query parameter doesn't remove  ?from the URL. See bug 193022. | 49 | 49 | 29 | 36 | 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
- A polyfill of URLSearchParamsis available incore-js
- The URLinterface.
- Google Developers: Easy URL manipulation with URLSearchParams
    © 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