JavaScript Reference ยท Browser and Web APIs
The URLSearchParams class
Reference for URLSearchParams: parse and build query strings, read repeated keys, iterate, sort, encode safely, and connect it to URL and fetch().
URLSearchParams reads and builds the query string of a URL, the part after ?. It decodes percent escapes on the way in, encodes them on the way out, and keeps repeated keys (tag=a&tag=b) in order. You get one from url.searchParams, or create your own from a string, an object or a list of pairs.
An instance is iterable, so it works with for...of, spreading and Object.fromEntries(). It is also accepted as a fetch() body, where it is sent as application/x-www-form-urlencoded.
const params = new URLSearchParams({ q: "tea", page: 2 }); console.log(params.toString());
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
new URLSearchParams() new URLSearchParams("a=1&b=2") // string; a leading ? is ignored new URLSearchParams({ a: 1, b: 2 }) // object (values become strings) new URLSearchParams([["a", "1"], ["a", "2"]]) // pairs, keeps duplicates
| Method or property | Description |
|---|---|
append(name, value) |
Adds a pair at the end, even if the name exists. |
set(name, value) |
Replaces the first pair of that name and removes the rest, or appends if none. |
get(name) |
First value as a string, or null. |
getAll(name) |
Array of all values for the name. |
has(name) |
true if the name exists. Newer browsers also accept a value: has(name, value). |
delete(name) |
Removes all pairs with that name. Newer browsers accept delete(name, value). |
sort() |
Sorts pairs by name; the order of equal names is kept. |
toString() |
Serialized query without the leading ?. |
forEach(), entries(), keys(), values() |
Iteration. The object itself is iterable. |
size |
Number of pairs (newer). |
Exceptions: none in normal use. Values are converted with string conversion, so undefined becomes the text "undefined".
Usage notes
- Everything is a string.
params.get("page")returns"2"; convert withNumber()and handlenullfor missing keys. - Spaces become
+intoString(), whileencodeURIComponent()uses%20. Both decode correctly in query strings. url.searchParamsis live. Changing it updatesurl.searchandurl.href, and the other way around.- Repeated keys.
get()returns only the first; usegetAll(). A plain object cannot represent repeats. - Skip empty values yourself.
params.set("q", "")still outputsq=. Check before setting if you want it omitted. - Not for paths or hashes. It handles only the query. For path segments, edit
url.pathname. - Form data.
new URLSearchParams(new FormData(form))serializes a form for a GET request, but file inputs do not work this way. - Order is preserved, which matters for signed URLs; call
sort()only when you need a canonical form.
Browser support
URLSearchParams is supported in every current browser and in Node.js. The size property and the value arguments of has() and delete() are recent, so check a compatibility table.