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:
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 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 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 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
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.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"
// 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
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.
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.
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()
.
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.
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 Standard # urlsearchparams |
Browser compatibility
BCD tables only load in the browser