dom / latest / urlsearchparams / urlsearchparams.html /

URLSearchParams()

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

Note: This feature is available in Web Workers

Syntax

new URLSearchParams(init);

Parameters

init Optional

One of:

  • A USVString, which will be parsed from application/x-www-form-urlencoded format. A leading '?' character is ignored.
  • 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 USVString keys and USVString values.

Return value

A URLSearchParams object instance.

Examples

The following example shows how to create a URLSearchParams object from a URL string.

// Retrieve params via url.search, passed into ctor
var url = new URL('https://example.com?foo=1&bar=2');
var params = new URLSearchParams(url.search);

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

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

// Pass in a record
var 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.

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),
    ]).toString()}`
  );

Specifications

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
URLSearchParams
49
17
29
No
36
10.1
49
49
29
36
10.3
5.0
USVString
49
17
29
No
36
10.1
49
49
29
36
10.3
5.0
record
61
17
54
No
48
11
61
61
54
45
11
8.0
sequence
58
17
53
No
45
11
58
58
53
43
11
7.2

© 2005–2021 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/URLSearchParams