query-string vs url vs url-parse vs url-search-params vs whatwg-url
URL and Query String Manipulation
Search packages..
query-stringurlurl-parseurl-search-paramswhatwg-urlSimilar Packages:

URL and Query String Manipulation

URL and Query String Manipulation libraries in JavaScript provide tools for parsing, constructing, and manipulating URLs and their components, such as query strings, paths, and fragments. These libraries help developers handle URL-related tasks more efficiently, whether for client-side applications, server-side code, or APIs. They offer features like encoding/decoding query parameters, handling nested or array-like parameters, and ensuring proper URL formatting, which is essential for web development, routing, and data transmission. query-string is a lightweight library focused on parsing and stringifying query strings, while url is a built-in Node.js module that provides comprehensive URL handling. url-parse is a small, fast library for parsing URLs, and url-search-params is a polyfill for the URLSearchParams API, which provides a simple interface for working with query parameters. whatwg-url is a reference implementation of the URL Standard, offering a robust and compliant way to work with URLs in JavaScript.

Npm Package Weekly Downloads Trend

3 Years

Github Stars Ranking

Stat Detail

Package
Downloads
Stars
Size
Issues
Publish
License
query-string06,90357.7 kB28 months agoMIT
url037678.3 kB182 years agoMIT
url-parse01,03763 kB16-MIT
url-search-params0761-08 years agoMIT
whatwg-url0413101 kB83 months agoMIT

Feature Comparison: query-string vs url vs url-parse vs url-search-params vs whatwg-url

Size and Performance

  • query-string:

    query-string is a small library (about 1KB minified) that offers efficient parsing and stringifying of query strings with minimal impact on performance. Its lightweight nature makes it ideal for client-side applications where load time and bandwidth are concerns.

  • url:

    The url module is built into Node.js, so it has no additional size overhead for server-side applications. It provides comprehensive URL handling, but its performance is optimized for server environments rather than client-side use.

  • url-parse:

    url-parse is a lightweight library (around 1KB minified) designed for fast URL parsing. Its small size and quick parsing capabilities make it suitable for both browser and Node.js applications, especially when performance is a priority.

  • url-search-params:

    url-search-params is a polyfill for the URLSearchParams API, which is lightweight and does not significantly impact performance. It is useful for adding standardized query parameter handling to environments that lack native support.

  • whatwg-url:

    whatwg-url is a reference implementation of the URL Standard, which is more comprehensive than other libraries. While it may be larger than some lightweight alternatives, it provides a thorough and compliant solution for handling URLs, making it suitable for applications that require strict adherence to web standards.

API Design

  • query-string:

    query-string provides a simple and intuitive API for parsing and stringifying query strings. It supports nested objects and arrays, making it easy to work with complex query parameters. The API is well-documented and easy to use, even for developers who are not familiar with query string manipulation.

  • url:

    The url module in Node.js offers a robust API for URL manipulation, including parsing, formatting, and resolving URLs. It provides detailed access to all URL components, but its API can be complex for beginners due to its comprehensive nature.

  • url-parse:

    url-parse offers a straightforward API for parsing URLs. It breaks down the URL into its components (protocol, host, pathname, etc.) and allows easy access and manipulation of these parts. The API is simple and well-suited for quick URL parsing tasks.

  • url-search-params:

    url-search-params provides a clean and simple API for working with query parameters. It allows easy retrieval, modification, and deletion of parameters, and supports iteration over them. The API is designed to be intuitive and aligns with the standard URLSearchParams interface.

  • whatwg-url:

    whatwg-url provides a detailed and standards-compliant API for URL manipulation. It follows the URL Standard closely, offering methods and properties that align with modern web specifications. This makes it a reliable choice for developers who need a compliant and comprehensive URL handling solution.

