1---
2category: Browser
3---
4 
5# useUrlSearchParams
6 
7Reactive [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
8 
9## Usage
10 
11```ts
12import { useUrlSearchParams } from '@vueuse/core'
13 
14const params = useUrlSearchParams('history')
15 
16console.log(params.foo) // 'bar'
17 
18params.foo = 'bar'
19params.vueuse = 'awesome'
20// url updated to `?foo=bar&vueuse=awesome`
21```
22 
23### Hash Mode
24 
25When using with hash mode route, specify the `mode` to `hash`
26 
27```ts
28import { useUrlSearchParams } from '@vueuse/core'
29 
30const params = useUrlSearchParams('hash')
31 
32params.foo = 'bar'
33params.vueuse = 'awesome'
34// url updated to `#/your/route?foo=bar&vueuse=awesome`
35```
36 
37### Hash Params
38 
39When using with history mode route, but want to use hash as params, specify the `mode` to `hash-params`
40 
41```ts
42import { useUrlSearchParams } from '@vueuse/core'
43 
44const params = useUrlSearchParams('hash-params')
45 
46params.foo = 'bar'
47params.vueuse = 'awesome'
48// url updated to `/your/route#foo=bar&vueuse=awesome`
49```
50 
51### Custom Stringify Function
52 
53You can provide a custom function to serialize URL parameters using the `stringify` option. This is useful when you need special formatting for your query string.
54 
55```js
56import { useUrlSearchParams } from '@vueuse/core'
57 
58// Custom stringify function that removes equal signs for empty values
59const params = useUrlSearchParams('history', {
60  stringify: (params) => {
61    return params.toString().replace(/=(&|$)/g, '$1')
62  }
63})
64 
65params.foo = ''
66params.bar = 'value'
67// url updated to `?foo&bar=value` instead of `?foo=&bar=value`
68```
69 
70## Type Declarations
71 
72```ts
73export type UrlParams = Record<string, string[] | string>
74export interface UseUrlSearchParamsOptions<T> extends ConfigurableWindow {
75  /**
76   * @default true
77   */
78  removeNullishValues?: boolean
79  /**
80   * @default false
81   */
82  removeFalsyValues?: boolean
83  /**
84   * @default {}
85   */
86  initialValue?: T
87  /**
88   * Write back to `window.history` automatically
89   *
90   * @default true
91   */
92  write?: boolean
93  /**
94   * Write mode for `window.history` when `write` is enabled
95   * - `replace`: replace the current history entry
96   * - `push`: push a new history entry
97   * @default 'replace'
98   */
99  writeMode?: "replace" | "push"
100  /**
101   * Custom function to serialize URL parameters
102   * When provided, this function will be used instead of the default URLSearchParams.toString()
103   * @param params The URLSearchParams object to serialize
104   * @returns The serialized query string (should not include the leading '?' or '#')
105   */
106  stringify?: (params: URLSearchParams) => string
107}
108/**
109 * Reactive URLSearchParams
110 *
111 * @see https://vueuse.org/useUrlSearchParams
112 * @param mode
113 * @param options
114 */
115export declare function useUrlSearchParams<
116  T extends Record<string, any> = UrlParams,
117>(
118  mode?: "history" | "hash" | "hash-params",
119  options?: UseUrlSearchParamsOptions<T>,
120): T
121```
122