URLSearchParams
Baseline Widely available *
This feature is well established and works across many devices and browser versions. It’s been available across browsers since April 2018.
* Some parts of this feature may have varying levels of support.
Note: This feature is available inWeb Workers.
TheURLSearchParams interface defines utility methods to work with the query string of a URL.
URLSearchParams objects areiterable, so they can directly be used in afor...of structure to iterate over key/value pairs in the same order as they appear in the query string, for example the following two lines are equivalent:
for (const [key, value] of mySearchParams) {}for (const [key, value] of mySearchParams.entries()) {}AlthoughURLSearchParams is functionally similar to aMap, when iterating, it may suffer from somepitfalls thatMap doesn't encounter due to how it's implemented.
Constructor
URLSearchParams()Returns a
URLSearchParamsobject instance.
Instance properties
sizeRead onlyIndicates the total number of search parameter entries.
Instance methods
URLSearchParams[Symbol.iterator]()Returns an
iteratorallowing iteration through all key/value pairs contained in this object in the same order as they appear in the query string.URLSearchParams.append()Appends a specified key/value pair as a new search parameter.
URLSearchParams.delete()Deletes search parameters that match a name, and optional value, from the list of all search parameters.
URLSearchParams.entries()Returns an
iteratorallowing iteration through all key/value pairs contained in this object in the same order as they appear in the query string.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 a given parameter, or parameter and value pair, 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
Using URLSearchParams
const paramsString = "q=URLUtils.searchParams&topic=api";const searchParams = new URLSearchParams(paramsString);// Iterating the search parametersfor (const p of searchParams) { console.log(p);}console.log(searchParams.has("topic")); // trueconsole.log(searchParams.has("topic", "fish")); // falseconsole.log(searchParams.get("topic") === "api"); // trueconsole.log(searchParams.getAll("topic")); // ["api"]console.log(searchParams.get("foo") === null); // trueconsole.log(searchParams.append("topic", "webdev"));console.log(searchParams.toString()); // "q=URLUtils.searchParams&topic=api&topic=webdev"console.log(searchParams.set("topic", "More webdev"));console.log(searchParams.toString()); // "q=URLUtils.searchParams&topic=More+webdev"console.log(searchParams.delete("topic"));console.log(searchParams.toString()); // "q=URLUtils.searchParams"Search parameters can also be an object.
const paramsObj = { foo: "bar", baz: "bar" };const searchParams = new URLSearchParams(paramsObj);console.log(searchParams.toString()); // "foo=bar&baz=bar"console.log(searchParams.has("foo")); // trueconsole.log(searchParams.get("foo")); // "bar"Parsing window.location
UnlikeURL, theLocation interface does not provide a readily-availablesearchParams property. We can parselocation.search withURLSearchParams.
// Assume page has location:// https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams?foo=aconst paramsString = window.location.search;const searchParams = new URLSearchParams(paramsString);console.log(searchParams.get("foo")); // aDuplicate search parameters
const paramStr = "foo=bar&foo=baz";const searchParams = new URLSearchParams(paramStr);console.log(searchParams.toString()); // "foo=bar&foo=baz"console.log(searchParams.has("foo")); // trueconsole.log(searchParams.get("foo")); // bar, only returns the first valueconsole.log(searchParams.getAll("foo")); // ["bar", "baz"]No URL parsing
TheURLSearchParams constructor doesnot 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);console.log(searchParams1.has("query")); // falseconsole.log(searchParams1.has("http://example.com/search?query")); // trueconsole.log(searchParams1.get("query")); // nullconsole.log(searchParams1.get("http://example.com/search?query")); // "@" (equivalent to decodeURIComponent('%40'))const paramsString2 = "?query=value";const searchParams2 = new URLSearchParams(paramsString2);console.log(searchParams2.has("query")); // trueconst url = new URL("http://example.com/search?query=%40");const searchParams3 = new URLSearchParams(url.search);console.log(searchParams3.has("query")); // truePercent encoding
URLSearchParams objectspercent-encode anything in theapplication/x-www-form-urlencoded percent-encode set (which contains all code points except ASCII alphanumeric,*,-,., and_), and encode U+0020 SPACE as+. However, it only handles percent-encoding when serializing and deserializing full URL search params syntax. When interacting with individual keys and values, you always use the unencoded version.
// Creation from parsing a string: percent-encoding is decodedconst params = new URLSearchParams("%24%25%26=%28%29%2B");// Retrieving all keys/values: only decoded values are returnedconsole.log([...params]); // [["$%&", "()+"]]// Getting an individual value: use the decoded key and get the decoded valueconsole.log(params.get("$%&")); // "()+"console.log(params.get("%24%25%26")); // null// Setting an individual value: use the unencoded key and valueparams.append("$%&$#@+", "$#&*@#()+");// Serializing: percent-encoding is appliedconsole.log(params.toString());// "%24%25%26=%28%29%2B&%24%25%26%24%23%40%2B=%24%23%26*%40%23%28%29%2B"If you append a key/value pair with a percent-encoded key, that key is treated as unencoded and is encoded again.
const params = new URLSearchParams();params.append("%24%26", "value");params.toString(); // "%2524%2526=value"Preserving plus signs
TheURLSearchParams constructor interprets plus signs (+) as spaces, which might cause problems. In the example below, we usehexadecimal escape sequences to mimic a string containing binary data (where every byte carries information) that needs to be stored in the URL search params. Note how the encoded string produced bybtoa() contains+ and isn't preserved byURLSearchParams.
const rawData = "\x13à\x17@\x1F\x80";const base64Data = btoa(rawData); // 'E+AXQB+A'const searchParams = new URLSearchParams(`bin=${base64Data}`); // 'bin=E+AXQB+A'const binQuery = searchParams.get("bin"); // 'E AXQB A', '+' is replaced by spacesconsole.log(atob(binQuery) === rawData); // falseNever constructURLSearchParams objects using dynamically interpolated strings. Instead, use theappend() method, which as mentioned above, interprets all characters as-is.
const rawData = "\x13à\x17@\x1F\x80";const base64Data = btoa(rawData); // 'E+AXQB+A'const searchParams = new URLSearchParams();searchParams.append("bin", base64Data); // 'bin=E%2BAXQB%2BA'const binQuery = searchParams.get("bin"); // 'E+AXQB+A'console.log(atob(binQuery) === rawData); // trueInteraction with URL.searchParams
TheURL.searchParams property exposes the URL'ssearch string as aURLSearchParams object. When updating thisURLSearchParams, the URL'ssearch is updated with its serialization. However,URL.search encodes a subset of characters thatURLSearchParams does, and encodes spaces as%20 instead of+. This may cause some surprising interactions—if you updatesearchParams, even with the same values, the URL may be serialized differently.
const url = new URL("https://example.com/?a=b ~");console.log(url.href); // "https://example.com/?a=b%20~"console.log(url.searchParams.toString()); // "a=b+%7E"// This should be a no-op, but it changes the URL's query to the// serialization of its searchParamsurl.searchParams.sort();console.log(url.href); // "https://example.com/?a=b+%7E"const url2 = new URL("https://example.com?search=1234¶m=my%20param");console.log(url2.search); // "?search=1234¶m=my%20param"url2.searchParams.delete("search");console.log(url2.search); // "?param=my+param"Empty value vs. no value
URLSearchParams 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");console.log(emptyVal.get("foo")); // returns ''const noEquals = new URLSearchParams("foo&bar=baz");console.log(noEquals.get("foo")); // also returns ''console.log(noEquals.toString()); // 'foo=&bar=baz'Specifications
| Specification |
|---|
| URL # urlsearchparams |