Query Parameter Handling

  • query-string:

    query-string excels at handling complex query parameters, including nested objects and arrays. It provides options for customizing the parsing and stringifying processes, such as specifying delimiters and encoding. This makes it highly flexible for working with a wide variety of query string formats.

  • url:

    The url module provides basic query parameter handling through its URL and URLSearchParams classes. While it supports standard query parameter manipulation, it is not as specialized or flexible as dedicated query string libraries.

  • url-parse:

    url-parse handles query parameters as part of its URL parsing functionality. It provides access to the query string and allows for basic manipulation, but it does not offer advanced features for handling complex or nested query parameters.

  • url-search-params:

    url-search-params focuses on query parameter manipulation, providing a standard interface for adding, removing, and modifying parameters. It supports iteration and works well with both simple and complex query strings, making it a reliable choice for most use cases.

  • whatwg-url:

    whatwg-url provides comprehensive support for query parameters as part of its URL implementation. It adheres to the URL Standard, offering robust methods for manipulating query parameters, including support for nested and complex structures.

Ease of Use: Code Examples

  • query-string:

    query-string makes it easy to work with query strings in a way that is both efficient and intuitive. Here’s a simple example of how to use it:

    import { parse, stringify } from 'query-string';

// Parsing a query string
const parsed = parse('?foo=bar&baz=qux&nested%5Bkey%5D=value');
console.log(parsed);
// Output: { foo: 'bar', baz: 'qux', nested: { key: 'value' } }

// Stringifying an object into a query string
const queryString = stringify({ foo: 'bar', baz: 'qux', nested: { key: 'value' } });
console.log(queryString);
// Output: 'foo=bar&baz=qux&nested%5Bkey%5D=value'
  • url:

    The url module in Node.js provides powerful tools for URL manipulation, but it can be more complex to use due to its comprehensive nature. Here’s a basic example:

    const { URL } = require('url');

// Creating a new URL
const myUrl = new URL('https://example.com/path?name=John&age=30');

// Accessing URL components
console.log(myUrl.hostname); // Output: 'example.com'
console.log(myUrl.pathname); // Output: '/path'
console.log(myUrl.searchParams.get('name')); // Output: 'John'

// Modifying URL components
myUrl.pathname = '/new-path';
myUrl.searchParams.append('city', 'New York');

console.log(myUrl.toString()); // Output: 'https://example.com/new-path?name=John&age=30&city=New+York'
  • url-parse:

    url-parse provides a simple way to parse URLs and access their components. Here’s an example:

    import urlParse from 'url-parse';

const parsedUrl = urlParse('https://example.com/path?name=John&age=30');

console.log(parsedUrl.protocol); // Output: 'https:'
console.log(parsedUrl.hostname); // Output: 'example.com'
console.log(parsedUrl.query.name); // Output: 'John'

// Modifying the URL
parsedUrl.set('query', { name: 'Jane', city: 'New York' });
console.log(parsedUrl.toString()); // Output: 'https://example.com/path?name=Jane&city=New+York'
  • url-search-params:

    url-search-params provides a simple interface for working with query parameters. Here’s an example:

    const params = new URLSearchParams('?name=John&age=30&city=New+York');

// Accessing parameters
console.log(params.get('name')); // Output: 'John'
console.log(params.get('age')); // Output: '30'

// Modifying parameters
params.set('age', '31');
params.append('country', 'USA');
params.delete('city');

console.log(params.toString()); // Output: 'name=John&age=31&country=USA'
  • whatwg-url:

    whatwg-url provides a compliant way to work with URLs according to the URL Standard. Here’s a simple example:

    import { URL } from 'whatwg-url';

const myUrl = new URL('https://example.com/path?name=John&age=30');

// Accessing URL components
console.log(myUrl.hostname); // Output: 'example.com'
console.log(myUrl.pathname); // Output: '/path'
console.log(myUrl.searchParams.get('name')); // Output: 'John'

// Modifying URL components
myUrl.pathname = '/new-path';
myUrl.searchParams.append('city', 'New York');

console.log(myUrl.toString()); // Output: 'https://example.com/new-path?name=John&age=30&city=New+York'

How to Choose: query-string vs url vs url-parse vs url-search-params vs whatwg-url

  • query-string:

    Choose query-string if you need a lightweight, easy-to-use library specifically for parsing and stringifying query strings, especially if you work with complex or nested query parameters.

  • url:

    Choose url if you need a comprehensive solution for URL manipulation in Node.js, including support for all URL components, parsing, and serialization.

  • url-parse:

    Choose url-parse if you want a small, fast library for parsing URLs that provides a simple API and supports both browser and Node.js environments.

  • url-search-params:

    Choose url-search-params if you need a polyfill for the URLSearchParams API, which provides a standard way to work with query parameters in a more structured manner.

  • whatwg-url:

    Choose whatwg-url if you require a compliant implementation of the URL Standard for handling URLs in a way that adheres to modern web specifications.

