URLSearchParams
URLSearchParams represents the query parameters after the ? in a URL. It is an ordered list of "name = value" pairs, and the same name can appear more than once. It handles encoding and decoding: what you write in is the raw text, what you read out is the raw text, and encoding happens only when it becomes URL text.
A URLSearchParams comes from one of two places: one you create yourself with new is an independent list; one read from the searchParams of a URL stays in sync with that URL, so changing it changes the URL. fetch() also accepts it as a request body and sends the result of toString().
Inheritance: URLSearchParams does not inherit from any class.
For how to change the query parameters of a URL, see the guide Building and parsing URLs.
Constructor
Creates a list from query text, an object, an array, or another URLSearchParams.
Instance properties
| Property | Description |
|---|---|
size read-only | The number of parameters; parameters with the same name are counted separately |
Instance methods
Reading:
| Method | Description |
|---|---|
get() | The value of the first parameter with the name |
getAll() | The values of all parameters with the name |
has() | Whether the parameter exists |
toString() | The encoded query text, without ? |
Changing:
| Method | Description |
|---|---|
append() | Adds a parameter at the end |
set() | Sets a name to one value, keeping only one parameter with that name |
delete() | Deletes the parameters with a name |
sort() | Sorts by name |
Iterating:
| Method | Description |
|---|---|
keys() | Yields the names in order |
values() | Yields the values in order |
entries() | Yields [name, value] in order. Iterating directly with for...of is the same as this |
forEach() | Calls a callback once for each parameter |
Encoding rules
Query parameters use the form encoding rules, which differ from those of the URL's path:
- A space is encoded as
+. In the path, a space is%20. - Chinese and other non-ASCII characters are encoded as
%XXusing UTF-8. - Characters with meaning in a query, such as
&,=, and+, are encoded so they don't break the structure of the URL.
Writing '中 文' in gives %E4%B8%AD+%E6%96%87, and reading it back still gives '中 文'.
Examples
The code below changes the query parameters of a URL. It needs no UI and runs when written directly at the top level of main.js.
const url = new URL('https://api.example.com/search?page=1');
url.searchParams.set('page', '2');
url.searchParams.append('q', '中 文');
console.log(url.href);
const params = new URLSearchParams('a=1&b=2&a=3');
console.log(params.getAll('a'), params.size);Result
- Logs
https://api.example.com/search?page=2&q=%E4%B8%AD+%E6%96%87. - Logs
['1', '3'] 3.
This code has not been run as a whole in the simulator. Every API it uses has been run in the acceptance tests.
Differences from the web
Same as the web.
See also
- Building and parsing URLs: several ways to change query parameters
URL: thesearchParamsproperty stays in sync with the URLfetch(): sending aURLSearchParamsas the request body