Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork454
Parse and stringify URL query strings
License
sindresorhus/query-string
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Parse and stringify URLquery strings
npm install query-string
Warning
Remember the hyphen! Do not install the deprecatedquerystring package!
For browser usage, this package targets the latest version of Chrome, Firefox, and Safari.
Tip
Consider usingURLSearchParams for simple use cases. It's a native browser API that handles basic query string operations.
importqueryStringfrom'query-string';console.log(location.search);//=> '?foo=bar'constparsed=queryString.parse(location.search);console.log(parsed);//=> {foo: 'bar'}console.log(location.hash);//=> '#token=bada55cafe'constparsedHash=queryString.parse(location.hash);console.log(parsedHash);//=> {token: 'bada55cafe'}parsed.foo='unicorn';parsed.ilike='pizza';conststringified=queryString.stringify(parsed);//=> 'foo=unicorn&ilike=pizza'location.search=stringified;// note that `location.search` automatically prepends a question markconsole.log(location.search);//=> '?foo=unicorn&ilike=pizza'
Parse a query string into an object. Leading? or# are ignored, so you can passlocation.search orlocation.hash directly.
The returned object is created withObject.create(null) and thus does not have aprototype.
queryString.parse('?foo=bar');//=> {foo: 'bar'}queryString.parse('#token=secret&name=jhon');//=> {token: 'secret', name: 'jhon'}
Type:object
Type:boolean
Default:true
Decode the keys and values. URL components are decoded withdecode-uri-component.
Type:string
Default:'none'
'bracket': Parse arrays with bracket representation:
importqueryStringfrom'query-string';queryString.parse('foo[]=1&foo[]=2&foo[]=3',{arrayFormat:'bracket'});//=> {foo: ['1', '2', '3']}
'index': Parse arrays with index representation:
importqueryStringfrom'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:
importqueryStringfrom'query-string';queryString.parse('foo=1,2,3',{arrayFormat:'comma'});//=> {foo: ['1', '2', '3']}
'separator': Parse arrays with elements separated by a custom character:
importqueryStringfrom'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:
importqueryStringfrom'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:
importqueryStringfrom'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:
importqueryStringfrom'query-string';queryString.parse('foo=1&foo=2&foo=3');//=> {foo: ['1', '2', '3']}
Type:string
Default:','
The character used to separate array elements when using{arrayFormat: 'separator'}.
Type:Function | boolean
Default:true
Supports bothFunction as a custom sorting function orfalse to disable sorting.
Type:boolean
Default:false
importqueryStringfrom'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.
Type:boolean
Default:false
importqueryStringfrom'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.
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 asparseNumbers,parseBooleans, andarrayFormat.
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 (likecomma,separator,bracket, etc.), the function is applied to each array element individually.
Supported Types:
'boolean': Parseflaggedas a boolean (overriding theparseBooleansoption):
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) astrue.
'string': ParsephoneNumberas a string (overriding theparseNumbersoption):
importqueryStringfrom'query-string';queryString.parse('?phoneNumber=%2B380951234567&id=1',{parseNumbers:true,types:{phoneNumber:'string',}});//=> {phoneNumber: '+380951234567', id: 1}
'number': Parseageas a number (even whenparseNumbersis false):
importqueryStringfrom'query-string';queryString.parse('?age=20&id=01234&zipcode=90210',{types:{age:'number',}});//=> {age: 20, id: '01234', zipcode: '90210'}
'string[]': Parseitemsas an array of strings (overriding theparseNumbersoption):
importqueryStringfrom'query-string';queryString.parse('?age=20&items=1%2C2%2C3',{parseNumbers:true,types:{items:'string[]',}});//=> {age: 20, items: ['1', '2', '3']}
'number[]': Parseitemsas an array of numbers (even whenparseNumbersis false):
importqueryStringfrom'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 (likecomma,separator,bracket, etc.), the function is applied to each array element individually.
importqueryStringfrom'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 elementqueryString.parse('?scores=10,20,30',{arrayFormat:'comma',types:{scores:value=>Number(value)*2,}});//=> {scores: [20, 40, 60]}
NOTE: Array types (string[],number[]) are ignored ifarrayFormat 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'}
importqueryStringfrom'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 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 likeSymbol, functions, or objects (except arrays) will throw an error.
Type:object
Type:boolean
Default:true
Strictly encode URI components. It usesencodeURIComponent if set to false. You probablydon't care about this option.
Type:boolean
Default:true
URL encode the keys and values.
Type:string
Default:'none'
'bracket': Serialize arrays using bracket representation:
importqueryStringfrom'query-string';queryString.stringify({foo:[1,2,3]},{arrayFormat:'bracket'});//=> 'foo[]=1&foo[]=2&foo[]=3'
'index': Serialize arrays using index representation:
importqueryStringfrom'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:
importqueryStringfrom'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:
importqueryStringfrom'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:
importqueryStringfrom'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:
importqueryStringfrom'query-string';queryString.stringify({foo:['one','two']},{arrayFormat:'colon-list-separator'});//=> 'foo:list=one&foo:list=two'
'none': Serialize arrays by using duplicate keys:
importqueryStringfrom'query-string';queryString.stringify({foo:[1,2,3]});//=> 'foo=1&foo=2&foo=3'
Type:string
Default:','
The character used to separate array elements when using{arrayFormat: 'separator'}.
Type:Function | boolean
Supports bothFunction as a custom sorting function orfalse to disable sorting.
importqueryStringfrom'query-string';constorder=['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'
importqueryStringfrom'query-string';queryString.stringify({b:1,c:2,a:3},{sort:false});//=> 'b=1&c=2&a=3'
If omitted, keys are sorted usingArray#sort(), which means, converting them to strings and comparing strings in Unicode code point order.
Skip keys withnull as the value.
Note that keys withundefined as the value are always skipped.
Type:boolean
Default:false
importqueryStringfrom'query-string';queryString.stringify({a:1,b:undefined,c:null,d:4},{skipNull:true});//=> 'a=1&d=4'
importqueryStringfrom'query-string';queryString.stringify({a:undefined,b:null},{skipNull:true});//=> ''
Skip keys with an empty string as the value.
Type:boolean
Default:false
importqueryStringfrom'query-string';queryString.stringify({a:1,b:'',c:'',d:4},{skipEmptyString:true});//=> 'a=1&d=4'
importqueryStringfrom'query-string';queryString.stringify({a:'',b:''},{skipEmptyString:true});//=> ''
A function that transforms key-value pairs before stringification.
Type:function
Default:undefined
Similar to thereplacer parameter ofJSON.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. Returningundefined will omit the key-value pair from the resulting query string.
This is useful for custom serialization of non-primitive types likeDate:
importqueryStringfrom'query-string';queryString.stringify({date:newDate('2024-01-15T10:30:00Z'),name:'John'},{replacer:(key,value)=>{if(valueinstanceofDate){returnvalue.toISOString();}returnvalue;}});//=> 'date=2024-01-15T10%3A30%3A00.000Z&name=John'
You can also use it to filter out keys:
importqueryStringfrom'query-string';queryString.stringify({a:1,b:null,c:3},{replacer:(key,value)=>value===null ?undefined :value});//=> 'a=1&c=3'
Extract a query string from a URL that can be passed into.parse().
queryString.extract('https://foo.bar?foo=bar');//=> 'foo=bar'
Extract the URL and the query string as an object.
Returns an object with aurl andquery property.
If theparseFragmentIdentifier option istrue, the object will also contain afragmentIdentifier property.
importqueryStringfrom'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'}
Type:object
The options are the same as for.parse().
Extra options are as below.
Parse the fragment identifier from the URL.
Type:boolean
Default:false
importqueryStringfrom'query-string';queryString.parseUrl('https://foo.bar?foo=bar#xyz',{parseFragmentIdentifier:true});//=> {url: 'https://foo.bar', query: {foo: 'bar'}, fragmentIdentifier: 'xyz'}
Stringify an object into a URL with a query string and sorting the keys. The inverse of.parseUrl()
Theoptions are the same as for.stringify().
Returns a string with the URL and a query string.
Query items in thequery property overrides queries in theurl property.
ThefragmentIdentifier property overrides the fragment identifier in theurl 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'
Type:object
Type:string
The URL to stringify.
Type:object
Query items to add to the URL.
Pick query parameters from a URL.
Returns a string with the new URL.
importqueryStringfrom'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 query parameters from a URL.
Returns a string with the new URL.
importqueryStringfrom'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'
Type:string
The URL containing the query parameters to filter.
Type:string[]
The names of the query parameters to filter based on the function used.
Type:(key, value) => boolean
A filter predicate that will be provided the name of each query parameter and its value. TheparseNumbers andparseBooleans options also affectvalue.
Type:object
Parse options andstringify options.
This module intentionally doesn't support nesting as it's not spec'd and varies between implementations, which causes a lot ofedge cases.
You're much better off just converting the object to a JSON string:
importqueryStringfrom'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:
importqueryStringfrom'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'
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:
importqueryStringfrom'query-string';queryString.stringify({foo:false});//=> 'foo=false'queryString.stringify({foo:null});//=> 'foo'queryString.stringify({foo:undefined});//=> ''
Seethis answer.
About
Parse and stringify URL query strings
Topics
Resources
License
Code of conduct
Contributing
Security policy
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Sponsor this project
Uh oh!
There was an error while loading.Please reload this page.