Similar Npm Packages to query-string

query-string is a popular JavaScript library that provides utilities for parsing and stringifying URL query strings. It simplifies the process of working with query parameters in URLs, making it easier to extract and manipulate data from them. With query-string, developers can easily convert query strings into JavaScript objects and vice versa, which is particularly useful for handling URL parameters in web applications.

One notable alternative to query-string is qs. The qs library is also designed for parsing and stringifying query strings, but it offers additional features and capabilities. For instance, qs supports nested objects and arrays in query strings, allowing for more complex data structures to be represented. This makes it a great choice for applications that require more advanced query string handling.

While both libraries serve similar purposes, the choice between query-string and qs often depends on the specific needs of the application. If you need a straightforward solution for basic query string manipulation, query-string is a solid option. However, if your application requires handling more complex data structures within query strings, qs may be the better choice.

To see how query-string compares with qs, check out the comparison: Comparing query-string vs qs.

Similar Npm Packages to url

url is a Node.js module that provides utilities for URL resolution and parsing. It simplifies the process of working with URLs, allowing developers to easily manipulate and extract information from them. While the url module is widely used, there are several alternatives that offer similar functionalities. Here are a few notable ones:

  • qs is a query string parsing and stringifying library that is known for its ability to handle complex query strings. Unlike the built-in querystring module in Node.js, qs supports nested objects and arrays, making it a more powerful option for parsing and constructing query strings. If your application requires handling complex query parameters, qs is an excellent choice due to its flexibility and ease of use.

  • query-string is another library for parsing and stringifying query strings. It is lightweight and provides a simple API for working with query parameters. query-string supports parsing query strings into objects and converting objects back into query strings. If you are looking for a straightforward solution for handling query strings without the overhead of more complex libraries, query-string is a great option.

  • url-parse is a library that provides a simple way to parse URLs into their components, such as protocol, host, pathname, and query string. It is designed to be easy to use and works in both Node.js and browser environments. If you need a lightweight solution for breaking down URLs into their constituent parts, url-parse is a solid choice.

To see how these packages compare, check out the comparison: Comparing qs vs query-string vs url vs url-parse.

Similar Npm Packages to url-parse

url-parse is a popular JavaScript library for parsing and manipulating URLs. It provides a simple and efficient way to break down URLs into their components, such as protocol, host, pathname, query string, and hash. This makes it easier for developers to work with URLs in their applications, whether they need to extract specific parts of a URL or construct new URLs from existing components. While url-parse is a robust solution for URL handling, there are several alternatives worth considering:

  • url-join is a lightweight library that focuses specifically on joining URL segments together. It ensures that the resulting URL is properly formatted, handling slashes and other characters gracefully. If your primary need is to concatenate URL parts without worrying about the intricacies of parsing, url-join is an excellent choice. Its simplicity and focused functionality make it ideal for scenarios where you need to build URLs dynamically from various segments.

  • url-parse-lax is a variant of the url-parse library that offers a more lenient approach to parsing URLs. It allows for more flexibility in handling malformed URLs and provides a simpler API for common use cases. If you find that you often deal with URLs that may not conform to strict standards, url-parse-lax can be a great alternative. It retains many of the features of url-parse while providing a more forgiving parsing experience.

To see how these libraries compare, check out the comparison: Comparing url-join vs url-parse vs url-parse-lax.

Similar Npm Packages to url-search-params

