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
Specifications
Specification | Status | Comment |
---|---|---|
URLThe definition of 'URLSearchParams' in that specification. | Living Standard | Initial definition. |
Browser compatibility
The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Update compatibility data on GitHub
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
URLSearchParams
|
Chrome
Full support 49 |
Edge
Full support 17 |
Firefox Full support 29 Full support 29 Notes' Prior to version 57 single quotes in URLs were escaped (see bug 1386683). |
IE
No support No |
Opera
Full support 36 |
Safari
Full support 10.1 |
WebView Android
Full support 49 |
Chrome Android
Full support 49 |
Firefox Android Full support 29 Full support 29 Notes' Prior to version 57 single quotes in URLs were escaped (see bug 1386683). |
Opera Android
Full support 36 |
Safari iOS
Full support 10.3 |
Samsung Internet Android
Full support 5.0 |
URLSearchParams() constructor
|
Chrome
Full support 49 |
Edge
Full support 17 |
Firefox
Full support 29 |
IE
No support No |
Opera
Full support 36 |
Safari
Full support 10.1 |
WebView Android
Full support 49 |
Chrome Android
Full support 49 |
Firefox Android
Full support 29 |
Opera Android
Full support 36 |
Safari iOS
Full support 10.3 |
Samsung Internet Android
Full support 5.0 |
append
|
Chrome
Full support 49 |
Edge
Full support 17 |
Firefox
Full support 29 |
IE
No support No |
Opera
Full support 36 |
Safari
Full support 10.1 |
WebView Android
Full support 49 |
Chrome Android
Full support 49 |
Firefox Android
Full support 29 |
Opera Android
Full support 36 |
Safari iOS
Full support 10.3 |
Samsung Internet Android
Full support 5.0 |
delete
|
Chrome
Full support 49 |
Edge
Full support 17 |
Firefox
Full support 29 |
IE
No support No |
Opera
Full support 36 |
Safari Partial support Partial Partial support Partial Notes' Removing a non-existent query parameter doesn't remove |
WebView Android
Full support 49 |
Chrome Android
Full support 49 |
Firefox Android
Full support 29 |
Opera Android
Full support 36 |
Safari iOS Partial support Partial Partial support Partial Notes' Removing a non-existent query parameter doesn't remove |
Samsung Internet Android
Full support 5.0 |
entries
|
Chrome
Full support 49 |
Edge
Full support 17 |
Firefox
Full support 44 |
IE
No support No |
Opera
Full support 36 |
Safari
Full support Yes |
WebView Android
Full support 49 |
Chrome Android
Full support 49 |
Firefox Android
Full support 44 |
Opera Android
Full support 36 |
Safari iOS
Full support Yes |
Samsung Internet Android
Full support 5.0 |
forEach
|
Chrome
Full support 49 |
Edge
Full support 17 |
Firefox
Full support 44 |
IE
No support No |
Opera
Full support 36 |
Safari
Full support Yes |
WebView Android
Full support 49 |
Chrome Android
Full support 49 |
Firefox Android
Full support 44 |
Opera Android
Full support 36 |
Safari iOS
Full support Yes |
Samsung Internet Android
Full support 5.0 |
get
|
Chrome
Full support 49 |
Edge
Full support 17 |
Firefox
Full support 29 |
IE
No support No |
Opera
Full support 36 |
Safari
Full support Yes |
WebView Android
Full support 49 |
Chrome Android
Full support 49 |
Firefox Android
Full support 29 |
Opera Android
Full support 36 |
Safari iOS
Full support Yes |
Samsung Internet Android
Full support 5.0 |
getAll
|
Chrome
Full support 49 |
Edge
Full support 17 |
Firefox
Full support 29 |
IE
No support No |
Opera
Full support 36 |
Safari
Full support Yes |
WebView Android
Full support 49 |
Chrome Android
Full support 49 |
Firefox Android
Full support 29 |
Opera Android
Full support 36 |
Safari iOS
Full support Yes |
Samsung Internet Android
Full support 5.0 |
has
|
Chrome
Full support 49 |
Edge
Full support 17 |
Firefox
Full support 29 |
IE
No support No |
Opera
Full support 36 |
Safari
Full support Yes |
WebView Android
Full support 49 |
Chrome Android
Full support 49 |
Firefox Android
Full support 29 |
Opera Android
Full support 36 |
Safari iOS
Full support Yes |
Samsung Internet Android
Full support 5.0 |
keys
|
Chrome
Full support 49 |
Edge
Full support 17 |
Firefox
Full support 44 |
IE
No support No |
Opera
Full support 36 |
Safari
Full support Yes |
WebView Android
Full support 49 |
Chrome Android
Full support 49 |
Firefox Android
Full support 44 |
Opera Android
Full support 36 |
Safari iOS
Full support Yes |
Samsung Internet Android
Full support 5.0 |
set
|
Chrome
Full support 49 |
Edge
Full support 17 |
Firefox
Full support 29 |
IE
No support No |
Opera
Full support 36 |
Safari
Full support Yes |
WebView Android
Full support 49 |
Chrome Android
Full support 49 |
Firefox Android
Full support 29 |
Opera Android
Full support 36 |
Safari iOS
Full support Yes |
Samsung Internet Android
Full support 5.0 |
sort
|
Chrome
Full support 61 |
Edge
Full support 17 |
Firefox
Full support 54 |
IE
No support No |
Opera
Full support 48 |
Safari
Full support Yes |
WebView Android
Full support 61 |
Chrome Android
Full support 61 |
Firefox Android
Full support 54 |
Opera Android
Full support 45 |
Safari iOS
Full support Yes |
Samsung Internet Android
Full support 8.0 |
toString
|
Chrome
Full support 49 |
Edge
Full support 17 |
Firefox
Full support 29 |
IE
No support No |
Opera
Full support 36 |
Safari
Full support Yes |
WebView Android
Full support 49 |
Chrome Android
Full support 49 |
Firefox Android
Full support 29 |
Opera Android
Full support 36 |
Safari iOS
Full support Yes |
Samsung Internet Android
Full support 5.0 |
values
|
Chrome
Full support 49 |
Edge
Full support 17 |
Firefox
Full support 44 |
IE
No support No |
Opera
Full support 36 |
Safari
Full support Yes |
WebView Android
Full support 49 |
Chrome Android
Full support 49 |
Firefox Android
Full support 44 |
Opera Android
Full support 36 |
Safari iOS
Full support Yes |
Samsung Internet Android
Full support 5.0 |
Legend
- Full support
- Full support
- Partial support
- Partial support
- No support
- No support
- See implementation notes.'
- See implementation notes.
See also
- The
URL
interface. - Google Developers: Easy URL manipulation with URLSearchParams
URLSearchParams by Mozilla Contributors is licensed under CC-BY-SA 2.5.