Working with URL query string parameters with vanilla JavaScript

Yesterday, we learned how to work with URLs and URL strings with JavaScript. Today, we’re going to look at how to get, set, modify, and delete query string parameters.

Let’s dig in!

Quick aside: today’s article is an excerpt from my new Vanilla JS Short on the URL and URLSearchParams APIs.

The new URLSearchParams() constructor

You can use the new URLSearchParams() constructor to create a new URLSearchParams object. Pass in a query string (with or without the leading ?) or a FormData object.

// A query string
let params = new URLSearchParams('product_id=12374&quantity=42');

// A FormData object
let form = document.querySelector('form');
let data = new FormData(form);
let formParams = new URLSearchParams(data);

If you already have a URL object, the URL.searchParams property returns a URLSearchParams object.

// A URL object
let url = new URL('https://gomakethings.com/checkout?product_id=12374&quantity=42');

// Returns a URLSearchParams object
let params = url.searchParams;

Looping over a URLSearchParams object

The URLSearchParams object is an iterable.

You can loop through it using a for...of loop. Each param is an array of key/value pairs.

// logs...
// ["product_id", "12374"]
// ["quantity", "42"]
for (let param of params) {
	console.log(param);
}

You can also use array destructuring to assign the key and value to their own variables within the for...of loop.

// logs "product_id", "12374", etc.
for (let [key, value] of params) {
	console.log(key);
	console.log(value);
}

If you’d prefer, a URLSearchParams instance also has a forEach() method you can use to loop over parameters.

It accepts a callback function to run on each parameter. The callback accepts variables for the value, key, and URLSearchParams object, which are passed in automatically as arguments.

params.forEach(function (value, key) {
	console.log(key);
	console.log(value);
});

Getting, setting, and deleting parameters

The URLSearchParams object has a handful of methods that you can use to get, set, and update query string values.

URLSearchParams.get() & URLSearchParams.getAll()

The URLSearchParams.get() method accepts the key of the parameter as an argument, and returns its value. Here, we would get the value of the product_id parameter.

// returns "12374"
let id = params.get('product_id');

If you had parameters with the same key, you might instead use the URLSearchParams.getAll() method.

It returns an array of values instead.

// returns ["12374"]
let productIDs = params.getAll('product_id');

URLSearchParams.set()

You can use the URLSearchParams.set() method to add a new key/value pair to your URLSearchParams object.

Pass in a key and value as arguments.

If parameter with that key already exists, the URLSearchParams.set() method overwrites it. If more than one item with that key exists, it deletes all of the others.

// Add a new parameter, "discount", to the URLSearchParams object
params.set('discount', 'EARLYBIRD');

// Overwrite the "quantity" parameter
params.set('quantity', '7');

URLSearchParams.delete()

The URLSearchParams.delete() method deletes all values for a key.

Pass in the key to delete as an argument.

// Deletes the "discount" entry
params.delete('discount');

Putting it to use

Tomorrow, we’ll look at how to combine the URL and URLSearchParams APIs with the History API to get a URL, modify some values, and update the URL in the browser without reloading the page.