The URLSearchParams
interface defines utility methods to work with the query string of a URL.
An object implementing URLSearchParams
can directly be used in a for...of
structure to iterate over key/value pairs in the same order as they appear in the query string, for example the following two lines are equivalent:
for (const [key, value] of mySearchParams) {
}
for (const [key, value] of mySearchParams.entries()) {
}
const paramsString = "q=URLUtils.searchParams&topic=api";
const searchParams = new URLSearchParams(paramsString);
for (const p of searchParams) {
console.log(p);
}
console.log(searchParams.has("topic"));
console.log(searchParams.has("topic", "fish"));
console.log(searchParams.get("topic") === "api");
console.log(searchParams.getAll("topic"));
console.log(searchParams.get("foo") === null);
console.log(searchParams.append("topic", "webdev"));
console.log(searchParams.toString());
console.log(searchParams.set("topic", "More webdev"));
console.log(searchParams.toString());
console.log(searchParams.delete("topic"));
console.log(searchParams.toString());
const paramsObj = { foo: "bar", baz: "bar" };
const searchParams = new URLSearchParams(paramsObj);
console.log(searchParams.toString());
console.log(searchParams.has("foo"));
console.log(searchParams.get("foo"));
const paramStr = "foo=bar&foo=baz";
const searchParams = new URLSearchParams(paramStr);
console.log(searchParams.toString());
console.log(searchParams.has("foo"));
console.log(searchParams.get("foo"));
console.log(searchParams.getAll("foo"));
The URLSearchParams
constructor does not parse full URLs. However, it will strip an initial leading ?
off of a string, if present.
const paramsString1 = "http://example.com/search?query=%40";
const searchParams1 = new URLSearchParams(paramsString1);
console.log(searchParams1.has("query"));
console.log(searchParams1.has("http://example.com/search?query"));
console.log(searchParams1.get("query"));
console.log(searchParams1.get("http://example.com/search?query"));
const paramsString2 = "?query=value";
const searchParams2 = new URLSearchParams(paramsString2);
console.log(searchParams2.has("query"));
const url = new URL("http://example.com/search?query=%40");
const searchParams3 = new URLSearchParams(url.search);
console.log(searchParams3.has("query"));
The URLSearchParams
constructor interprets plus signs (+
) as spaces, which might cause problems. In the example below, we use hexadecimal escape sequences to mimic a string containing binary data (where every byte carries information) that needs to be stored in the URL search params. Note how the encoded string produced by btoa()
contains +
and isn't preserved by URLSearchParams
.
const rawData = "\x13à\x17@\x1F\x80";
const base64Data = btoa(rawData);
const searchParams = new URLSearchParams(`bin=${base64Data}`);
const binQuery = searchParams.get("bin");
console.log(atob(binQuery) === rawData);
You can avoid this by encoding the data with the encodeURIComponent()
.
const rawData = "\x13à\x17@\x1F\x80";
const base64Data = btoa(rawData);
const encodedBase64Data = encodeURIComponent(base64Data);
const searchParams = new URLSearchParams(`bin=${encodedBase64Data}`);
const binQuery = searchParams.get("bin");
console.log(atob(binQuery) === rawData);
URLSearchParams
doesn't distinguish between a parameter with nothing after the =
, and a parameter that doesn't have a =
altogether.
const emptyVal = new URLSearchParams("foo=&bar=baz");
console.log(emptyVal.get("foo"));
const noEquals = new URLSearchParams("foo&bar=baz");
console.log(noEquals.get("foo"));
console.log(noEquals.toString());