1---
2category: State
3related: useLocalStorage, useSessionStorage, useStorageAsync
4---
5 
6# useStorage
7 
8Create a reactive ref that can be used to access & modify [LocalStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) or [SessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage).
9 
10Uses localStorage by default, other storage sources be specified via third argument.
11 
12## Usage
13 
14::: tip
15When using with Nuxt 3, this function will **NOT** be auto imported in favor of Nitro's built-in [`useStorage()`](https://nitro.unjs.io/guide/storage). Use explicit import if you want to use the function from VueUse.
16:::
17 
18```ts
19import { useStorage } from '@vueuse/core'
20 
21// bind object
22const state = useStorage('my-store', { hello: 'hi', greeting: 'Hello' })
23 
24// bind boolean
25const flag = useStorage('my-flag', true) // returns Ref<boolean>
26 
27// bind number
28const count = useStorage('my-count', 0) // returns Ref<number>
29 
30// bind string with SessionStorage
31const id = useStorage('my-id', 'some-string-id', sessionStorage) // returns Ref<string>
32 
33// delete data from storage
34state.value = null
35```
36 
37## Merge Defaults
38 
39By default, `useStorage` will use the value from storage if it is present and ignores the default value. Be aware that when you are adding more properties to the default value, the key might be `undefined` if client's storage does not have that key.
40 
41```ts
42import { useStorage } from '@vueuse/core'
43// ---cut---
44localStorage.setItem('my-store', '{"hello": "hello"}')
45 
46const state = useStorage('my-store', { hello: 'hi', greeting: 'hello' }, localStorage)
47 
48console.log(state.value.greeting) // undefined, since the value is not presented in storage
49```
50 
51To solve that, you can enable `mergeDefaults` option.
52 
53```ts
54import { useStorage } from '@vueuse/core'
55// ---cut---
56localStorage.setItem('my-store', '{"hello": "nihao"}')
57 
58const state = useStorage(
59  'my-store',
60  { hello: 'hi', greeting: 'hello' },
61  localStorage,
62  { mergeDefaults: true } // <--
63)
64 
65console.log(state.value.hello) // 'nihao', from storage
66console.log(state.value.greeting) // 'hello', from merged default value
67```
68 
69When setting it to true, it will perform a **shallow merge** for objects. You can pass a function to perform custom merge (e.g. deep merge), for example:
70 
71```ts
72import { useStorage } from '@vueuse/core'
73// ---cut---
74const state = useStorage(
75  'my-store',
76  { hello: 'hi', greeting: 'hello' },
77  localStorage,
78  { mergeDefaults: (storageValue, defaults) => deepMerge(defaults, storageValue) } // <--
79)
80```
81 
82## Custom Serialization
83 
84By default, `useStorage` will smartly use the corresponding serializer based on the data type of provided default value. For example, `JSON.stringify` / `JSON.parse` will be used for objects, `Number.toString` / `parseFloat` for numbers, etc.
85 
86You can also provide your own serialization function to `useStorage`:
87 
88```ts
89import { useStorage } from '@vueuse/core'
90 
91useStorage(
92  'key',
93  {},
94  undefined,
95  {
96    serializer: {
97      read: (v: any) => v ? JSON.parse(v) : null,
98      write: (v: any) => JSON.stringify(v),
99    },
100  },
101)
102```
103 
104Please note when you provide `null` as the default value, `useStorage` can't assume the data type from it. In this case, you can provide a custom serializer or reuse the built-in ones explicitly.
105 
106```ts
107import { StorageSerializers, useStorage } from '@vueuse/core'
108 
109const objectLike = useStorage('key', null, undefined, { serializer: StorageSerializers.object })
110objectLike.value = { foo: 'bar' }
111```
112 
113### Built-in Serializers
114 
115The following serializers are available via `StorageSerializers`:
116 
117| Type      | Description                           |
118| --------- | ------------------------------------- |
119| `string`  | Plain string                          |
120| `number`  | Number (via `parseFloat`)             |
121| `boolean` | Boolean                               |
122| `object`  | JSON object/array                     |
123| `map`     | JavaScript `Map`                      |
124| `set`     | JavaScript `Set`                      |
125| `date`    | JavaScript `Date` (via `toISOString`) |
126| `any`     | Raw string passthrough                |
127 
128```ts
129import { StorageSerializers, useStorage } from '@vueuse/core'
130 
131const myMap = useStorage('my-map', new Map(), undefined, {
132  serializer: StorageSerializers.map,
133})
134```
135 
136## Options
137 
138```ts
139useStorage('key', defaults, storage, {
140  // Watch for deep changes in objects/arrays (default: true)
141  deep: true,
142  // Sync across tabs via storage events (default: true)
143  listenToStorageChanges: true,
144  // Write default value to storage if not present (default: true)
145  writeDefaults: true,
146  // Use shallowRef instead of ref (default: false)
147  shallow: false,
148  // Initialize only after component is mounted (default: false)
149  initOnMounted: false,
150  // Custom error handler (default: console.error)
151  onError: e => console.error(e),
152  // Watch flush timing (default: 'pre')
153  flush: 'pre',
154})
155```
156 
157## Reactive Key
158 
159The storage key can be a ref or getter, and the data will be updated when the key changes:
160 
161```ts
162import { useStorage } from '@vueuse/core'
163 
164const userId = ref('user-1')
165const userData = useStorage(
166  () => `user-data-${userId.value}`,
167  { name: '' },
168)
169 
170// Changing the key will read from the new storage location
171userId.value = 'user-2'
172```
173 
174## Type Declarations
175 
176```ts
177export interface Serializer<T> {
178  read: (raw: string) => T
179  write: (value: T) => string
180}
181export interface SerializerAsync<T> {
182  read: (raw: string) => Awaitable<T>
183  write: (value: T) => Awaitable<string>
184}
185export declare const StorageSerializers: Record<
186  "boolean" | "object" | "number" | "any" | "string" | "map" | "set" | "date",
187  Serializer<any>
188>
189export declare const customStorageEventName = "vueuse-storage"
190export interface StorageEventLike {
191  storageArea: StorageLike | null
192  key: StorageEvent["key"]
193  oldValue: StorageEvent["oldValue"]
194  newValue: StorageEvent["newValue"]
195}
196export interface UseStorageOptions<T>
197  extends ConfigurableEventFilter, ConfigurableWindow, ConfigurableFlush {
198  /**
199   * Watch for deep changes
200   *
201   * @default true
202   */
203  deep?: boolean
204  /**
205   * Listen to storage changes, useful for multiple tabs application
206   *
207   * @default true
208   */
209  listenToStorageChanges?: boolean
210  /**
211   * Write the default value to the storage when it does not exist
212   *
213   * @default true
214   */
215  writeDefaults?: boolean
216  /**
217   * Merge the default value with the value read from the storage.
218   *
219   * When setting it to true, it will perform a **shallow merge** for objects.
220   * You can pass a function to perform custom merge (e.g. deep merge), for example:
221   *
222   * @default false
223   */
224  mergeDefaults?: boolean | ((storageValue: T, defaults: T) => T)
225  /**
226   * Custom data serialization
227   */
228  serializer?: Serializer<T>
229  /**
230   * On error callback
231   *
232   * Default log error to `console.error`
233   */
234  onError?: (error: unknown) => void
235  /**
236   * Use shallow ref as reference
237   *
238   * @default false
239   */
240  shallow?: boolean
241  /**
242   * Wait for the component to be mounted before reading the storage.
243   *
244   * @default false
245   */
246  initOnMounted?: boolean
247}
248export declare function useStorage(
249  key: MaybeRefOrGetter<string>,
250  defaults: MaybeRefOrGetter<string>,
251  storage?: StorageLike,
252  options?: UseStorageOptions<string>,
253): RemovableRef<string>
254export declare function useStorage(
255  key: MaybeRefOrGetter<string>,
256  defaults: MaybeRefOrGetter<boolean>,
257  storage?: StorageLike,
258  options?: UseStorageOptions<boolean>,
259): RemovableRef<boolean>
260export declare function useStorage(
261  key: MaybeRefOrGetter<string>,
262  defaults: MaybeRefOrGetter<number>,
263  storage?: StorageLike,
264  options?: UseStorageOptions<number>,
265): RemovableRef<number>
266export declare function useStorage<T>(
267  key: MaybeRefOrGetter<string>,
268  defaults: MaybeRefOrGetter<T>,
269  storage?: StorageLike,
270  options?: UseStorageOptions<T>,
271): RemovableRef<T>
272export declare function useStorage<T = unknown>(
273  key: MaybeRefOrGetter<string>,
274  defaults: MaybeRefOrGetter<null>,
275  storage?: StorageLike,
276  options?: UseStorageOptions<T>,
277): RemovableRef<T>
278```
279