URLSearchParams

Query strings, repeated keys, plus encoding, and live URL.searchParams, verified in Node.js 22.23.3.

モジュールページの本文は現在英語です。

URLSearchParams represents the application/x-www-form-urlencoded query string. It is a Web API, not a String built-in. toString() returns the query without a leading ?. Examples were checked in Node.js 22.23.3.

Repeated keys are stored in order. A + in a query string decodes as a space; a space encodes as +. This page does not send the string as an HTTP request.

Examples were checked in Node.js 22.23.3, which provides these Web APIs as built-in globals. This is not a browser DOM test, and the examples do not send network requests. See the MDN documentation for the complete API, including browser support.

Web APIs overview → · JavaScript tutorial and built-in APIs →

API index

APISummary
URLSearchParams(), get(), getAll(), append(), set(), toString()Parse and serialize query parameters, including repeated keys and plus-encoded spaces.
set(), delete(), sort(), has(), URL.searchParamsReplace, delete, or sort parameters, and observe that URL.searchParams mutates the URL query.

Repeated keys and plus encoding

get("q") returns the first value; getAll("q") returns every value. append adds another q without removing the earlier ones. The example starts from "q=a&q=b&q=c" and appends "d".

new URLSearchParams("q=a+b") yields the value "a b". Setting the value back to "a b" serializes as q=a+b. A literal plus in the value is encoded as %2B, so "a b+c" becomes q=a+b%2Bc. You can also construct from a record or from a sequence of pairs, where a sequence can repeat a key.

URLSearchParams(), get(), getAll(), append(), set(), toString()

new URLSearchParams(init)
URLSearchParams.prototype.get(name)
URLSearchParams.prototype.getAll(name)
URLSearchParams.prototype.append(name, value)
URLSearchParams.prototype.set(name, value)
URLSearchParams.prototype.toString()

Parse and serialize query parameters, including repeated keys and plus-encoded spaces.

ParameterDescription
initA query string without or with a leading ?, an iterable of name/value pairs, or a record of string values.
name, valueThe parameter name and value. get returns the first match; getAll returns every match.

Returns: get returns a string or null. getAll returns an array of strings. toString returns the encoded query without ?.

javascript
const params = new URLSearchParams("q=a&q=b&q=c");
console.log(params.get("q"));
console.log(JSON.stringify(params.getAll("q")));
params.append("q", "d");
console.log(params.toString());

const plus = new URLSearchParams("q=a+b");
console.log(JSON.stringify(plus.get("q")));
plus.set("q", "a b");
console.log(plus.toString());

const encoded = new URLSearchParams();
encoded.set("q", "a b+c");
console.log(encoded.toString());

console.log(new URLSearchParams({ a: "1", b: "2" }).toString());
console.log(new URLSearchParams([["a", "1"], ["a", "2"]]).toString());

Expected output

a
["a","b","c"]
q=a&q=b&q=c&q=d
"a b"
q=a+b
q=a+b%2Bc
a=1&b=2
a=1&a=2

Related: URL

MDN documentation →

Mutations and live URL.searchParams

set replaces all values for a name. delete(name, value) removes one matching pair; delete(name) removes every pair with that name. sort orders by name and keeps relative order for equal names. has(name, value) tests a specific pair.

url.searchParams is live. append on that object updates url.href and url.search. Assigning url.search replaces the query and drops earlier keys that were not in the new string.

set(), delete(), sort(), has(), URL.searchParams

URLSearchParams.prototype.set(name, value)
URLSearchParams.prototype.delete(name)
URLSearchParams.prototype.delete(name, value)
URLSearchParams.prototype.sort()
URLSearchParams.prototype.has(name, value)
url.searchParams

Replace, delete, or sort parameters, and observe that URL.searchParams mutates the URL query.

Returns: The example prints the serialized query, boolean has() results, and the updated href.

  • delete(name, value) and has(name, value) were available in this Node.js 22.23.3 runtime.
javascript
const params = new URLSearchParams("b=2&a=1&a=3");
params.set("a", "9");
console.log(params.toString());
params.delete("a", "9");
console.log(params.toString());
params.delete("b");
params.append("m", "1");
params.append("c", "2");
params.sort();
console.log(params.toString());
console.log(params.has("c", "2"), params.has("c", "9"));

const url = new URL("https://example.com/?a=1");
url.searchParams.append("b", "2");
console.log(url.href);
url.search = "c=3";
console.log(url.searchParams.get("c"));
console.log(url.searchParams.get("a"));

Expected output

b=2&a=9
b=2
c=2&m=1
true false
https://example.com/?a=1&b=2
3
null

MDN documentation →