url-search-params is a JavaScript library that provides a simple and convenient way to work with URL query parameters. It allows developers to easily parse, manipulate, and serialize query strings in a user-friendly manner. While url-search-params is a great tool for handling URL parameters, there are several alternatives available that offer similar functionalities. Here are a few notable ones:

  • qs is a powerful query string parsing and stringifying library that supports nested objects and arrays. It provides a rich set of features for handling complex query strings, making it a popular choice for developers who need to work with more intricate data structures. If your application requires advanced parsing capabilities beyond simple key-value pairs, qs is an excellent option.
  • query-string is a lightweight library for parsing and stringifying URL query strings. It offers a straightforward API and supports features like array and object serialization. query-string is ideal for developers looking for a simple solution to handle query parameters without the overhead of more complex libraries. Its ease of use makes it a popular choice for many projects.
  • querystring is a built-in Node.js module that provides utilities for parsing and formatting query strings. While it is primarily used in server-side applications, it can also be utilized in client-side code. If you are working in a Node.js environment and need basic query string manipulation, querystring is a reliable option.
  • url-parse is a comprehensive library for parsing and manipulating URLs. It provides a wide range of features, including the ability to easily access various components of a URL, such as the protocol, hostname, and query parameters. If your project requires extensive URL manipulation beyond just query strings, url-parse is a robust choice.
  • url-search-params-polyfill is a polyfill for the URLSearchParams interface, which allows developers to work with query strings in environments that do not support this feature natively. If you need to ensure compatibility with older browsers or environments, this polyfill can be a valuable addition to your project.

To see how these packages compare, check out the comparison: Comparing qs vs query-string vs querystring vs url-parse vs url-search-params vs url-search-params-polyfill.

Similar Npm Packages to whatwg-url

whatwg-url is a JavaScript library that provides a comprehensive implementation of the WHATWG URL Standard. It allows developers to parse, construct, and manipulate URLs in a consistent and reliable manner. This library is particularly useful for applications that require robust URL handling, ensuring that URLs are processed according to the latest web standards. While whatwg-url is a powerful tool for URL manipulation, there are several alternatives available in the ecosystem. Here are a few notable ones:

  • query-string is a lightweight library for parsing and stringifying URL query strings. It provides a simple API to convert query strings into JavaScript objects and vice versa. If your primary focus is on handling query parameters rather than full URL manipulation, query-string is an excellent choice. Its simplicity and ease of use make it a popular option for developers who need to work with query strings in their applications.

  • url is a built-in Node.js module that provides utilities for URL resolution and parsing. It allows developers to work with URLs in a straightforward manner, offering methods to parse and format URLs. While it is a solid choice for server-side applications, it may not cover all the features provided by whatwg-url, especially when it comes to adhering to the latest web standards. If you're working in a Node.js environment and need basic URL handling, the url module can be sufficient.

  • url-parse is a lightweight library that provides a simple way to parse URLs into their components. It supports both browser and Node.js environments and allows for easy manipulation of URL parts. While url-parse is straightforward and effective for basic URL parsing, it may lack some of the advanced features and compliance with the WHATWG URL Standard that whatwg-url offers. If you need a quick and easy solution for parsing URLs without the need for extensive features, url-parse is a good option.

  • url-search-params is a polyfill for the URLSearchParams interface, which provides methods to work with the query string of a URL. It allows developers to easily manipulate query parameters, making it a useful tool for applications that need to handle URL query strings. If your focus is primarily on managing query parameters and you want a simple API, url-search-params can be a suitable alternative.

For a comprehensive comparison of these packages, check out the following link: Comparing query-string vs url vs url-parse vs url-search-params vs whatwg-url.

README for query-string

query-string

Parse and stringify URL query strings

Install

npm install query-string

[!WARNING] Remember the hyphen! Do not install the deprecated querystring package!

For browser usage, this package targets the latest version of Chrome, Firefox, and Safari.

Usage

import queryString from 'query-string';

console.log(location.search);
//=> '?foo=bar'

const parsed = queryString.parse(location.search);
console.log(parsed);
//=> {foo: 'bar'}

console.log(location.hash);
//=> '#token=bada55cafe'

const parsedHash = queryString.parse(location.hash);
console.log(parsedHash);
//=> {token: 'bada55cafe'}

parsed.foo = 'unicorn';
parsed.ilike = 'pizza';

const stringified = queryString.stringify(parsed);
//=> 'foo=unicorn&ilike=pizza'

location.search = stringified;
// note that `location.search` automatically prepends a question mark
console.log(location.search);
//=> '?foo=unicorn&ilike=pizza'

API

.parse(string, options?)

Parse a query string into an object. Leading ? or # are ignored, so you can pass location.search or location.hash directly.

