useStorage | VueUse

useStorage
​
Category
State
Export Size
1.99 kB
Last Changed
3 weeks ago
Related
useColorMode
useDark
useLocalStorage
useSessionStorage
useStorageAsync

Reactive LocalStorage/SessionStorage

Demo
​

source

name: 'Banana'
color: 'Yellow'
size: 'Medium'
count: 0

Usage
​

TIP

When using with Nuxt 3, this functions will NOT be auto imported in favor of Nitro's built-in useStorage(). Use explicit import if you want to use the function from VueUse.

js
import { useStorage } from '@vueuse/core'

// bind object
const state = useStorage('my-store', { hello: 'hi', greeting: 'Hello' })

// bind boolean
const flag = useStorage('my-flag', true) // returns Ref<boolean>

// bind number
const count = useStorage('my-count', 0) // returns Ref<number>

// bind string with SessionStorage
const id = useStorage('my-id', 'some-string-id', sessionStorage) // returns Ref<string>

// delete data from storage
state.value = null
Merge Defaults
​

By 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.

ts
localStorage.setItem('my-store', '{"hello": "hello"}')

const state = useStorage('my-store', { hello: 'hi', greeting: 'hello' }, localStorage)

console.log(state.value.greeting) // undefined, since the value is not presented in storage

To solve that, you can enable mergeDefaults option.

TypeScript
ts
localStorage.setItem('my-store', '{"hello": "nihao"}')
const state = useStorage(
  'my-store',
  { hello: 'hi', greeting: 'hello' },
  localStorage,
  { mergeDefaults: true }, // <--
)
console.log(state.value.hello) // 'nihao', from storage
console.log(state.value.greeting) // 'hello', from merged default value

When 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:

TypeScript
ts
const state = useStorage(
  'my-store',
  { hello: 'hi', greeting: 'hello' },
  localStorage,
  {
    mergeDefaults: (storageValue, defaults) =>
      deepMerge(defaults, storageValue),
  }, // <--
)
Custom Serialization
​

By 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.

You can also provide your own serialization function to useStorage

TypeScript
ts
import { useStorage } from '@vueuse/core'
useStorage('key', {}, undefined, {
  serializer: {
    read: (v: any) => (v ? JSON.parse(v) : null),
    write: (v: any) => JSON.stringify(v),
  },
})

Please 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.

ts
import { StorageSerializers, useStorage } from '@vueuse/core'

const objectLike = useStorage('key', null, undefined, { serializer: StorageSerializers.object })
objectLike.value = { foo: 'bar' }
Source
​

Source • Demo • Docs

Contributors
​
Anthony Fu
sun0day
Jelf
Jeffrey Li
Eduardo San Martin Morote
丶远方
Daniel Maixner
chenglu
David Ma
Daniel Mittereder
Clément Ollivier
James Garbutt
Yury Rudey
Puru Vijay
webfansplz
spking11
Maurici Abad Gutierrez
Guillaume Chau
Denis Blazhkun
Andreas Weber
Le Minh Tri
Jamie Warburton
Shinigami
Sasan Farrokh
Pig Fang
wheat
Alex Kozack
Nurettin Kaya
Pine
Antério Vieira
Ivan Demchuk
Changelog
​
v10.6.0 on 11/9/2023
dc6f2 - feat: add waitOnMounted option for SSR (#3504)
b6d2b - fix: fix defaults not unwrapped (#3534)
v10.4.0 on 8/25/2023
6fabe - fix: read object only when it's serialized differently (#2782) (#3091)
v10.0.0-beta.5 on 4/13/2023
cb644 - refactor!: remove isFunction and isString utils
v10.0.0-beta.4 on 4/13/2023
4d757 - feat(types)!: rename MaybeComputedRef to MaybeRefOrGetter
0a72b - feat(toValue): rename resolveUnref to toValue
v9.13.0 on 2/18/2023
c6185 - fix: emit a custom event to support custom storage areas (#2630)
v9.8.2 on 12/20/2022
800f7 - fix: sync within page, close #1595
v9.8.1 on 12/20/2022
c3851 - fix: resume the watch after setting the value, fix loop updates
v9.3.1 on 10/17/2022
a06b7 - fix: fixed data desynchronization in case of clearing storage (#2221)
v9.0.0-beta.2 on 7/24/2022
26aae - feat: mergeDefaults option (#1957)
v8.9.3 on 7/14/2022
499f6 - fix!: rename type StorageOptions to UseStorageOptions (#1867)
v8.9.1 on 7/8/2022
a9ccc - feat(all): use MaybeComputedRef (#1768)