Skip to content
Tutorials Center
My learning

Topics

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.

NODE
const params = new URLSearchParams("a=1&b=2");
params.append("c", "3");
console.log(params.toString());

Try it

Node.js Reading and writing

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.

Node.js Building, iterating and linking to a URL

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

NODE
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", and get("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 use getAll() 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 querystring module 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.
  • size and the value argument of has() and delete() are newer features (Node.js 19.8 and 18.18); older runtimes ignore the extra argument.