The returned object is created with Object.create(null) and thus does not have a prototype.

queryString.parse('?foo=bar');
//=> {foo: 'bar'}

queryString.parse('#token=secret&name=jhon');
//=> {token: 'secret', name: 'jhon'}

options

Type: object

decode

Type: boolean
Default: true

Decode the keys and values. URL components are decoded with decode-uri-component.

arrayFormat

Type: string
Default: 'none'

  • 'bracket': Parse arrays with bracket representation:
import queryString from 'query-string';

queryString.parse('foo[]=1&foo[]=2&foo[]=3', {arrayFormat: 'bracket'});
//=> {foo: ['1', '2', '3']}
  • 'index': Parse arrays with index representation:
import queryString from 'query-string';

queryString.parse('foo[0]=1&foo[1]=2&foo[3]=3', {arrayFormat: 'index'});
//=> {foo: ['1', '2', '3']}
  • 'comma': Parse arrays with elements separated by comma:
import queryString from 'query-string';

queryString.parse('foo=1,2,3', {arrayFormat: 'comma'});
//=> {foo: ['1', '2', '3']}
  • 'separator': Parse arrays with elements separated by a custom character:
import queryString from 'query-string';

queryString.parse('foo=1|2|3', {arrayFormat: 'separator', arrayFormatSeparator: '|'});
//=> {foo: ['1', '2', '3']}
  • 'bracket-separator': Parse arrays (that are explicitly marked with brackets) with elements separated by a custom character:
import queryString from 'query-string';

