Browse files

doc: document URLSearchParams constructor

PR-URL: #11060
Ref: whatwg/url#175
Reviewed-By: Anna Henningsen <>
Reviewed-By: James M Snell <>
Reviewed-By: Joyee Cheung <>
  • Loading branch information...
TimothyGu committed Jan 28, 2017
1 parent 29f7587 commit c505b8109e7eb57b4c54162682401279ba0d9bac
Showing with 122 additions and 4 deletions.
  1. +122 −4 doc/api/
@@ -525,10 +525,12 @@ value returned is equivalent to that of `url.href`.
### Class: URLSearchParams
The `URLSearchParams` object provides read and write access to the query of a
`URL`. The `URLSearchParams` class can also be used standalone with one of the
four following constructors.
const URL = require('url').URL;
const { URL, URLSearchParams } = require('url');
const myURL = new URL('');
// Prints 123
@@ -541,11 +543,125 @@ myURL.searchParams.delete('abc');
myURL.searchParams.set('a', 'b');
// Prints
const newSearchParams = new URLSearchParams(myURL.searchParams);
// The above is equivalent to
// const newSearchParams = new URLSearchParams(;
newSearchParams.append('a', 'c');
// Prints
// Prints a=b&a=c
// newSearchParams.toString() is implicitly called = newSearchParams;
// Prints
// Prints
#### Constructor: new URLSearchParams()
Instantiate a new empty `URLSearchParams` object.
#### Constructor: new URLSearchParams(string)
* `string` {String} A query string
Parse the `string` as a query string, and use it to instantiate a new
`URLSearchParams` object. A leading `'?'`, if present, is ignored.
const { URLSearchParams } = require('url');
let params;
params = new URLSearchParams('user=abc&query=xyz');
// Prints 'abc'
// Prints 'user=abc&query=xyz'
params = new URLSearchParams('?user=abc&query=xyz');
// Prints 'user=abc&query=xyz'
#### Constructor: new URLSearchParams([init])
#### Constructor: new URLSearchParams(obj)
* `obj` {Object} An object representing a collection of key-value pairs
Instantiate a new `URLSearchParams` object with a query hash map. The key and
value of each property of `obj` are always coerced to strings.
* `init` {String} The URL query
*Note*: Unlike [`querystring`][] module, duplicate keys in the form of array
values are not allowed. Arrays are stringified using [`array.toString()`][],
which simply joins all array elements with commas.
const { URLSearchParams } = require('url');
const params = new URLSearchParams({
user: 'abc',
query: ['first', 'second']
// Prints ['first,second']
// Prints 'user=abc&query=first%2Csecond'
#### Constructor: new URLSearchParams(iterable)
* `iterable` {Iterable} An iterable object whose elements are key-value pairs
Instantiate a new `URLSearchParams` object with an iterable map in a way that
is similar to [`Map`][]'s constructor. `iterable` can be an Array or any
iterable object. That means `iterable` can be another `URLSearchParams`, in
which case the constructor will simply create a clone of the provided
`URLSearchParams`. Elements of `iterable` are key-value pairs, and can
themselves be any iterable object.
Duplicate keys are allowed.
const { URLSearchParams } = require('url');
let params;
// Using an array
params = new URLSearchParams([
['user', 'abc'],
['query', 'first'],
['query', 'second']
// Prints 'user=abc&query=first&query=second'
// Using a Map object
const map = new Map();
map.set('user', 'abc');
map.set('query', 'xyz');
params = new URLSearchParams(map);
// Prints 'user=abc&query=xyz'
// Using a generator function
function* getQueryPairs() {
yield ['user', 'abc'];
yield ['query', 'first'];
yield ['query', 'second'];
params = new URLSearchParams(getQueryPairs());
// Prints 'user=abc&query=first&query=second'
// Each key-value pair must have exactly two elements
new URLSearchParams([
['user', 'abc', 'error']
// Throws TypeError: Each query pair must be a name/value tuple
#### urlSearchParams.append(name, value)
@@ -712,3 +828,5 @@ console.log(myURL.origin);
[`url.parse()`]: #url_url_parse_urlstring_parsequerystring_slashesdenotehost
[`url.format()`]: #url_url_format_urlobject

0 comments on commit c505b81

Please sign in to comment.