URLSearchParams

interface

interface URLSearchParams

URLSearchParams provides methods for working with the query string of a URL.

Use this interface to:

  • Parse query parameters from URLs
  • Build and modify query strings
  • Handle form data (when used with FormData)
  • Safely encode/decode URL parameter values

variable

var URLSearchParams: { … }

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.

See also

Constructors

constructor

new URLSearchParams(init?: Iterable<string[]> | Record<string, string> | string | URLSearchParams): URLSearchParams

Creates a new URLSearchParams object for parsing query strings.

URLSearchParams is Ende's built-in query string parser, providing a standard way to parse, manipulate, and stringify URL query parameters. Instead of manually parsing query strings with regex or string operations, use this API for robust handling of URL query parameters.

Example

// From a URL object's query string (recommended approach for parsing query strings in URLs)
const url = new URL('https://example.org/path?foo=bar&baz=qux');
const params = url.searchParams;  // No need to manually extract the query string
console.log(params.get('foo'));  // Logs "bar"

// Manually parsing a query string from a URL
const urlString = 'https://example.org/path?foo=bar&baz=qux';
const queryString = urlString.split('?')[1];  // Extract query string part
const params2 = new URLSearchParams(queryString);
console.log(params2.get('foo'));  // Logs "bar"

// Empty search parameters
const params3 = new URLSearchParams();
console.log(params3.toString());  // Logs ""

// From a string
const params4 = new URLSearchParams("foo=bar&baz=qux");
console.log(params4.get("foo"));  // Logs "bar"

// From an array of pairs
const params5 = new URLSearchParams([["foo", "1"], ["bar", "2"]]);
console.log(params5.toString());  // Logs "foo=1&bar=2"

// From a record object
const params6 = new URLSearchParams({"foo": "1", "bar": "2"});
console.log(params6.toString());  // Logs "foo=1&bar=2"

Properties

size

readonly size: number

Contains the number of search parameters

searchParams.size

prototype

readonly prototype: URLSearchParams

Methods

append

append(name: string, value: string): void

Appends a specified key/value pair as a new search parameter.

let searchParams = new URLSearchParams();
searchParams.append('name', 'first');
searchParams.append('name', 'second');

delete

delete(name: string, value?: string): void

Deletes search parameters that match a name, and optional value, from the list of all search parameters.

let searchParams = new URLSearchParams([['name', 'value']]);
searchParams.delete('name');
searchParams.delete('name', 'value');

getAll

getAll(name: string): string[]

Returns all the values associated with a given search parameter as an array.

searchParams.getAll('name');

get

get(name: string): string | null

Returns the first value associated to the given search parameter.

searchParams.get('name');

has

has(name: string, value?: string): boolean

Returns a boolean value indicating if a given parameter, or parameter and value pair, exists.

searchParams.has('name');
searchParams.has('name', 'value');

set

set(name: string, value: string): void

Sets the value associated with a given search parameter to the given value. If there were several matching values, this method deletes the others. If the search parameter doesn't exist, this method creates it.

searchParams.set('name', 'value');

sort

sort(): void

Sort all key/value pairs contained in this object in place and return undefined. The sort order is according to Unicode code points of the keys.

searchParams.sort();

forEach

forEach(callbackfn: (value: string, key: string, parent: this) => void, thisArg?: any): void

Calls a function for each element contained in this object in place and return undefined. Optionally accepts an object to use as this when executing callback as second argument.

const params = new URLSearchParams([["a", "b"], ["c", "d"]]);
params.forEach((value, key, parent) => {
  console.log(value, key, parent);
});

keys

keys(): URLSearchParamsIterator<string>

Returns an iterator allowing to go through all keys contained in this object.

const params = new URLSearchParams([["a", "b"], ["c", "d"]]);
for (const key of params.keys()) {
  console.log(key);
}

values

values(): URLSearchParamsIterator<string>

Returns an iterator allowing to go through all values contained in this object.

const params = new URLSearchParams([["a", "b"], ["c", "d"]]);
for (const value of params.values()) {
  console.log(value);
}

entries

entries(): URLSearchParamsIterator<[string, string]>

Returns an iterator allowing to go through all key/value pairs contained in this object.

const params = new URLSearchParams([["a", "b"], ["c", "d"]]);
for (const [key, value] of params.entries()) {
  console.log(key, value);
}

[Symbol.iterator]

[Symbol.iterator](): URLSearchParamsIterator<[string, string]>

Returns an iterator allowing to go through all key/value pairs contained in this object.

const params = new URLSearchParams([["a", "b"], ["c", "d"]]);
for (const [key, value] of params) {
  console.log(key, value);
}

toString

toString(): string

Returns a query string suitable for use in a URL.

searchParams.toString();