This content originally appeared on Jack Franklin and was authored by Jack Franklin
One of the most common tasks in building a frontend application is to update
query parameters. A quick search for
query string on npm reveals
many options that people have built for tackling this task. But what fewer
people seem to be aware of is that there is now an API for working with query
parameters baked right into the browser and it's called
URLSearchParams.
In this post we'll have a quick play with the API to see how easy it makes
working with query params.
Browser Support
At the time of writing,
browser support for URLSearchParams
is very good. IE11 is the main offender, along with Opera Mini. The good news is
that there is an
excellent polyfill that
you can use to ensure your application will continue to work in browsers that
don't support it natively ?.
Using URLSearchParams
URLSearchParams expects to be given a string of query parameters (with or
without the initial ?). If you've got a full URL that you'd like to parse
query params from, you can use location.search to pull those out:
// Working with the current URL
// URL: buy-shirts-here.com/filter?size=M&colour=red&sleeves=short
location.search //=> ?size=M&colour=red&sleeves=short
// Creating an instance of new URL from scratch works too...
const url = new URL("https://buy-shirts-here.com/filter?filter?size=M&colour=red&sleeves=short")
url.search //=> ?size=M&colour=red&sleeves=shortWe can now that that location.search and pass it to the URLSearchParams
constructor:
const params = new URLSearchParams(location.search)Querying for parameters
We can use has to see if a particular query param is present:
params.has('size') // => true
params.has('button-style') // => falseIf you want to read the values out of a query parameter, you can use get. If
no query parameter exists, you'll get null back.
params.get('size') // => 'M'
params.get('button-style') // => nullI often find rather than use has to check, and then get to fetch the value,
I can just use get and check that the value is not null.
get vs getAll
There's one gotcha with get that you need to be aware of. One of the
behaviours of query parameters is that they can have multiple values:
// URL: buy-shirts-here.com/filter?size=M&size=LThis is a perfectly valid URL. When we pass that into URLSearchParams, it will
understand that size has multiple values. This is where the behaviour of get
is important: get will only return the first value for the query parameter.
If you want all of them, you need to use getAll which always returns an array:
// URL: buy-shirts-here.com/filter?size=M&size=L
const params = new URLSearchParams(location.search)
params.get('size') //=> 'M'
params.getAll('size') //=> ['M', 'L']Iterating on parameters
You can iterate through all the parameters in a few different ways. The first if
using for of. Once again, be wary of parameters will multiple values, they
will appear twice!
// URL: buy-shirts-here.com/filter?size=M&size=L&colour=red
const params = new URLSearchParams(location.search)
for (let p of params) {
console.log(p)
}
// => ['size', 'M']
// => ['size', 'L']
// => ['colour', 'red']You can also use .keys() to get an iterator of all the keys in the params, or
.values() to get all the values:
// URL: buy-shirts-here.com/filter?size=M&size=L&colour=red
const params = new URLSearchParams(location.search)
console.log([...params.keys()]) // => ['size', 'size', 'colour']
console.log([...params.values()]) // => ['M', 'L', 'red']
console.log([...params.entries()]) // => [['size', 'M'], ['size', 'L'], ['colour', 'red']]Modifying parameters
The first thing to note is that all these methods mutate the existing
URLSearchParams object, rather than return a new one.
You can use .delete() to delete a query parameter. Note that this deletes all
values of it, if it has multiple:
// URL: buy-shirts-here.com/filter?size=M&size=L&colour=red
const params = new URLSearchParams(location.search)
params.delete('size')
console.log([...params.keys()]) // => ['colour']We can use .append() to add a new key/value pair. If the value already exists,
append will append the new one on, as its name suggests:
// URL: buy-shirts-here.com/filter?size=M&colour=red
const params = new URLSearchParams(location.search)
params.append('size', 'L')
console.log([...params.keys()]) // => ['size', 'size', 'colour']
console.log([...params.values()]) // => ['M', 'L', 'red']
console.log([...params.entries()]) // => [['size', 'M'], ['size', 'L'], ['colour', 'red']]If you want to set a new value for the parameter and remove all other existing
values, you can use .set to do just that:
// URL: buy-shirts-here.com/filter?size=M&colour=red
const params = new URLSearchParams(location.search)
params.set('size', 'L')
console.log([...params.keys()]) // => ['size', 'colour']
console.log([...params.values()]) // => ['L', 'red']
console.log([...params.entries()]) // => [['size', 'L'], ['colour', 'red']]Getting the URL back out
After you've done all this reading and updating of query parameters, you'll
probably want to pull it back out as a URL so you can update the URL in the
browser. To do this, just call .toString():
// URL: buy-shirts-here.com/filter?size=M&colour=red
const params = new URLSearchParams(location.search)
params.set('size', 'L')
params.delete('colour')
console.log(params.toString()) // => 'size=L'Note that toString does not add the ? at the beginning, so make sure you
remember to add that if you need it.
Conclusion
URLSearchParams is a great API that you can use to clearly update your query
parameters without having to worry about any additional libraries to parse query
params, or to convert them back into a string at the end. I highly recommend
using it next time you need to do some query parameter parsing or updating, and
with it being very well supported in most browsers alongside many polyfills
being available, I don't see a good reason to not use it in your next project!
This content originally appeared on Jack Franklin and was authored by Jack Franklin
Jack Franklin | Sciencx (2018-07-23T00:00:00+00:00) Reading and updating query params with URLSearchParams. Retrieved from https://www.scien.cx/2018/07/23/reading-and-updating-query-params-with-urlsearchparams/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.