Skip to content
Tutorials Center
My learning

Topics

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.

JavaScript
const params = new URLSearchParams({ q: "tea", page: 2 });
console.log(params.toString());

Try it

JS Parse and read a query string

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Build, edit and encode

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
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 with Number() and handle null for missing keys.
  • Spaces become + in toString(), while encodeURIComponent() uses %20. Both decode correctly in query strings.
  • url.searchParams is live. Changing it updates url.search and url.href, and the other way around.
  • Repeated keys. get() returns only the first; use getAll(). A plain object cannot represent repeats.
  • Skip empty values yourself. params.set("q", "") still outputs q=. 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.