# Add and update query string parameters using URLSearchParams

By Atta Ur Rehman Shah (https://attacomsian.com/about). Published Apr 20, 2020, updated Oct 7, 2022. Topics: JavaScript.
Canonical URL: https://attacomsian.com/blog/javascript-url-search-params

> An introduction to URLSearchParams interface and how to use it to add, update and delete query string parameters in JavaScript.

As a front-end developer, you should know how to manipulate query string parameters on the client side. Today, we'll look at the `URLSearchParams` interface that can be used to add, update or delete query string parameters in JavaScript.

## Initializing `URLSearchParams`

To create a new instance of `URLSearchParams`, just pass the query string part of the URL (with or without the initial `?`) to its constructor.

If you are working in a browser, you can access the query string part of the current URL with `window.location.search`:

```javascript
const params = new URLSearchParams(window.location.search)
```

Alternatively, you can create a new [URL object](https://attacomsian.com/blog/javascript-url-object) and retrieve all query parameters like below:

```javascript
// current URL
const url = 'http://example.com?size=M&color=blue&price=29&sort=desc'

// create a URL object
const urlObj = new URL(url)

// initialize URLSearchParams
const params = new URLSearchParams(urlObj.search)
```

The `URLSearchParams` constructor also accepts a JavaScript object and automatically [turns it to a query string](https://attacomsian.com/blog/javascript-convert-object-to-query-string-parameters):

```javascript
const obj = {
  size: 'M',
  color: 'blue',
  price: 29,
  sort: 'desc'
}

// initialize URLSearchParams from object
const params = new URLSearchParams(obj)
```

## Accessing Parameters

To get the value of a query parameter, you can use the `get()` method. If the parameter doesn't exist or it is empty, you will get a `null` value:

```javascript
params.get('price')   // 29
params.get('page')  // null
```

To check if a certain query parameter is present, you can use the `has()` method:

```javascript
params.has('size')  // true
params.has('user')   // false
```

You should always use the `has()` method to check the existence of the parameter before accessing its value. It avoids a false positive when the parameter is present in the URL but has no value, for example, `size=&rows=12`. 

### Getting multiple parameters

Sometimes a URL may contain more than one value of a single parameter. Let us look at the following URL:

```http
http://example.com?size=M&size=XL&color=blue
```

The above URL is 100% valid. When you will parse the above URL with `URLSearchParams`, it will create an array of values for the `size` parameter.

However, if you use the `get()` method to access `size`, you will only get the first value `M`. To get all values of a query string parameter, you should use the `getAll()` method:

```javascript
params.getAll('size') // [ 'M', 'XL' ]
```

## Modifying Parameters

The `set()` method can be used to **add** a new query parameter or **update** the existing parameter value:

```javascript
// add new param
params.set('page', 2)

// update existing param
param.set('price', 9)
```

Note that if the parameter contains more than values, the `set()` method will remove all of them and set a new value:

```javascript
// URL: http://example.com?size=M&size=XL&color=blue&price=29&sort=desc

// change `size` to `L`
params.set('size', 'L')

console.log([...params.keys()])   // [ 'size', 'color', 'price', 'sort' ]
console.log([...params.values()]) // [ 'L', 'blue', '29', 'desc' ]
```

To avoid overriding the existing parameter values, you should use the `append()` method instead. As its name suggests, `append()` will add a new parameter if it doesn't already exist. Otherwise, it will append a new value to it.

Here is an example:

```javascript
// URL: http://example.com?size=M&size=XL&color=blue&price=29&sort=desc

// append new color
params.append('color', 'pink')

console.log([...params.entries()])

// [ [ 'size', 'M' ],
//   [ 'size', 'XL' ],
//   [ 'color', 'blue' ],
//   [ 'price', '29' ],
//   [ 'sort', 'desc' ],
//   [ 'color', 'pink' ] ]
```

To **delete** a query string parameter from the URL, `URLSearchParams` provides the `delete()` method:

```javascript
// URL: http://example.com?size=M&size=XL&color=blue&price=29&sort=desc

// remove size
params.delete('size')

console.log([...params.entries()])

// [ [ 'color', 'blue' ], [ 'price', '29' ], [ 'sort', 'desc' ] ]

```

As you can see above, the `delete()` method removes all values of the `size` parameter.

## Iterating through Parameters

To iterate over all parameters included in the `URLSearchParams` object, the first way is to use the [for...of](https://attacomsian.com/blog/javascript-for-of-loop) loop:

```javascript
for (const p of params) {
  console.log(p)
}

// [ 'size', 'M' ]
// [ 'size', 'XL' ]
// [ 'color', 'blue' ]
// [ 'price', '29' ]
// [ 'sort', 'desc' ]
```

The `URLSearchParams` also supports the [forEach()](https://attacomsian.com/blog/javascript-foreach) loop that can be used to iterate through all values contained in the object with a callback function:

```javascript
params.forEach((value, key) => {
  console.log(`${key} => ${value}`)
})

// size => M
// size => XL
// color => blue
// price => 29
// sort => desc
```

You can also use the `key()`, `values()`, and `entries()` methods to get an iterator of all keys, values, or key-value pairs available in `URLSearchParams`.


## Getting Query String

Once you are done with the modifications, you can get all parameters as a [query string](https://attacomsian.com/blog/javascript-query-string) by using the `toString()` method:

```javascript
// URL: http://example.com?size=M&size=XL&color=blue&price=29&sort=desc

// remove size
params.delete('size')

// add page
params.set('page', 1)

console.log(params.toString())

// color=blue&price=29&sort=desc&page=1
```

Notice the missing `?` in front of the query string. The `toString()` doesn't add it. You need to manually use `?` when updating the URL with the new query string.

## Browser Compatibility

At the time of writing, the `URLSearchParams` object is [supported](https://caniuse.com/#feat=urlsearchparams) by all major browsers except IE and Opera Mini. However, you can use a [polyfill](https://github.com/ungap/url-search-params) to ensure your application continues working even in old browsers.