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 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
URL
The definition of 'URLSearchParams' in that specification.
Living Standard Initial definition.

Browser compatibility

DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
URLSearchParamsChrome Full support 49Edge Full support 17Firefox 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 NoOpera Full support 36Safari Full support 10.1WebView Android Full support 49Chrome Android Full support 49Firefox 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 36Safari iOS Full support 10.3Samsung Internet Android Full support 5.0
URLSearchParams() constructorChrome Full support 49Edge Full support 17Firefox Full support 29IE No support NoOpera Full support 36Safari Full support 10.1WebView Android Full support 49Chrome Android Full support 49Firefox Android Full support 29Opera Android Full support 36Safari iOS Full support 10.3Samsung Internet Android Full support 5.0
appendChrome Full support 49Edge Full support 17Firefox Full support 29IE No support NoOpera Full support 36Safari Full support 10.1WebView Android Full support 49Chrome Android Full support 49Firefox Android Full support 29Opera Android Full support 36Safari iOS Full support 10.3Samsung Internet Android Full support 5.0
deleteChrome Full support 49Edge Full support 17Firefox Full support 29IE No support NoOpera Full support 36Safari 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 49Chrome Android Full support 49Firefox Android Full support 29Opera Android Full support 36Safari 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
entriesChrome Full support 49Edge Full support 17Firefox Full support 44IE No support NoOpera Full support 36Safari Full support YesWebView Android Full support 49Chrome Android Full support 49Firefox Android Full support 44Opera Android Full support 36Safari iOS Full support YesSamsung Internet Android Full support 5.0
forEachChrome Full support 49Edge Full support 17Firefox Full support 44IE No support NoOpera Full support 36Safari Full support YesWebView Android Full support 49Chrome Android Full support 49Firefox Android Full support 44Opera Android Full support 36Safari iOS Full support YesSamsung Internet Android Full support 5.0
getChrome Full support 49Edge Full support 17Firefox Full support 29IE No support NoOpera Full support 36Safari Full support YesWebView Android Full support 49Chrome Android Full support 49Firefox Android Full support 29Opera Android Full support 36Safari iOS Full support YesSamsung Internet Android Full support 5.0
getAllChrome Full support 49Edge Full support 17Firefox Full support 29IE No support NoOpera Full support 36Safari Full support YesWebView Android Full support 49Chrome Android Full support 49Firefox Android Full support 29Opera Android Full support 36Safari iOS Full support YesSamsung Internet Android Full support 5.0
hasChrome Full support 49Edge Full support 17Firefox Full support 29IE No support NoOpera Full support 36Safari Full support YesWebView Android Full support 49Chrome Android Full support 49Firefox Android Full support 29Opera Android Full support 36Safari iOS Full support YesSamsung Internet Android Full support 5.0
keysChrome Full support 49Edge Full support 17Firefox Full support 44IE No support NoOpera Full support 36Safari Full support YesWebView Android Full support 49Chrome Android Full support 49Firefox Android Full support 44Opera Android Full support 36Safari iOS Full support YesSamsung Internet Android Full support 5.0
setChrome Full support 49Edge Full support 17Firefox Full support 29IE No support NoOpera Full support 36Safari Full support YesWebView Android Full support 49Chrome Android Full support 49Firefox Android Full support 29Opera Android Full support 36Safari iOS Full support YesSamsung Internet Android Full support 5.0
sortChrome Full support 61Edge Full support 17Firefox Full support 54IE No support NoOpera Full support 48Safari Full support YesWebView Android Full support 61Chrome Android Full support 61Firefox Android Full support 54Opera Android Full support 45Safari iOS Full support YesSamsung Internet Android Full support 8.0
toStringChrome Full support 49Edge Full support 17Firefox Full support 29IE No support NoOpera Full support 36Safari Full support YesWebView Android Full support 49Chrome Android Full support 49Firefox Android Full support 29Opera Android Full support 36Safari iOS Full support YesSamsung Internet Android Full support 5.0
valuesChrome Full support 49Edge Full support 17Firefox Full support 44IE No support NoOpera Full support 36Safari Full support YesWebView Android Full support 49Chrome Android Full support 49Firefox Android Full support 44Opera Android Full support 36Safari iOS Full support YesSamsung 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