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 |
---|---|---|
URL The 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.
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
URLSearchParams | 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 |
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
| 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
| 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