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 April 2018.

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 addParams = {
  c: "a",
  d: 2,
  e: false,
};

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

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

console.log(newURL.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

desktop mobile server
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Bun
Deno
Node.js
URLSearchParams() constructor
Chrome – Full support
Chrome 49 (Release date: 2016-03-02)
footnote Full support
Edge – Full support
Edge 17 (Release date: 2018-04-30)
footnote Full support
Firefox – Full support
Firefox 29 (Release date: 2014-04-29)
footnote Full support
Opera – Full support
Opera 36 (Release date: 2016-03-15)
footnote Full support
Safari – Full support
Safari 10.1 (Release date: 2017-03-27)
footnote Full support
Chrome Android – Full support
Chrome Android 49 (Release date: 2016-03-09)
footnote Full support
Firefox for Android – Full support
Firefox for Android 29 (Release date: 2014-04-29)
footnote Full support
Opera Android – Full support
Opera Android 36 (Release date: 2016-03-31)
footnote Full support
Safari on iOS – Full support
Safari on iOS 10.3 (Release date: 2017-03-27)
footnote Full support
Samsung Internet – Full support
Samsung Internet 5 (Release date: 2016-12-15)
footnote Full support
WebView Android – Full support
WebView Android 49 (Release date: 2016-03-09)
footnote Full support
WebView on iOS – Full support
WebView on iOS 10.3 (Release date: 2017-03-27)
footnote Full support
Bun – Full support
Bun 1 (Release date: 2023-09-08)
footnote Full support
Deno – Full support
Deno 1 (Release date: 2020-05-13)
footnote Full support
Node.js – Full support
Node.js 6.13 (Release date: 2018-02-13)
footnote Full support
USVString for init object
Chrome – Full support
Chrome 49 (Release date: 2016-03-02)
footnote Full support
Edge – Full support
Edge 17 (Release date: 2018-04-30)
footnote Full support
Firefox – Full support
Firefox 29 (Release date: 2014-04-29)
footnote Full support
Opera – Full support
Opera 36 (Release date: 2016-03-15)
footnote Full support
Safari – Full support
Safari 10.1 (Release date: 2017-03-27)
footnote Full support
Chrome Android – Full support
Chrome Android 49 (Release date: 2016-03-09)
footnote Full support
Firefox for Android – Full support
Firefox for Android 29 (Release date: 2014-04-29)
footnote Full support
Opera Android – Full support
Opera Android 36 (Release date: 2016-03-31)
footnote Full support
Safari on iOS – Full support
Safari on iOS 10.3 (Release date: 2017-03-27)
footnote Full support
Samsung Internet – Full support
Samsung Internet 5 (Release date: 2016-12-15)
footnote Full support
WebView Android – Full support
WebView Android 49 (Release date: 2016-03-09)
footnote Full support
WebView on iOS – Full support
WebView on iOS 10.3 (Release date: 2017-03-27)
footnote Full support
Bun – Full support
Bun 1 (Release date: 2023-09-08)
footnote Full support
Deno – Full support
Deno 1 (Release date: 2020-05-13)
footnote Full support
Node.js – No support
Node.js 6.13 – 6.13 (Release date: 2018-02-13)
footnote Removed in 7 and later
Node.js – Full support
Node.js 7.5 (Release date: 2017-01-31)
footnote Full support
record for init object
Chrome – Full support
Chrome 61 (Release date: 2017-09-05)
footnote Full support
Edge – Full support
Edge 17 (Release date: 2018-04-30)
footnote Full support
Firefox – Full support
Firefox 54 (Release date: 2017-06-13)
footnote Full support
Opera – Full support
Opera 48 (Release date: 2017-09-27)
footnote Full support
Safari – Full support
Safari 11 (Release date: 2017-09-19)
footnote Full support
Chrome Android – Full support
Chrome Android 61 (Release date: 2017-09-05)
footnote Full support
Firefox for Android – Full support
Firefox for Android 54 (Release date: 2017-06-13)
footnote Full support
Opera Android – Full support
Opera Android 45 (Release date: 2018-02-15)
footnote Full support
Safari on iOS – Full support
Safari on iOS 11 (Release date: 2017-09-19)
footnote Full support
Samsung Internet – Full support
Samsung Internet 8 (Release date: 2018-07-18)
footnote Full support
WebView Android – Full support
WebView Android 61 (Release date: 2017-09-05)
footnote Full support
WebView on iOS – Full support
WebView on iOS 11 (Release date: 2017-09-19)
footnote Full support
Bun – Full support
Bun 1 (Release date: 2023-09-08)
footnote Full support
Deno – Full support
Deno 1 (Release date: 2020-05-13)
footnote Full support
Node.js – Full support
Node.js 7.10 (Release date: 2017-05-02)
footnote Full support
sequence for init object
Chrome – Full support
Chrome 58 (Release date: 2017-04-19)
footnote Full support
Edge – Full support
Edge 17 (Release date: 2018-04-30)
footnote Full support
Firefox – Full support
Firefox 53 (Release date: 2017-04-19)
footnote Full support
Opera – Full support
Opera 45 (Release date: 2017-05-10)
footnote Full support
Safari – Full support
Safari 11 (Release date: 2017-09-19)
footnote Full support
Chrome Android – Full support
Chrome Android 58 (Release date: 2017-04-25)
footnote Full support
Firefox for Android – Full support
Firefox for Android 53 (Release date: 2017-04-19)
footnote Full support
Opera Android – Full support
Opera Android 43 (Release date: 2017-09-27)
footnote Full support
Safari on iOS – Full support
Safari on iOS 11 (Release date: 2017-09-19)
footnote Full support
Samsung Internet – Full support
Samsung Internet 7.2 (Release date: 2018-06-20)
footnote Full support
WebView Android – Full support
WebView Android 58 (Release date: 2017-04-25)
footnote Full support
WebView on iOS – Full support
WebView on iOS 11 (Release date: 2017-09-19)
footnote Full support
Bun – Full support
Bun 1 (Release date: 2023-09-08)
footnote Full support
Deno – Full support
Deno 1 (Release date: 2020-05-13)
footnote Full support
Node.js – Full support
Node.js 7.10 (Release date: 2017-05-02)
footnote Full support

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Has more compatibility info.