These libraries solve the problem of converting URL query strings (the part after ?) into JavaScript objects and vice versa. While modern browsers provide the native URLSearchParams API, it has limitations regarding nested data structures, array formatting, and legacy browser support.
qs and query-string are feature-rich utilities designed to handle complex serialization needs like nested objects and custom array formats. url-parse is a broader tool that parses the entire URL structure, including query strings. url-search-params and url-search-params-polyfill are legacy shims intended to bring the native URLSearchParams API to older environments like Internet Explorer, though they are largely obsolete in modern development.
Handling URL query parameters is a daily task for frontend developers, whether you are reading filters from a search bar or syncing state with the browser history. While modern browsers offer the native URLSearchParams API, it often falls short when dealing with nested objects or specific array formats. This comparison breaks down the leading toolsβqs, query-string, and url-parseβalong with legacy polyfills, to help you pick the right tool for your architecture.
The most significant difference between these libraries is how they handle nested data structures. URLs naturally flatten data, but JavaScript objects often nest.
qs excels at deep nesting. It can parse strings like user[address][city]=NY into a structured object automatically. It is the most robust choice for complex forms.
import qs from 'qs';
const str = 'user[name]=John&user[skills][]=JS&user[skills][]=React';
const obj = qs.parse(str);
// Result: { user: { name: 'John', skills: ['JS', 'React'] } }
query-string supports nested objects but requires you to explicitly enable the feature. By default, it treats everything as flat strings, which can be safer if you don't expect nested data.
import queryString from 'query-string';
const str = 'user[name]=John&user[skills][]=JS';
const obj = queryString.parse(str, { parseNumbers: false, parseBooleans: false });
// Note: Deep nesting support varies by version; often returns flat keys like 'user[name]'
// unless specific options or newer versions handling bracket notation are used.
// In recent versions, it handles simple brackets but `qs` is generally preferred for deep recursion.
url-parse focuses on splitting the URL parts. It extracts the query string but relies on the native querystring module (in Node) or simple splitting for the content. It does not natively resolve deep nested objects into structured JS objects without extra steps.
import UrlParse from 'url-parse';
const url = new UrlParse('http://example.com/?user[name]=John');
const query = url.query;
// Result: '?user[name]=John' (String)
// You must pass this string to another parser (like qs) to get the object.
url-search-params and url-search-params-polyfill mimic the native API. The native specification does not support nested objects. You get flat key-value pairs only.
// Native or Polyfill behavior
const params = new URLSearchParams('user[name]=John&user[city]=NY');
const obj = Object.fromEntries(params.entries());
// Result: { 'user[name]': 'John', 'user[city]': 'NY' }
// The keys remain strings; no automatic object structure is created.
Different backend frameworks expect arrays in different formats. Some want ?id=1&id=2, others ?id[]=1&id[]=2, and some ?id[0]=1&id[0]=2.
qs offers the most granular control. You can dictate exactly how arrays are serialized using the arrayFormat option.
import qs from 'qs';
const obj = { ids: [1, 2, 3] };
// Bracket format: ?ids[]=1&ids[]=2&ids[]=3
qs.stringify(obj, { arrayFormat: 'brackets' });
// Index format: ?ids[0]=1&ids[1]=2&ids[2]=3
qs.stringify(obj, { arrayFormat: 'indices' });
// Repeat format: ?ids=1&ids=2&ids=3
qs.stringify(obj, { arrayFormat: 'repeat' });
query-string also supports multiple array formats, making it a strong contender for frontend routing where URL readability matters.
import queryString from 'query-string';
const obj = { ids: [1, 2, 3] };
// Bracket format
queryString.stringify(obj, { arrayFormat: 'bracket' }); // ?ids[]=1&ids[]=2&ids[]=3
// Separator format (custom delimiter)
queryString.stringify(obj, { arrayFormat: 'separator' }); // ?ids=1,2,3
url-parse does not handle array serialization logic itself. It simply constructs the query string from the object you pass or returns the raw string. You would need to pre-process your arrays before passing them to this library.
import UrlParse from 'url-parse';
// You must manually format the array before creating the URL
const query = '?ids=1&ids=2&ids=3';
const url = new UrlParse(`http://example.com/${query}`);
url-search-params and url-search-params-polyfill strictly follow the HTML standard. They only support the "repeat" format (?key=val&key=val). They cannot generate bracket or index notation natively.
const params = new URLSearchParams();
params.append('ids', 1);
params.append('ids', 2);
// Result: ?ids=1&ids=2
// Impossible to generate ?ids[]=1 with native API alone.
Sometimes you need more than just the query parameters; you need the host, protocol, or port.
url-parse is the only tool in this list designed for full URL decomposition. It works consistently even in older environments where the global URL constructor is missing.
import UrlParse from 'url-parse';
const url = new UrlParse('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash');
console.log(url.protocol); // 'https:'
console.log(url.hostname); // 'sub.example.com'
console.log(url.port); // '8080'
console.log(url.query); // '?query=string'
qs, query-string, and the polyfills focus exclusively on the query string part. If you pass a full URL to them, they may fail or require you to manually slice the string first.
import qs from 'qs';
// This will likely fail or return empty if passed a full URL directly depending on config
// You must extract the query part first:
const fullUrl = 'http://site.com/?a=1';
const queryOnly = fullUrl.split('?')[1];
const obj = qs.parse(queryOnly);
The packages url-search-params and url-search-params-polyfill were created to fill a gap in older browsers (specifically Internet Explorer 11 and early Edge).
URLSearchParams API globally.// β Avoid this in new code
import 'url-search-params-polyfill';
// β
Use native API directly
const params = new URLSearchParams(window.location.search);
| Feature | qs | query-string | url-parse | Native / Polyfills |
|---|---|---|---|---|
| Nested Objects | β Excellent (Deep) | β οΈ Limited / Configurable | β No (Returns String) | β No (Flat Keys Only) |
| Array Formats | β Brackets, Indices, Repeat | β Brackets, Separator, Repeat | β Manual Only | β Repeat Only |
| Full URL Parsing | β No | β No | β Yes | β
(via new URL()) |
| Bundle Size | Medium | Small | Small | 0 (Native) |
| Environment | Node & Browser | Node & Browser | Node & Browser | Browser / Node 10+ |
For complex data synchronization (like dashboards with deep filters), qs is the undisputed leader. Its ability to reliably serialize and deserialize nested structures ensures your URL state matches your application state perfectly.
For standard frontend routing where you need a lightweight dependency that handles common array cases and works universally, query-string is the modern favorite. It strikes the best balance between features and simplicity.
Use url-parse only if you are building a utility that needs to dissect full URLs in environments where the native URL API is unreliable.
Finally, drop url-search-params-polyfill and url-search-params. Rely on the native URLSearchParams API for simple key-value tasks, and reach for qs or query-string when the native API hits its limits.
Choose qs if you need to handle deeply nested objects or require strict control over array formatting (e.g., indices vs. brackets). It is the industry standard for backend-heavy Node.js applications and complex form data where data fidelity is critical.
Choose query-string if you want a lightweight, modern library that works seamlessly in both Node.js and the browser. It is ideal for typical frontend routing needs where you need to parse simple to moderately complex query parameters without the heavy feature set of qs.
Choose url-parse if your primary goal is to dissect the entire URL (protocol, host, port, path) rather than just the query string. Use this when you need a consistent parsing interface across environments that might lack the native URL constructor.
Do NOT choose url-search-params for new projects. This package is a deprecated polyfill shim. Modern browsers and Node.js versions now include the native URLSearchParams API, making this external dependency unnecessary.
Do NOT choose url-search-params-polyfill for new projects. Like the previous package, this is a legacy solution for Internet Explorer. Unless you are explicitly maintaining an old codebase that must support IE11 without transpilation, rely on native browser features instead.
A querystring parsing and stringifying library with some added security.
Lead Maintainer: Jordan Harband
The qs module was originally created and maintained by TJ Holowaychuk.
var qs = require('qs');
var assert = require('assert');
var obj = qs.parse('a=c');
assert.deepEqual(obj, { a: 'c' });
var str = qs.stringify(obj);
assert.equal(str, 'a=c');
qs.parse(string, [options]);
qs allows you to create nested objects within your query strings, by surrounding the name of sub-keys with square brackets [].
For example, the string 'foo[bar]=baz' converts to:
assert.deepEqual(qs.parse('foo[bar]=baz'), {
foo: {
bar: 'baz'
}
});
When using the plainObjects option the parsed value is returned as a null object, created via { __proto__: null } and as such you should be aware that prototype methods will not exist on it and a user may set those names to whatever value they like:
var nullObject = qs.parse('a[hasOwnProperty]=b', { plainObjects: true });
assert.deepEqual(nullObject, { a: { hasOwnProperty: 'b' } });
By default parameters that would overwrite properties on the object prototype are ignored, if you wish to keep the data from those fields either use plainObjects as mentioned above, or set allowPrototypes to true which will allow user input to overwrite those properties.
WARNING It is generally a bad idea to enable this option as it can cause problems when attempting to use the properties that have been overwritten.
Always be careful with this option.
var protoObject = qs.parse('a[hasOwnProperty]=b', { allowPrototypes: true });
assert.deepEqual(protoObject, { a: { hasOwnProperty: 'b' } });
URI encoded strings work too:
assert.deepEqual(qs.parse('a%5Bb%5D=c'), {
a: { b: 'c' }
});
You can also nest your objects, like 'foo[bar][baz]=foobarbaz':
assert.deepEqual(qs.parse('foo[bar][baz]=foobarbaz'), {
foo: {
bar: {
baz: 'foobarbaz'
}
}
});
By default, when nesting objects qs will only parse up to 5 children deep.
This means if you attempt to parse a string like 'a[b][c][d][e][f][g][h][i]=j' your resulting object will be:
var expected = {
a: {
b: {
c: {
d: {
e: {
f: {
'[g][h][i]': 'j'
}
}
}
}
}
}
};
var string = 'a[b][c][d][e][f][g][h][i]=j';
assert.deepEqual(qs.parse(string), expected);
This depth can be overridden by passing a depth option to qs.parse(string, [options]):
var deep = qs.parse('a[b][c][d][e][f][g][h][i]=j', { depth: 1 });
assert.deepEqual(deep, { a: { b: { '[c][d][e][f][g][h][i]': 'j' } } });
You can configure qs to throw an error when parsing nested input beyond this depth using the strictDepth option (defaulted to false):
try {
qs.parse('a[b][c][d][e][f][g][h][i]=j', { depth: 1, strictDepth: true });
} catch (err) {
assert(err instanceof RangeError);
assert.strictEqual(err.message, 'Input depth exceeded depth option of 1 and strictDepth is true');
}
The depth limit helps mitigate abuse when qs is used to parse user input, and it is recommended to keep it a reasonably small number. The strictDepth option adds a layer of protection by throwing an error when the limit is exceeded, allowing you to catch and handle such cases.
For similar reasons, by default qs will only parse up to 1000 parameters. This can be overridden by passing a parameterLimit option:
var limited = qs.parse('a=b&c=d', { parameterLimit: 1 });
assert.deepEqual(limited, { a: 'b' });
If you want an error to be thrown whenever the a limit is exceeded (eg, parameterLimit, arrayLimit), set the throwOnLimitExceeded option to true. This option will generate a descriptive error if the query string exceeds a configured limit.
try {
qs.parse('a=1&b=2&c=3&d=4', { parameterLimit: 3, throwOnLimitExceeded: true });
} catch (err) {
assert(err instanceof Error);
assert.strictEqual(err.message, 'Parameter limit exceeded. Only 3 parameters allowed.');
}
When throwOnLimitExceeded is set to false (default), qs will parse up to the specified parameterLimit and ignore the rest without throwing an error.
Note that parameterLimit only bounds the number of &-delimited parameters; it does not limit how many values a single parameter expands into. In particular, when comma: true is enabled, a single parameter's value is split on commas into arbitrarily many elements, which parameterLimit does not constrain. To bound the total element count from untrusted input, set throwOnLimitExceeded: true (see arrayLimit below), and always bound the input size at the transport layer (e.g. an HTTP body-size limit).
To bypass the leading question mark, use ignoreQueryPrefix:
var prefixed = qs.parse('?a=b&c=d', { ignoreQueryPrefix: true });
assert.deepEqual(prefixed, { a: 'b', c: 'd' });
An optional delimiter can also be passed:
var delimited = qs.parse('a=b;c=d', { delimiter: ';' });
assert.deepEqual(delimited, { a: 'b', c: 'd' });
Delimiters can be a regular expression too:
var regexed = qs.parse('a=b;c=d,e=f', { delimiter: /[;,]/ });
assert.deepEqual(regexed, { a: 'b', c: 'd', e: 'f' });
Option allowDots can be used to enable dot notation:
var withDots = qs.parse('a.b=c', { allowDots: true });
assert.deepEqual(withDots, { a: { b: 'c' } });
Option decodeDotInKeys can be used to decode dots in keys
Note: it implies allowDots, so parse will error if you set decodeDotInKeys to true, and allowDots to false.
var withDots = qs.parse('name%252Eobj.first=John&name%252Eobj.last=Doe', { decodeDotInKeys: true });
assert.deepEqual(withDots, { 'name.obj': { first: 'John', last: 'Doe' }});
Option allowEmptyArrays can be used to allow empty array values in an object
var withEmptyArrays = qs.parse('foo[]&bar=baz', { allowEmptyArrays: true });
assert.deepEqual(withEmptyArrays, { foo: [], bar: 'baz' });
Option duplicates can be used to change the behavior when duplicate keys are encountered
assert.deepEqual(qs.parse('foo=bar&foo=baz'), { foo: ['bar', 'baz'] });
assert.deepEqual(qs.parse('foo=bar&foo=baz', { duplicates: 'combine' }), { foo: ['bar', 'baz'] });
assert.deepEqual(qs.parse('foo=bar&foo=baz', { duplicates: 'first' }), { foo: 'bar' });
assert.deepEqual(qs.parse('foo=bar&foo=baz', { duplicates: 'last' }), { foo: 'baz' });
Note that keys with bracket notation ([]) always combine into arrays, regardless of the duplicates setting:
assert.deepEqual(qs.parse('a=1&a=2&b[]=1&b[]=2', { duplicates: 'last' }), { a: '2', b: ['1', '2'] });
If you have to deal with legacy browsers or services, there's also support for decoding percent-encoded octets as iso-8859-1:
var oldCharset = qs.parse('a=%A7', { charset: 'iso-8859-1' });
assert.deepEqual(oldCharset, { a: 'Β§' });
Some services add an initial utf8=β value to forms so that old Internet Explorer versions are more likely to submit the form as utf-8.
Additionally, the server can check the value against wrong encodings of the checkmark character and detect that a query string or application/x-www-form-urlencoded body was not sent as utf-8, eg. if the form had an accept-charset parameter or the containing page had a different character set.
qs supports this mechanism via the charsetSentinel option.
If specified, the utf8 parameter will be omitted from the returned object.
It will be used to switch to iso-8859-1/utf-8 mode depending on how the checkmark is encoded.
Important: When you specify both the charset option and the charsetSentinel option, the charset will be overridden when the request contains a utf8 parameter from which the actual charset can be deduced.
In that sense the charset will behave as the default charset rather than the authoritative charset.
var detectedAsUtf8 = qs.parse('utf8=%E2%9C%93&a=%C3%B8', {
charset: 'iso-8859-1',
charsetSentinel: true
});
assert.deepEqual(detectedAsUtf8, { a: 'ΓΈ' });
// Browsers encode the checkmark as ✓ when submitting as iso-8859-1:
var detectedAsIso8859_1 = qs.parse('utf8=%26%2310003%3B&a=%F8', {
charset: 'utf-8',
charsetSentinel: true
});
assert.deepEqual(detectedAsIso8859_1, { a: 'ΓΈ' });
If you want to decode the &#...; syntax to the actual character, you can specify the interpretNumericEntities option as well:
var detectedAsIso8859_1 = qs.parse('a=%26%239786%3B', {
charset: 'iso-8859-1',
interpretNumericEntities: true
});
assert.deepEqual(detectedAsIso8859_1, { a: 'βΊ' });
It also works when the charset has been detected in charsetSentinel mode.
qs can also parse arrays using a similar [] notation:
var withArray = qs.parse('a[]=b&a[]=c');
assert.deepEqual(withArray, { a: ['b', 'c'] });
You may specify an index as well:
var withIndexes = qs.parse('a[1]=c&a[0]=b');
assert.deepEqual(withIndexes, { a: ['b', 'c'] });
Note that the only difference between an index in an array and a key in an object is that the value between the brackets must be a number to create an array. When creating arrays with specific indices, qs will compact a sparse array to only the existing values preserving their order:
var noSparse = qs.parse('a[1]=b&a[15]=c');
assert.deepEqual(noSparse, { a: ['b', 'c'] });
You may also use allowSparse option to parse sparse arrays:
var sparseArray = qs.parse('a[1]=2&a[3]=5', { allowSparse: true });
assert.deepEqual(sparseArray, { a: [, '2', , '5'] });
Note that an empty string is also a value, and will be preserved:
var withEmptyString = qs.parse('a[]=&a[]=b');
assert.deepEqual(withEmptyString, { a: ['', 'b'] });
var withIndexedEmptyString = qs.parse('a[0]=b&a[1]=&a[2]=c');
assert.deepEqual(withIndexedEmptyString, { a: ['b', '', 'c'] });
qs will also limit arrays to a maximum of 20 elements.
Any array members with an index of 20 or greater will instead be converted to an object with the index as the key.
This is needed to handle cases when someone sent, for example, a[999999999] and it will take significant time to iterate over this huge array.
var withMaxIndex = qs.parse('a[100]=b');
assert.deepEqual(withMaxIndex, { a: { '100': 'b' } });
This limit can be overridden by passing an arrayLimit option:
var withArrayLimit = qs.parse('a[1]=b', { arrayLimit: 0 });
assert.deepEqual(withArrayLimit, { a: { '1': 'b' } });
If you want to throw an error whenever the array limit is exceeded, set the throwOnLimitExceeded option to true. This option will generate a descriptive error if the query string exceeds a configured limit.
try {
qs.parse('a[1]=b', { arrayLimit: 0, throwOnLimitExceeded: true });
} catch (err) {
assert(err instanceof Error);
assert.strictEqual(err.message, 'Array limit exceeded. Only 0 elements allowed in an array.');
}
When throwOnLimitExceeded is set to false (default), qs will parse up to the specified arrayLimit and if the limit is exceeded, the array will instead be converted to an object with the index as the key.
Note that arrayLimit is a representation threshold that controls when a numerically-indexed collection switches from an array to an object β it is not a hard cap on the total number of elements parsed. With the default throwOnLimitExceeded: false, exceeding arrayLimit never rejects or truncates input; it only changes the container type, and the resulting object still holds every element (so its size stays proportional to the input). This conversion is itself a safeguard: it avoids allocating a huge sparse array for input like a[999999999]. If you need a hard limit that rejects oversized input from untrusted sources, set throwOnLimitExceeded: true.
To prevent array syntax (a[], a[0]) from being parsed as arrays, set parseArrays to false.
Note that duplicate keys (e.g. a=b&a=c) may still produce arrays when duplicates is 'combine' (the default).
var noParsingArrays = qs.parse('a[]=b', { parseArrays: false });
assert.deepEqual(noParsingArrays, { a: { '0': 'b' } });
If you mix notations, qs will merge the two items into an object:
var mixedNotation = qs.parse('a[0]=b&a[b]=c');
assert.deepEqual(mixedNotation, { a: { '0': 'b', b: 'c' } });
When a key appears as both a plain value and an object, qs will by default wrap the conflicting values in an array (strictMerge defaults to true):
assert.deepEqual(qs.parse('a[b]=c&a=d'), { a: [{ b: 'c' }, 'd'] });
assert.deepEqual(qs.parse('a=d&a[b]=c'), { a: ['d', { b: 'c' }] });
To restore the legacy behavior (where the primitive is used as a key with value true), set strictMerge to false:
assert.deepEqual(qs.parse('a[b]=c&a=d', { strictMerge: false }), { a: { b: 'c', d: true } });
You can also create arrays of objects:
var arraysOfObjects = qs.parse('a[][b]=c');
assert.deepEqual(arraysOfObjects, { a: [{ b: 'c' }] });
Some people use comma to join array, qs can parse it:
var arraysOfObjects = qs.parse('a=b,c', { comma: true })
assert.deepEqual(arraysOfObjects, { a: ['b', 'c'] })
(this cannot convert nested objects, such as a={b:1},{c:d})
By default, all values are parsed as strings. This behavior will not change and is explained in issue #91.
var primitiveValues = qs.parse('a=15&b=true&c=null');
assert.deepEqual(primitiveValues, { a: '15', b: 'true', c: 'null' });
If you wish to auto-convert values which look like numbers, booleans, and other values into their primitive counterparts, you can use the query-types Express JS middleware which will auto-convert all request query parameters.
qs.stringify(object, [options]);
When stringifying, qs by default URI encodes output. Objects are stringified as you would expect:
assert.equal(qs.stringify({ a: 'b' }), 'a=b');
assert.equal(qs.stringify({ a: { b: 'c' } }), 'a%5Bb%5D=c');
This encoding can be disabled by setting the encode option to false:
var unencoded = qs.stringify({ a: { b: 'c' } }, { encode: false });
assert.equal(unencoded, 'a[b]=c');
Encoding can be disabled for keys by setting the encodeValuesOnly option to true:
var encodedValues = qs.stringify(
{ a: 'b', c: ['d', 'e=f'], f: [['g'], ['h']] },
{ encodeValuesOnly: true }
);
assert.equal(encodedValues,'a=b&c[0]=d&c[1]=e%3Df&f[0][0]=g&f[1][0]=h');
This encoding can also be replaced by a custom encoding method set as encoder option:
var encoded = qs.stringify({ a: { b: 'c' } }, { encoder: function (str) {
// Passed in values `a`, `b`, `c`
return // Return encoded string
}})
(Note: the encoder option does not apply if encode is false)
By default, qs.stringify serializes an object of any nesting depth.
For backwards compatibility, and because its input is the caller's own object rather than a query string parsed by qs, this is unbounded.
If you serialize objects whose nesting can be influenced by untrusted input, bound it with the numeric depth option (default Infinity);
exceeding it throws a catchable RangeError instead of eventually overflowing the call stack:
try {
qs.stringify({ a: { b: { c: { d: 'e' } } } }, { depth: 2 });
} catch (err) {
assert(err instanceof RangeError);
assert.strictEqual(err.message, 'Input depth exceeded depth option of 2');
}
Analogue to the encoder there is a decoder option for parse to override decoding of properties and values:
var decoded = qs.parse('x=z', { decoder: function (str) {
// Passed in values `x`, `z`
return // Return decoded string
}})
You can encode keys and values using different logic by using the type argument provided to the encoder:
var encoded = qs.stringify({ a: { b: 'c' } }, { encoder: function (str, defaultEncoder, charset, type) {
if (type === 'key') {
return // Encoded key
} else if (type === 'value') {
return // Encoded value
}
}})
The type argument is also provided to the decoder:
var decoded = qs.parse('x=z', { decoder: function (str, defaultDecoder, charset, type) {
if (type === 'key') {
return // Decoded key
} else if (type === 'value') {
return // Decoded value
}
}})
Examples beyond this point will be shown as though the output is not URI encoded for clarity. Please note that the return values in these cases will be URI encoded during real usage.
When arrays are stringified, they follow the arrayFormat option, which defaults to indices:
qs.stringify({ a: ['b', 'c', 'd'] });
// 'a[0]=b&a[1]=c&a[2]=d'
You may override this by setting the indices option to false, or to be more explicit, the arrayFormat option to repeat:
qs.stringify({ a: ['b', 'c', 'd'] }, { indices: false });
// 'a=b&a=c&a=d'
You may use the arrayFormat option to specify the format of the output array:
qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'indices' })
// 'a[0]=b&a[1]=c'
qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'brackets' })
// 'a[]=b&a[]=c'
qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'repeat' })
// 'a=b&a=c'
qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'comma' })
// 'a=b,c'
Note: when using arrayFormat set to 'comma', you can also pass the commaRoundTrip option set to true or false, to append [] on single-item arrays, so that they can round trip through a parse.
When objects are stringified, by default they use bracket notation:
qs.stringify({ a: { b: { c: 'd', e: 'f' } } });
// 'a[b][c]=d&a[b][e]=f'
You may override this to use dot notation by setting the allowDots option to true:
qs.stringify({ a: { b: { c: 'd', e: 'f' } } }, { allowDots: true });
// 'a.b.c=d&a.b.e=f'
You may encode the dot notation in the keys of object with option encodeDotInKeys by setting it to true:
Note: it implies allowDots, so stringify will error if you set decodeDotInKeys to true, and allowDots to false.
Caveat: when encodeValuesOnly is true as well as encodeDotInKeys, only dots in keys and nothing else will be encoded.
qs.stringify({ "name.obj": { "first": "John", "last": "Doe" } }, { allowDots: true, encodeDotInKeys: true })
// 'name%252Eobj.first=John&name%252Eobj.last=Doe'
You may allow empty array values by setting the allowEmptyArrays option to true:
qs.stringify({ foo: [], bar: 'baz' }, { allowEmptyArrays: true });
// 'foo[]&bar=baz'
Empty strings and null values will omit the value, but the equals sign (=) remains in place:
assert.equal(qs.stringify({ a: '' }), 'a=');
Key with no values (such as an empty object or array) will return nothing:
assert.equal(qs.stringify({ a: [] }), '');
assert.equal(qs.stringify({ a: {} }), '');
assert.equal(qs.stringify({ a: [{}] }), '');
assert.equal(qs.stringify({ a: { b: []} }), '');
assert.equal(qs.stringify({ a: { b: {}} }), '');
Properties that are set to undefined will be omitted entirely:
assert.equal(qs.stringify({ a: null, b: undefined }), 'a=');
The query string may optionally be prepended with a question mark:
assert.equal(qs.stringify({ a: 'b', c: 'd' }, { addQueryPrefix: true }), '?a=b&c=d');
Note that when the output is an empty string, the prefix will not be added:
assert.equal(qs.stringify({}, { addQueryPrefix: true }), '');
The delimiter may be overridden with stringify as well:
assert.equal(qs.stringify({ a: 'b', c: 'd' }, { delimiter: ';' }), 'a=b;c=d');
If you only want to override the serialization of Date objects, you can provide a serializeDate option:
var date = new Date(7);
assert.equal(qs.stringify({ a: date }), 'a=1970-01-01T00:00:00.007Z'.replace(/:/g, '%3A'));
assert.equal(
qs.stringify({ a: date }, { serializeDate: function (d) { return d.getTime(); } }),
'a=7'
);
You may use the sort option to affect the order of parameter keys:
function alphabeticalSort(a, b) {
return a.localeCompare(b);
}
assert.equal(qs.stringify({ a: 'c', z: 'y', b : 'f' }, { sort: alphabeticalSort }), 'a=c&b=f&z=y');
Finally, you can use the filter option to restrict which keys will be included in the stringified output.
If you pass a function, it will be called for each key to obtain the replacement value.
Otherwise, if you pass an array, it will be used to select properties and array indices for stringification:
function filterFunc(prefix, value) {
if (prefix == 'b') {
// Return an `undefined` value to omit a property.
return;
}
if (prefix == 'e[f]') {
return value.getTime();
}
if (prefix == 'e[g][0]') {
return value * 2;
}
return value;
}
qs.stringify({ a: 'b', c: 'd', e: { f: new Date(123), g: [2] } }, { filter: filterFunc });
// 'a=b&c=d&e[f]=123&e[g][0]=4'
qs.stringify({ a: 'b', c: 'd', e: 'f' }, { filter: ['a', 'e'] });
// 'a=b&e=f'
qs.stringify({ a: ['b', 'c', 'd'], e: 'f' }, { filter: ['a', 0, 2] });
// 'a[0]=b&a[2]=d'
You could also use filter to inject custom serialization for user defined types.
Consider you're working with some api that expects query strings of the format for ranges:
https://domain.com/endpoint?range=30...70
For which you model as:
class Range {
constructor(from, to) {
this.from = from;
this.to = to;
}
}
You could inject a custom serializer to handle values of this type:
qs.stringify(
{
range: new Range(30, 70),
},
{
filter: (prefix, value) => {
if (value instanceof Range) {
return `${value.from}...${value.to}`;
}
// serialize the usual way
return value;
},
}
);
// range=30...70
null valuesBy default, null values are treated like empty strings:
var withNull = qs.stringify({ a: null, b: '' });
assert.equal(withNull, 'a=&b=');
Parsing does not distinguish between parameters with and without equal signs. Both are converted to empty strings.
var equalsInsensitive = qs.parse('a&b=');
assert.deepEqual(equalsInsensitive, { a: '', b: '' });
To distinguish between null values and empty strings use the strictNullHandling flag. In the result string the null
values have no = sign:
var strictNull = qs.stringify({ a: null, b: '' }, { strictNullHandling: true });
assert.equal(strictNull, 'a&b=');
To parse values without = back to null use the strictNullHandling flag:
var parsedStrictNull = qs.parse('a&b=', { strictNullHandling: true });
assert.deepEqual(parsedStrictNull, { a: null, b: '' });
To completely skip rendering keys with null values, use the skipNulls flag:
var nullsSkipped = qs.stringify({ a: 'b', c: null}, { skipNulls: true });
assert.equal(nullsSkipped, 'a=b');
If you're communicating with legacy systems, you can switch to iso-8859-1 using the charset option:
var iso = qs.stringify({ Γ¦: 'Γ¦' }, { charset: 'iso-8859-1' });
assert.equal(iso, '%E6=%E6');
Characters that don't exist in iso-8859-1 will be converted to numeric entities, similar to what browsers do:
var numeric = qs.stringify({ a: 'βΊ' }, { charset: 'iso-8859-1' });
assert.equal(numeric, 'a=%26%239786%3B');
You can use the charsetSentinel option to announce the character by including an utf8=β parameter with the proper encoding if the checkmark, similar to what Ruby on Rails and others do when submitting forms.
var sentinel = qs.stringify({ a: 'βΊ' }, { charsetSentinel: true });
assert.equal(sentinel, 'utf8=%E2%9C%93&a=%E2%98%BA');
var isoSentinel = qs.stringify({ a: 'Γ¦' }, { charsetSentinel: true, charset: 'iso-8859-1' });
assert.equal(isoSentinel, 'utf8=%26%2310003%3B&a=%E6');
By default the encoding and decoding of characters is done in utf-8, and iso-8859-1 support is also built in via the charset parameter.
If you wish to encode querystrings to a different character set (i.e.
Shift JIS) you can use the
qs-iconv library:
var encoder = require('qs-iconv/encoder')('shift_jis');
var shiftJISEncoded = qs.stringify({ a: 'γγγ«γ‘γ―οΌ' }, { encoder: encoder });
assert.equal(shiftJISEncoded, 'a=%82%B1%82%F1%82%C9%82%BF%82%CD%81I');
This also works for decoding of query strings:
var decoder = require('qs-iconv/decoder')('shift_jis');
var obj = qs.parse('a=%82%B1%82%F1%82%C9%82%BF%82%CD%81I', { decoder: decoder });
assert.deepEqual(obj, { a: 'γγγ«γ‘γ―οΌ' });
RFC3986 used as default option and encodes ' ' to %20 which is backward compatible. In the same time, output can be stringified as per RFC1738 with ' ' equal to '+'.
assert.equal(qs.stringify({ a: 'b c' }), 'a=b%20c');
assert.equal(qs.stringify({ a: 'b c' }, { format : 'RFC3986' }), 'a=b%20c');
assert.equal(qs.stringify({ a: 'b c' }, { format : 'RFC1738' }), 'a=b+c');
Please email @ljharb or see https://tidelift.com/security if you have a potential security vulnerability to report.
Available as part of the Tidelift Subscription
The maintainers of qs and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.
qs logo by NUMI: