URLSearchParams: URLSearchParams() constructor

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Note: This feature is available in Web Workers.

The URLSearchParams() constructor creates and returns a new URLSearchParams object.

Syntax

js
new URLSearchParams()
new URLSearchParams(options)

Parameters

options Optional

One of:

  • A string, which will be parsed from application/x-www-form-urlencoded format. A leading '?' character is ignored. This is the only form that decodes percent-encoding, and decodes + to U+0020 SPACE.
  • A literal sequence of name-value string pairs, or any object — such as a FormData object — with an iterator that produces a sequence of string pairs. Note that File entries will be serialized as [object File] rather than as their filename (as they would in an application/x-www-form-urlencoded form).
  • A record of string keys and string values. Note that nesting is not supported.

Return value

A URLSearchParams object instance.

Examples

The following example shows how to create a URLSearchParams object from various inputs.

js
// Retrieve params via url.search, passed into constructor
const url = new URL("https://example.com?foo=1&bar=2");
const params1 = new URLSearchParams(url.search);

// Get the URLSearchParams object directly from a URL object
const params1a = url.searchParams;

// Pass in a string literal
const params2 = new URLSearchParams("foo=1&bar=2");
const params2a = new URLSearchParams("?foo=1&bar=2");

// Pass in a sequence of pairs
const params3 = new URLSearchParams([
  ["foo", "1"],
  ["bar", "2"],
]);

// Pass in a record
const params4 = new URLSearchParams({ foo: "1", bar: "2" });

This example shows how to build a new URL with an object of search parameters from an existing URL that has search parameters.

js
const url = new URL("https://example.com/?a=hello&b=world");

console.log(url.href);
// https://example.com/?a=hello&b=world

console.log(url.origin);
// https://example.com

const add_params = {
  c: "a",
  d: new String(2),
  e: false.toString(),
};

const new_params = new URLSearchParams([
  ...Array.from(url.searchParams.entries()), // [["a","hello"],["b","world"]]
  ...Object.entries(add_params), // [["c","a"],["d","2"],["e","false"]]
]).toString();
console.log(new_params);
// a=hello&b=world&c=a&d=2&e=false

const new_url = new URL(`${url.origin}${url.pathname}?${new_params}`);

console.log(new_url.href);
// https://example.com/?a=hello&b=world&c=a&d=2&e=false

// Here it is as a function that accepts (URL, Record<string, string>)
const addSearchParams = (url, params = {}) =>
  new URL(
    `${url.origin}${url.pathname}?${new URLSearchParams([
      ...Array.from(url.searchParams.entries()),
      ...Object.entries(params),
    ])}`,
  );

Specifications

Specification
URL
# dom-urlsearchparams-urlsearchparams

Browser compatibility

Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
URLSearchParams() constructor
USVString for init object
record for init object
sequence for init object