W3cubDocs

/Web APIs

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

js

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.

Instance properties

size

Indicates the total number of search parameter entries.

Instance methods

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 iterator allowing 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 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

js

const paramsString = "q=URLUtils.searchParams&topic=api";
const searchParams = new URLSearchParams(paramsString);

// Iterating the search parameters
for (const p of searchParams) {
  console.log(p);
}

console.log(searchParams.has("topic")); // true
console.log(searchParams.has("topic", "fish")); // false
console.log(searchParams.get("topic") === "api"); // true
console.log(searchParams.getAll("topic")); // ["api"]
console.log(searchParams.get("foo") === null); // true
console.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"

js

// 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")); // true
console.log(searchParams.get("foo")); // "bar"

Duplicate search parameters

js

const paramStr = "foo=bar&foo=baz";
const searchParams = new URLSearchParams(paramStr);

console.log(searchParams.toString()); // "foo=bar&foo=baz"
console.log(searchParams.has("foo")); // true
console.log(searchParams.get("foo")); // bar, only returns the first value
console.log(searchParams.getAll("foo")); // ["bar", "baz"]

No URL parsing

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

js

const paramsString1 = "http://example.com/search?query=%40";
const searchParams1 = new URLSearchParams(paramsString1);

console.log(searchParams1.has("query")); // false
console.log(searchParams1.has("http://example.com/search?query")); // true

console.log(searchParams1.get("query")); // null
console.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")); // true

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

Preserving plus signs

The URLSearchParams constructor interprets plus signs (+) as spaces, which might cause problems. In the example below, we use hexadecimal 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 by btoa() contains + and isn't preserved by URLSearchParams.

js

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 spaces

console.log(atob(binQuery) === rawData); // false

You can avoid this by encoding the data with the encodeURIComponent().

js

const rawData = "\x13à\x17@\x1F\x80";
const base64Data = btoa(rawData); // 'E+AXQB+A'
const encodedBase64Data = encodeURIComponent(base64Data); // 'E%2BAXQB%2BA'

const searchParams = new URLSearchParams(`bin=${encodedBase64Data}`); // 'bin=E%2BAXQB%2BA'
const binQuery = searchParams.get("bin"); // 'E+AXQB+A'

console.log(atob(binQuery) === rawData); // true

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.

js

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

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
@@iterator 49 17 44 No 36 10.1 49 49 44 36 10.3 5.0
URLSearchParams 49 17 29 No 36 10.1 49 49 29 36 10.3 5.0
URLSearchParams 49 17
29Before version 57 single quotes in URLs were escaped (see bug 1386683).
No 36 10.1 49 49
29Before version 57 single quotes in URLs were escaped (see bug 1386683).
36 10.3 5.0
append 49 17 29 No 36 10.1 49 49 29 36 10.3 5.0
delete 49 17 29 No 36 14
10.1Removing a non-existent query parameter doesn't remove ? from the URL. See bug 193022.
49 49 29 36 14
10.3Removing a non-existent query parameter doesn't remove ? from the URL. See bug 193022.
5.0
entries 49 17 44 No 36 10.1 49 49 44 36 10.3 5.0
forEach 49 17 44 No 36 10.1 49 49 44 36 10.3 5.0
get 49 17 29 No 36 10.1 49 49 29 36 10.3 5.0
getAll 49 17 29 No 36 10.1 49 49 29 36 10.3 5.0
has 49 17 29 No 36 10.1 49 49 29 36 10.3 5.0
keys 49 17 44 No 36 10.1 49 49 44 36 10.3 5.0
set 49 17 29 No 36 10.1 49 49 29 36 10.3 5.0
size 113 113 112 No 99 17 113 113 112 No 17 No
sort 61 17 54 No 48 11 61 61 54 45 11 8.0
toString 49 17 29 No 36 10.1 49 49 29 36 10.3 5.0
values 49 17 44 No 36 10.1 49 49 44 36 10.3 5.0

See also

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams