Node.js Reference Β· path, os and url
The Node.js URLSearchParams class
Reference for URLSearchParams in Node.js: read, add, change and delete query parameters, iterate, sort and serialize without manual encoding.
URLSearchParams is a global class for working with the query string of a URL: the part after ?, made of name=value pairs separated by &. It handles percent-encoding for you, supports repeated names and keeps pairs in order.
You can create one from a string, an object, an array of pairs or an iterable such as a Map. Every URL has a live searchParams property; changing it updates url.search and url.href, and the other way round.
const params = new URLSearchParams("a=1&b=2"); params.append("c", "3"); console.log(params.toString());
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input Β· what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input Β· what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
new URLSearchParams(init?: string | Record<string, string> | Iterable<[string, string]> | URLSearchParams)
| Method / property | Description |
|---|---|
append(name, value) |
Adds a pair at the end, even if the name already exists. |
delete(name, value?) |
Removes all pairs with the name (or only those with that value). |
get(name) |
First value for the name, or null. |
getAll(name) |
Array of every value for the name. |
has(name, value?) |
Whether such a pair exists. |
set(name, value) |
Replaces the first pair with the name and removes the others; appends if none exists. |
sort() |
Sorts pairs by name; the order of equal names is kept. |
size |
Number of pairs. |
keys(), values(), entries(), forEach() |
Iteration. The object itself is iterable and yields [name, value] pairs. |
toString() |
The serialized query string, without the leading ?. |
Returns: get() returns a string or null; the other methods return undefined except getAll(), toString() and the iterators.
Usage notes
- Every value is a string.
set("n", 5)stores"5", andget("n")returns"5". Convert numbers and booleans yourself. +means space when parsing and serializing, as in HTML forms. A literal plus becomes%2B.- Repeated names are legal.
Object.fromEntries()keeps only the last value, so usegetAll()when you need all of them. - A leading
?in the input string is ignored.new URLSearchParams("?a=1")works. - Passing an object copies it once; later changes to the object do not affect the params.
- Prefer it to the legacy
querystringmodule for new code, because it follows the same rules as browsers. - Do not build URLs by string concatenation. Missing encoding is a classic source of bugs and injection.
sizeand thevalueargument ofhas()anddelete()are newer features (Node.js 19.8 and 18.18); older runtimes ignore the extra argument.
Related
URL,querystringmodule- Lessons: The url module