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 (var p of mySearchParams);
for (var p of mySearchParams.entries());

Note: This feature is available in Web Workers.

Constructor

URLSearchParams()
Returns a URLSearchParams object instance.

Properties

This interface doesn't inherit any properties.

Methods

This interface doesn't inherit any 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

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox 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 49Edge Mobile No support NoFirefox 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 YesSamsung Internet Android Full support Yes
URLSearchParams() constructorChrome 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 49Edge Mobile No support NoFirefox Android Full support 29Opera Android Full support 36Safari iOS Full support YesSamsung Internet Android Full support Yes
appendChrome 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 49Edge Mobile No support NoFirefox Android Full support 29Opera Android Full support 36Safari iOS Full support YesSamsung Internet Android Full support Yes
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 49Edge Mobile No support NoFirefox 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 Yes
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 49Edge Mobile No support NoFirefox Android Full support 44Opera Android Full support 36Safari iOS Full support YesSamsung Internet Android Full support Yes
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 49Edge Mobile No support NoFirefox Android Full support 44Opera Android Full support 36Safari iOS Full support YesSamsung Internet Android Full support Yes
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 49Edge Mobile No support NoFirefox Android Full support 29Opera Android Full support 36Safari iOS Full support YesSamsung Internet Android Full support Yes
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 49Edge Mobile No support NoFirefox Android Full support 29Opera Android Full support 36Safari iOS Full support YesSamsung Internet Android Full support Yes
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 49Edge Mobile No support NoFirefox Android Full support 29Opera Android Full support 36Safari iOS Full support YesSamsung Internet Android Full support Yes
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 49Edge Mobile No support NoFirefox Android Full support 44Opera Android Full support 36Safari iOS Full support YesSamsung Internet Android Full support Yes
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 49Edge Mobile No support NoFirefox Android Full support 29Opera Android Full support 36Safari iOS Full support YesSamsung Internet Android Full support Yes
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 61Edge Mobile No support NoFirefox Android Full support 54Opera Android Full support 45Safari iOS Full support YesSamsung Internet Android Full support Yes
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 49Edge Mobile No support NoFirefox Android Full support 29Opera Android Full support 36Safari iOS Full support YesSamsung Internet Android Full support Yes
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 49Edge Mobile No support NoFirefox Android Full support 44Opera Android Full support 36Safari iOS Full support YesSamsung Internet Android Full support Yes

Legend

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

See also