DEV Community

nerdyman ~ Ricky
nerdyman ~ Ricky

Posted on • Updated on

Replacing query-string with Native URLSearchParams

query-string is an awesome package which allows you to parse URL parameters, however, you may not need it anymore.

URLSearchParams is a native interface to easily parse and construct URL parameters in both Node and the browser!


The syntax is slightly more verbose than query-string in places, however, the benefit of a native solution to that of an external dependency outweighs the verbosity.

Setting Parameters

Parameters can be set both at and after instantiation.

const params = new URLSearchParams({ foo: "" });
// { foo: "" }
params.set('hello', 'world');
// { foo: "", hello: "world" }
params.set('foo', 'bar');
// { foo: "bar", hello: "world" }
Enter fullscreen mode Exit fullscreen mode

Getting Parameters

URLSearchParams returns an iterator to get values.

The simplest way to get the parameters as an Object is to use Object.FromEntries on the interface instance:

const params = new URLSearchParams('?one&foo=bar');

// Get all values.
const parsedParams = Object.fromEntries(params);
// { one: "", foo: "bar" }

// Get a specific value.
// "bar"
Enter fullscreen mode Exit fullscreen mode

Differences in Implementation


query-string removes leading # symbols - URLSearchParams does not.

const query = querystring('#foo=bar');
// { foo: "bar" } 

const params = new URLSearchParams('#foo=bar');
// { #foo: "bar" } 
Enter fullscreen mode Exit fullscreen mode

Implicit Parameter Values

Implicit parameters (parameters without =) will evaluate to null with query-string and an empty string with URLSearchParams.

const queryString = querystring.parse('?implicit&explicit=');
// { implicit: null, explicit: "" }

const params = new URLSearchParam('?implicit&explicit=');
// { implicit: "", explicit: "" }
Enter fullscreen mode Exit fullscreen mode

Array Values

query-string has advanced utilities to parse array values, for example:

queryString.parse('?foo[]=bar&foo[]=baz', { arrayFormat: 'bracket' });
//=> {foo: ['1', '2', '3']}
Enter fullscreen mode Exit fullscreen mode

URLSearchParams doesn't ship with array utilities so you need to roll your own function to get the full values back from arrays.

 * Convert `URLSearchParams` `[]` properties to array objects.
const arrayParams = (props) => {
  const params {};

  for (const key of props.keys()) {
    if (key.endsWith('[]')) {
      params[key.replace('[]', '')] = props.getAll(key);
    } else {
      params[key] = props.get(key);

  return params;

const params = arrayParams(new URLSearchParams('?foo[]=bar&foo[]=baz'));
// { foo: ["bar", "baz"] } 
Enter fullscreen mode Exit fullscreen mode

Otherwise, you'll end up with a single [] property with the first value supplied.

const params = new URLSearchParams('?foo[]=bar&foo[]=baz');
const entries Object.fromEntries(params);
// { foo[]: "bar" }
Enter fullscreen mode Exit fullscreen mode

If you only need to get a specific value you can use the .getAll method directly.

const params = new URLSearchParams('?foo=bar&foo=baz');

// ["bar", "baz"]
Enter fullscreen mode Exit fullscreen mode

Node and Browser Support

URLSearchParams is supported by Node 10+ and browser support is prettay prettay prettay pretty good - It works with Edge 17+ and all evergreen browsers have supported it since 2016~2017.

A polyfill is also available for the unfortunate souls who need to support legacy browsers.


Live Demo


The native URLSearchParams interface removes the need for query-string. One fewer dependency 🥳


Top comments (3)

amiralikulov profile image
Amir Alikulov

Thanks. Found this article in query-string issues section :)

char0n profile image
VladimĂ­r Gorej • Edited

Yeah great migration guide, thanks!

I've written similar guide for migrating Node.js internal querystring API to URLSearchParams. Node.js marked the querystring as legacy API in version 14.x, and recommends using URLSearchParams. But doesn’t give us any clue how to actually migrate.

And just for a reader clarification, the difference between query-string and querystring is that query-string is an independent npm package, while querystring is internal Node.js API.

lukewalker96 profile image
Luke Walker