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!

Usage

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" }

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.
params.get('foo');
// "bar"

Differences in Implementation

Symbols

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

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

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

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: "" }

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']}

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"] } 

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" }

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

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

params.getAll('foo');

// ["bar", "baz"]

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

Summary

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

Links

• URLSearchParams on MDN
• URLSearchParams on Can I Use

Comments

[Amir Alikulov]

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

[Vladimír Gorej]

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.

[Luke Walker]

🔥🔥🔥