category | related |
---|---|
State |
useLocalStorage, useSessionStorage, useStorageAsync |
Reactive LocalStorage/SessionStorage
::: 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.
:::
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
By default, useStorage
will use the value from storage if it presents and ignores the default value. Be aware that when you adding more properties to the default value, the key might be undefined if client's storage does not have that key.
localStorage.setItem('my-store', '{"hello": "hello"}')
const state = useStorage('my-store', { hello: 'hi', greeting: 'hello' }, localStorage)
console.log(state.greeting) // undefined, since the value is not presented in storage
To solve that, you can enable mergeDefaults
option.
localStorage.setItem('my-store', '{"hello": "nihao"}')
const state = useStorage(
'my-store',
{ hello: 'hi', greeting: 'hello' },
localStorage,
{ mergeDefaults: true } // <--
)
console.log(state.hello) // 'nihao', from storage
console.log(state.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:
const state = useStorage(
'my-store',
{ hello: 'hi', greeting: 'hello' },
localStorage,
{ mergeDefaults: (storageValue, defaults) => deepMerge(defaults, storageValue) } // <--
)
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
:
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.
import { StorageSerializers, useStorage } from '@vueuse/core'
const objectLike = useStorage('key', null, undefined, { serializer: StorageSerializers.object })
objectLike.value = { foo: 'bar' }