Web/API/URLSearchParams

From Get docs


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 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.
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 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

var paramsString = "q=URLUtils.searchParams&topic=api";
var 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"

Gotchas

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

var paramsString1 = "http://example.com/search?query=%40";
var 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'))

var paramsString2 = "?query=value";
var searchParams2 = new URLSearchParams(paramsString2);
searchParams2.has("query"); // true 

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

Specifications

Specification Status Comment
URLThe definition of 'URLSearchParams' in that specification. Living Standard Initial definition.

Browser compatibility

Update compatibility data on GitHub

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari Android webview Chrome for Android Firefox for Android Opera for Android Safari on iOS Samsung Internet
URLSearchParams Chrome

Full support 49

Edge

Full support 17

Firefox Full support 29

Notes'

Full support 29

Notes'

Notes' Prior to version 57 single quotes in URLs were escaped (see bug 1386683).

IE

No support No

Opera

Full support 36

Safari

Full support 10.1

WebView Android

Full support 49

Chrome Android

Full support 49

Firefox Android Full support 29

Notes'

Full support 29

Notes'

Notes' Prior to version 57 single quotes in URLs were escaped (see bug 1386683).

Opera Android

Full support 36

Safari iOS

Full support 10.3

Samsung Internet Android

Full support 5.0

URLSearchParams() constructor Chrome

Full support 49

Edge

Full support 17

Firefox

Full support 29

IE

No support No

Opera

Full support 36

Safari

Full support 10.1

WebView Android

Full support 49

Chrome Android

Full support 49

Firefox Android

Full support 29

Opera Android

Full support 36

Safari iOS

Full support 10.3

Samsung Internet Android

Full support 5.0

append Chrome

Full support 49

Edge

Full support 17

Firefox

Full support 29

IE

No support No

Opera

Full support 36

Safari

Full support 10.1

WebView Android

Full support 49

Chrome Android

Full support 49

Firefox Android

Full support 29

Opera Android

Full support 36

Safari iOS

Full support 10.3

Samsung Internet Android

Full support 5.0

delete Chrome

Full support 49

Edge

Full support 17

Firefox

Full support 29

IE

No support No

Opera

Full support 36

Safari Partial support Partial

Notes'

Partial support Partial

Notes'

Notes' Removing a non-existent query parameter doesn't remove ? from the URL. See bug 193022.

WebView Android

Full support 49

Chrome Android

Full support 49

Firefox Android

Full support 29

Opera Android

Full support 36

Safari iOS Partial support Partial

Notes'

Partial support Partial

Notes'

Notes' Removing a non-existent query parameter doesn't remove ? from the URL. See bug 193022.

Samsung Internet Android

Full support 5.0

entries Chrome

Full support 49

Edge

Full support 17

Firefox

Full support 44

IE

No support No

Opera

Full support 36

Safari

Full support Yes

WebView Android

Full support 49

Chrome Android

Full support 49

Firefox Android

Full support 44

Opera Android

Full support 36

Safari iOS

Full support Yes

Samsung Internet Android

Full support 5.0

forEach Chrome

Full support 49

Edge

Full support 17

Firefox

Full support 44

IE

No support No

Opera

Full support 36

Safari

Full support Yes

WebView Android

Full support 49

Chrome Android

Full support 49

Firefox Android

Full support 44

Opera Android

Full support 36

Safari iOS

Full support Yes

Samsung Internet Android

Full support 5.0

get Chrome

Full support 49

Edge

Full support 17

Firefox

Full support 29

IE

No support No

Opera

Full support 36

Safari

Full support Yes

WebView Android

Full support 49

Chrome Android

Full support 49

Firefox Android

Full support 29

Opera Android

Full support 36

Safari iOS

Full support Yes

Samsung Internet Android

Full support 5.0

getAll Chrome

Full support 49

Edge

Full support 17

Firefox

Full support 29

IE

No support No

Opera

Full support 36

Safari

Full support Yes

WebView Android

Full support 49

Chrome Android

Full support 49

Firefox Android

Full support 29

Opera Android

Full support 36

Safari iOS

Full support Yes

Samsung Internet Android

Full support 5.0

has Chrome

Full support 49

Edge

Full support 17

Firefox

Full support 29

IE

No support No

Opera

Full support 36

Safari

Full support Yes

WebView Android

Full support 49

Chrome Android

Full support 49

Firefox Android

Full support 29

Opera Android

Full support 36

Safari iOS

Full support Yes

Samsung Internet Android

Full support 5.0

keys Chrome

Full support 49

Edge

Full support 17

Firefox

Full support 44

IE

No support No

Opera

Full support 36

Safari

Full support Yes

WebView Android

Full support 49

Chrome Android

Full support 49

Firefox Android

Full support 44

Opera Android

Full support 36

Safari iOS

Full support Yes

Samsung Internet Android

Full support 5.0

set Chrome

Full support 49

Edge

Full support 17

Firefox

Full support 29

IE

No support No

Opera

Full support 36

Safari

Full support Yes

WebView Android

Full support 49

Chrome Android

Full support 49

Firefox Android

Full support 29

Opera Android

Full support 36

Safari iOS

Full support Yes

Samsung Internet Android

Full support 5.0

sort Chrome

Full support 61

Edge

Full support 17

Firefox

Full support 54

IE

No support No

Opera

Full support 48

Safari

Full support Yes

WebView Android

Full support 61

Chrome Android

Full support 61

Firefox Android

Full support 54

Opera Android

Full support 45

Safari iOS

Full support Yes

Samsung Internet Android

Full support 8.0

toString Chrome

Full support 49

Edge

Full support 17

Firefox

Full support 29

IE

No support No

Opera

Full support 36

Safari

Full support Yes

WebView Android

Full support 49

Chrome Android

Full support 49

Firefox Android

Full support 29

Opera Android

Full support 36

Safari iOS

Full support Yes

Samsung Internet Android

Full support 5.0

values Chrome

Full support 49

Edge

Full support 17

Firefox

Full support 44

IE

No support No

Opera

Full support 36

Safari

Full support Yes

WebView Android

Full support 49

Chrome Android

Full support 49

Firefox Android

Full support 44

Opera Android

Full support 36

Safari iOS

Full support Yes

Samsung Internet Android

Full support 5.0

Legend

Full support  
Full support
Partial support  
Partial support
No support  
No support
See implementation notes.'
See implementation notes.


See also