Get query string values with URLSearchParams

The HTTP protocol allows the request to a web page to be made with a query string.

Like this:

https://test.com/?name=roger
https://test.com/hello?name=roger

In this case we have a single query parameter, named name, with the value roger.

You can have multiple parameters, like this:

https://test.com/hello?name=roger&age=20

The parameters passed as a query string are normally used server-side, to generate a proper response. Here’s how you can access query parameters using Node.js.

To access the value of the query inside the browser, using JavaScript, we have a special API called URLSearchParams, supported by every modern browser (and by Node.js too).

Here is how we can use it:

const params = new URLSearchParams(window.location.search)

(if you want to see how a query string breaks down into parameters, I built a free URL parser tool that labels every part of a URL)

If you already have a full URL string, use new URL(href).searchParams from the URL object instead. That gives you a URLSearchParams object with the same methods, linked to that URL: change it and the URL’s href changes too.

Note: don’t pass the full URL as a parameter to URLSearchParams(), but only the query string part of the URL, which you access using window.location.search.

In the case of:

https://test.com/hello?name=roger

window.location.search is equal to the string ?name=roger.

Now that you have the params object, you can query it.

You can check if a parameter was passed:

params.has('test')

You can get the value of a parameter:

params.get('test')

You can iterate over all the parameters, using for..of:

const params = new URLSearchParams(window.location.search)
for (const param of params) {
  console.log(param)
}

A parameter can have more than one value.

In this case, we pass the same parameter name multiple times, like this:

https://test.com/hello?name=roger&name=flavio

If we use params.get('name'), we’ll only get the first value back.

Use params.getAll('name') when the same key appears more than once. It returns an array with every value for that key.

The size property tells you how many key/value pairs are in the object (counting duplicates separately). It arrived in 2023, and every current browser has it.

In addition to has(), get() and getAll(), the URLSearchParams API offers several other methods that we can use to loop through the parameters:

• forEach() iterates over the parameters
• entries() returns an iterator containing the parameters key/values
• keys() returns an iterator containing the parameters keys
• values() returns an iterator containing the parameters values

Other methods to alter the parameters, for use in other JavaScript running in the page (they do not change the URL):

• append() to append a new parameter to the object
• delete() to delete an existing parameter
• set() to set the value of a parameter

We also have sort() to sort parameters by key value, and we have the toString() method to generate a query string from the values.

We can use append() / set() / delete() to edit the query string, and generate a new one with toString().

Want me to talk about your product? You can sponsor this site.