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

let base64 = btoa(String.fromCharCode(19,224,23,64,31,128)); // base64 is "E+AXQB+A"
let searchParams = new URLSearchParams("q=foo&bin=" + base64); // q=foo&bin=E+AXQB+A
let 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"

Specifications

Specification
URL Standard (URL)
# urlsearchparams

Browser compatibility

BCD tables only load in the browser

See also