queryString.parse('foo[]', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
//=> {foo: []}

queryString.parse('foo[]=', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
//=> {foo: ['']}

queryString.parse('foo[]=1', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
//=> {foo: ['1']}

queryString.parse('foo[]=1|2|3', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
//=> {foo: ['1', '2', '3']}

queryString.parse('foo[]=1||3|||6', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
//=> {foo: ['1', '', 3, '', '', '6']}

queryString.parse('foo[]=1|2|3&bar=fluffy&baz[]=4', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
//=> {foo: ['1', '2', '3'], bar: 'fluffy', baz:['4']}
  • 'colon-list-separator': Parse arrays with parameter names that are explicitly marked with :list:
import queryString from 'query-string';

queryString.parse('foo:list=one&foo:list=two', {arrayFormat: 'colon-list-separator'});
//=> {foo: ['one', 'two']}
  • 'none': Parse arrays with elements using duplicate keys:
import queryString from 'query-string';

queryString.parse('foo=1&foo=2&foo=3');
//=> {foo: ['1', '2', '3']}
arrayFormatSeparator

Type: string
Default: ','

The character used to separate array elements when using {arrayFormat: 'separator'}.

sort

Type: Function | boolean
Default: true

Supports both Function as a custom sorting function or false to disable sorting.

parseNumbers

Type: boolean
Default: false

import queryString from 'query-string';

queryString.parse('foo=1', {parseNumbers: true});
//=> {foo: 1}

Parse the value as a number type instead of string type if it's a number.

parseBooleans

Type: boolean
Default: false

import queryString from 'query-string';

queryString.parse('foo=true', {parseBooleans: true});
//=> {foo: true}

Parse the value as a boolean type instead of string type if it's a boolean.

types

Type: object
Default: {}

Specifies a schema for parsing query values with explicit type declarations. When defined, the types provided here take precedence over general parsing options such as parseNumbers, parseBooleans, and arrayFormat.

Use this option to explicitly define the type of a specific parameter—particularly useful in cases where the type might otherwise be ambiguous (e.g., phone numbers or IDs).

You can also provide a custom function to transform the value. The function will receive the raw string and should return the desired parsed result. When used with array formats (like comma, separator, bracket, etc.), the function is applied to each array element individually.

Supported Types:

  • 'boolean': Parse flagged as a boolean (overriding the parseBooleans option):
queryString.parse('?isAdmin=true&flagged=true&isOkay=0', {
		parseBooleans: false,
		types: {
				flagged: 'boolean',
				isOkay: 'boolean',
		},
});
//=> {isAdmin: 'true', flagged: true, isOkay: false}

Note: The 'boolean' type also converts '0' and '1' to booleans, and treats valueless keys (e.g. ?flag) as true.

  • 'string': Parse phoneNumber as a string (overriding the parseNumbers option):
import queryString from 'query-string';

queryString.parse('?phoneNumber=%2B380951234567&id=1', {
	parseNumbers: true,
	types: {
		phoneNumber: 'string',
	}
});
//=> {phoneNumber: '+380951234567', id: 1}
  • 'number': Parse age as a number (even when parseNumbers is false):
import queryString from 'query-string';

queryString.parse('?age=20&id=01234&zipcode=90210', {
	types: {
		age: 'number',
	}
});
//=> {age: 20, id: '01234', zipcode: '90210'}
  • 'string[]': Parse items as an array of strings (overriding the parseNumbers option):
import queryString from 'query-string';

queryString.parse('?age=20&items=1%2C2%2C3', {
	parseNumbers: true,
	types: {
		items: 'string[]',
	}
});
//=> {age: 20, items: ['1', '2', '3']}
  • 'number[]': Parse items as an array of numbers (even when parseNumbers is false):
import queryString from 'query-string';

queryString.parse('?age=20&items=1%2C2%2C3', {
	types: {
		items: 'number[]',
	}
});
//=> {age: '20', items: [1, 2, 3]}
  • 'Function': Provide a custom function as the parameter type. The parameter's value will equal the function's return value. When used with array formats (like comma, separator, bracket, etc.), the function is applied to each array element individually.
import queryString from 'query-string';

queryString.parse('?age=20&id=01234&zipcode=90210', {
	types: {
		age: value => value * 2,
	}
});
//=> {age: 40, id: '01234', zipcode: '90210'}

// With arrays, the function is applied to each element
queryString.parse('?scores=10,20,30', {
	arrayFormat: 'comma',
	types: {
		scores: value => Number(value) * 2,
	}
});
//=> {scores: [20, 40, 60]}

NOTE: Array types (string[], number[]) are ignored if arrayFormat is set to 'none'.

queryString.parse('ids=001%2C002%2C003&foods=apple%2Corange%2Cmango', {
	arrayFormat: 'none',
	types: {
		ids: 'number[]',
		foods: 'string[]',
	},
}
//=> {ids:'001,002,003', foods:'apple,orange,mango'}
Function
import queryString from 'query-string';

queryString.parse('?age=20&id=01234&zipcode=90210', {
	types: {
		age: value => value * 2,
	}
});
//=> {age: 40, id: '01234', zipcode: '90210'}

Parse the value as a boolean type instead of string type if it's a boolean.

.stringify(object, options?)

Stringify an object into a query string and sorting the keys.

Supported value types: string, number, bigint, boolean, null, undefined, and arrays of these types. Other types like Symbol, functions, or objects (except arrays) will throw an error.

options

Type: object

strict

Type: boolean
Default: true

Strictly encode URI components. It uses encodeURIComponent if set to false. You probably don't care about this option.

encode

Type: boolean
Default: true

URL encode the keys and values.

arrayFormat

Type: string
Default: 'none'

  • 'bracket': Serialize arrays using bracket representation:
import queryString from 'query-string';

queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket'});
//=> 'foo[]=1&foo[]=2&foo[]=3'
  • 'index': Serialize arrays using index representation:
import queryString from 'query-string';

queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'index'});
//=> 'foo[0]=1&foo[1]=2&foo[2]=3'
  • 'comma': Serialize arrays by separating elements with comma:
import queryString from 'query-string';

queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'comma'});
//=> 'foo=1,2,3'

queryString.stringify({foo: [1, null, '']}, {arrayFormat: 'comma'});
//=> 'foo=1,,'
// Note that typing information for null values is lost
// and `.parse('foo=1,,')` would return `{foo: [1, '', '']}`.
  • 'separator': Serialize arrays by separating elements with a custom character:
import queryString from 'query-string';

queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'separator', arrayFormatSeparator: '|'});
//=> 'foo=1|2|3'
  • 'bracket-separator': Serialize arrays by explicitly post-fixing array names with brackets and separating elements with a custom character:
import queryString from 'query-string';

queryString.stringify({foo: []}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
//=> 'foo[]'

queryString.stringify({foo: ['']}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
//=> 'foo[]='

queryString.stringify({foo: [1]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
//=> 'foo[]=1'

queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
//=> 'foo[]=1|2|3'

queryString.stringify({foo: [1, '', 3, null, null, 6]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
//=> 'foo[]=1||3|||6'

queryString.stringify({foo: [1, '', 3, null, null, 6]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|', skipNull: true});
//=> 'foo[]=1||3|6'

queryString.stringify({foo: [1, 2, 3], bar: 'fluffy', baz: [4]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
//=> 'foo[]=1|2|3&bar=fluffy&baz[]=4'
  • 'colon-list-separator': Serialize arrays with parameter names that are explicitly marked with :list:
import queryString from 'query-string';

queryString.stringify({foo: ['one', 'two']}, {arrayFormat: 'colon-list-separator'});
//=> 'foo:list=one&foo:list=two'
  • 'none': Serialize arrays by using duplicate keys:
import queryString from 'query-string';

queryString.stringify({foo: [1, 2, 3]});
//=> 'foo=1&foo=2&foo=3'
arrayFormatSeparator

Type: string
Default: ','

The character used to separate array elements when using {arrayFormat: 'separator'}.

sort

Type: Function | boolean

Supports both Function as a custom sorting function or false to disable sorting.

import queryString from 'query-string';

const order = ['c', 'a', 'b'];

queryString.stringify({a: 1, b: 2, c: 3}, {
	sort: (a, b) => order.indexOf(a) - order.indexOf(b)
});
//=> 'c=3&a=1&b=2'

import queryString from 'query-string';

queryString.stringify({b: 1, c: 2, a: 3}, {sort: false});
//=> 'b=1&c=2&a=3'

If omitted, keys are sorted using Array#sort(), which means, converting them to strings and comparing strings in Unicode code point order.

skipNull

Skip keys with null as the value.

Note that keys with undefined as the value are always skipped.

Type: boolean
Default: false

import queryString from 'query-string';

queryString.stringify({a: 1, b: undefined, c: null, d: 4}, {
	skipNull: true
});
//=> 'a=1&d=4'

import queryString from 'query-string';

queryString.stringify({a: undefined, b: null}, {
	skipNull: true
});
//=> ''
skipEmptyString

Skip keys with an empty string as the value.

Type: boolean
Default: false

import queryString from 'query-string';

queryString.stringify({a: 1, b: '', c: '', d: 4}, {
	skipEmptyString: true
});
//=> 'a=1&d=4'

import queryString from 'query-string';

queryString.stringify({a: '', b: ''}, {
	skipEmptyString: true
});
//=> ''
replacer

A function that transforms key-value pairs before stringification.

Type: function
Default: undefined

Similar to the replacer parameter of JSON.stringify(), this function is called for each key-value pair and can be used to transform values before they are stringified. The function receives the key and value, and should return the transformed value. Returning undefined will omit the key-value pair from the resulting query string.

This is useful for custom serialization of non-primitive types like Date:

import queryString from 'query-string';

queryString.stringify({
	date: new Date('2024-01-15T10:30:00Z'),
	name: 'John'
}, {
	replacer: (key, value) => {
		if (value instanceof Date) {
			return value.toISOString();
		}

		return value;
	}
});
//=> 'date=2024-01-15T10%3A30%3A00.000Z&name=John'

You can also use it to filter out keys:

import queryString from 'query-string';

queryString.stringify({
	a: 1,
	b: null,
	c: 3
}, {
	replacer: (key, value) => value === null ? undefined : value
});
//=> 'a=1&c=3'

.extract(string)

Extract a query string from a URL that can be passed into .parse().

queryString.extract('https://foo.bar?foo=bar');
//=> 'foo=bar'

.parseUrl(string, options?)

Extract the URL and the query string as an object.

Returns an object with a url and query property.

If the parseFragmentIdentifier option is true, the object will also contain a fragmentIdentifier property.

import queryString from 'query-string';

queryString.parseUrl('https://foo.bar?foo=bar');
//=> {url: 'https://foo.bar', query: {foo: 'bar'}}

queryString.parseUrl('https://foo.bar?foo=bar#xyz', {parseFragmentIdentifier: true});
//=> {url: 'https://foo.bar', query: {foo: 'bar'}, fragmentIdentifier: 'xyz'}

options

Type: object

The options are the same as for .parse().

Extra options are as below.

parseFragmentIdentifier

Parse the fragment identifier from the URL.

Type: boolean
Default: false

import queryString from 'query-string';

queryString.parseUrl('https://foo.bar?foo=bar#xyz', {parseFragmentIdentifier: true});
//=> {url: 'https://foo.bar', query: {foo: 'bar'}, fragmentIdentifier: 'xyz'}

.stringifyUrl(object, options?)

Stringify an object into a URL with a query string and sorting the keys. The inverse of .parseUrl()

The options are the same as for .stringify().

Returns a string with the URL and a query string.

Query items in the query property overrides queries in the url property.

The fragmentIdentifier property overrides the fragment identifier in the url property.

queryString.stringifyUrl({url: 'https://foo.bar', query: {foo: 'bar'}});
//=> 'https://foo.bar?foo=bar'

queryString.stringifyUrl({url: 'https://foo.bar?foo=baz', query: {foo: 'bar'}});
//=> 'https://foo.bar?foo=bar'

queryString.stringifyUrl({
	url: 'https://foo.bar',
	query: {
		top: 'foo'
	},
	fragmentIdentifier: 'bar'
});
//=> 'https://foo.bar?top=foo#bar'

object

Type: object

url

Type: string

The URL to stringify.

query

Type: object

Query items to add to the URL.

.pick(url, keys, options?)

.pick(url, filter, options?)

Pick query parameters from a URL.

Returns a string with the new URL.

import queryString from 'query-string';

queryString.pick('https://foo.bar?foo=1&bar=2#hello', ['foo']);
//=> 'https://foo.bar?foo=1#hello'

queryString.pick('https://foo.bar?foo=1&bar=2#hello', (name, value) => value === 2, {parseNumbers: true});
//=> 'https://foo.bar?bar=2#hello'

.exclude(url, keys, options?)

.exclude(url, filter, options?)

Exclude query parameters from a URL.

Returns a string with the new URL.

import queryString from 'query-string';

queryString.exclude('https://foo.bar?foo=1&bar=2#hello', ['foo']);
//=> 'https://foo.bar?bar=2#hello'

queryString.exclude('https://foo.bar?foo=1&bar=2#hello', (name, value) => value === 2, {parseNumbers: true});
//=> 'https://foo.bar?foo=1#hello'

url

Type: string

The URL containing the query parameters to filter.

keys

Type: string[]

The names of the query parameters to filter based on the function used.

filter

Type: (key, value) => boolean

A filter predicate that will be provided the name of each query parameter and its value. The parseNumbers and parseBooleans options also affect value.

options

Type: object

Parse options and stringify options.

Nesting

This module intentionally doesn't support nesting as it's not spec'd and varies between implementations, which causes a lot of edge cases.

You're much better off just converting the object to a JSON string:

import queryString from 'query-string';

queryString.stringify({
	foo: 'bar',
	nested: JSON.stringify({
		unicorn: 'cake'
	})
});
//=> 'foo=bar&nested=%7B%22unicorn%22%3A%22cake%22%7D'

However, there is support for multiple instances of the same key:

import queryString from 'query-string';

queryString.parse('likes=cake&name=bob&likes=icecream');
//=> {likes: ['cake', 'icecream'], name: 'bob'}

queryString.stringify({color: ['taupe', 'chartreuse'], id: '515'});
//=> 'color=taupe&color=chartreuse&id=515'

Falsy values

Sometimes you want to unset a key, or maybe just make it present without assigning a value to it. Here is how falsy values are stringified:

import queryString from 'query-string';

queryString.stringify({foo: false});
//=> 'foo=false'

queryString.stringify({foo: null});
//=> 'foo'

queryString.stringify({foo: undefined});
//=> ''

FAQ

Why is it parsing + as a space?

See this answer.

npm-compare.com is an independent website designed to help developers choose the most suitable npm packages. We are not affiliated with npm, Inc, the official website for the npm registry. Note that npm is a registered trademark of npm, Inc. Please share your feedback via our GitHub repository. For more details, please refer to our Terms & Privacy.