URLSearchParams
An object for reading and building query parameters in an address, the part after the ? character, e.g. ?course=js&page=2.
- Returns
- A new
URLSearchParamsobject.
Example
#const params = new URLSearchParams('?course=javascript&page=2&tag=dom&tag=events')
console.log(params.get('course'))
console.log(Number(params.get('page')) + 1)
console.log(params.get('sort'))
console.log(params.getAll('tag'))
console.log(params.has('tag'))Definition and usage
#URLSearchParams stores query parameters as a list of name-value pairs. You can create an object from a string ("?course=js&page=2", a leading ? is ignored), from a plain object ({ course: "js" }), or from an array of pairs. A ready-made object is also available on the searchParams property of every URL object.
The get(name) method returns the parameter’s value or null when it doesn’t exist, getAll() returns every value with that name, has() checks whether it’s present, set() sets a value (replacing any previous one), append() adds another value under the same name, and delete() removes a parameter. Values are always strings, so convert numbers with Number().
The toString() method assembles the parameters back into a string and encodes special characters: a space becomes +, and accented letters become %XX sequences. You can loop over the object with for...of, and Object.fromEntries(params) turns it into a plain object. An object passed as the body to fetch() is sent in the same format as a regular form.
Syntax
#new URLSearchParams(init)
params.get(name)
params.getAll(name)
params.has(name)
params.set(name, value)
params.append(name, value)
params.delete(name)
params.toString()
params.sizeParameters
#init
optional
A string with parameters (e.g.location.search), an object with name-value pairs, or an array of[name, value]pairs.
More examples
#const params = new URLSearchParams({ search: 'for loop', level: 'beginner' })
params.append('tag', 'js')
params.set('level', 'intermediate')
console.log(params.toString())
console.log(`/api/courses?${params}`)set() changes the value of an existing parameter in the same spot in the list. In the template literal the object turns itself into a string through toString().
const params = new URLSearchParams('name=Emma&points=340&badge=start')
for (const [name, value] of params) {
console.log(`${name} = ${value}`)
}
console.log(Object.fromEntries(params))
console.log(params.size)const address = 'https://codeworlds.com/ranking?period=week&page=3'
const url = new URL(address)
url.searchParams.set('page', '1')
url.searchParams.delete('period')
url.searchParams.append('course', 'python')
console.log(url.search)
console.log(url.href)Changes to url.searchParams immediately update the URL object’s search and href.
Browser support
#Widely available
Works in all modern browsers, phones included. You can use it without worry.
- Chrome
- Edge
- Firefox
- Safari
Good practices
#- Read the current page’s parameters with
new URLSearchParams(location.search). get()returns a string ornull, andNumber(null)is0. Give a missing parameter a default value:Number(params.get("page") ?? 1).- Don’t encode values by hand with
encodeURIComponent()beforeset(), or they’ll be encoded twice.URLSearchParamsdoes it for you.
Related entries
#- URLAn object for creating, reading, and changing URLs. It breaks an address into parts: protocol, host, path, and parameters.
- locationAn object with information about the current page’s address. Lets you read its parts and navigate to a different address.
- history.pushState()Adds a new entry to the browser history and changes the address bar without reloading the page.
- FormDataCollects form field values into name-value pairs. The ready-made object can be read or sent to the server with fetch().
- Object.fromEntries()Creates an object from a list of [key, value] pairs.
- fetch()Sends an HTTP request and returns a promise with the server’s response (a Response object).
Spotted a mistake or missing an example? Write to us.