Skip to content
On this page

useStorage

Category
Last Changed
a month ago

Reactive LocalStorage/SessionStorage

Demo

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

Usage

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

Custom Serialization

By default, useStoragewill 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),
    }
  }
})
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, useStoragecan't assume the data type from it. In this case, you can provide a custom serializer or reuse the built-in ones explicitly.

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

const objectLike = useStorage('key', null, undefined, { serializer: StorageSerializers.object })
objectLike.value = { foo: 'bar' }
import { useStorage, StorageSerializers } from '@vueuse/core'

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

Type Declarations

Show Type Declarations
export interface Serializer<T> {
  read(raw: string): T
  write(value: T): string
}
export interface SerializerAsync<T> {
  read(raw: string): Awaitable<T>
  write(value: T): Awaitable<string>
}
export declare const StorageSerializers: Record<
  "boolean" | "object" | "number" | "any" | "string" | "map" | "set",
  Serializer<any>
>
export interface StorageOptions<T>
  extends ConfigurableEventFilter,
    ConfigurableWindow,
    ConfigurableFlush {
  /**
   * Watch for deep changes
   *
   * @default true
   */
  deep?: boolean
  /**
   * Listen to storage changes, useful for multiple tabs application
   *
   * @default true
   */
  listenToStorageChanges?: boolean
  /**
   * Write the default value to the storage when it does not exist
   *
   * @default true
   */
  writeDefaults?: boolean
  /**
   * Custom data serialization
   */
  serializer?: Serializer<T>
  /**
   * On error callback
   *
   * Default log error to `console.error`
   */
  onError?: (error: unknown) => void
  /**
   * Use shallow ref as reference
   *
   * @default false
   */
  shallow?: boolean
}
export declare function useStorage(
  key: string,
  initialValue: MaybeRef<string>,
  storage?: StorageLike,
  options?: StorageOptions<string>
): RemovableRef<string>
export declare function useStorage(
  key: string,
  initialValue: MaybeRef<boolean>,
  storage?: StorageLike,
  options?: StorageOptions<boolean>
): RemovableRef<boolean>
export declare function useStorage(
  key: string,
  initialValue: MaybeRef<number>,
  storage?: StorageLike,
  options?: StorageOptions<number>
): RemovableRef<number>
export declare function useStorage<T>(
  key: string,
  initialValue: MaybeRef<T>,
  storage?: StorageLike,
  options?: StorageOptions<T>
): RemovableRef<T>
export declare function useStorage<T = unknown>(
  key: string,
  initialValue: MaybeRef<null>,
  storage?: StorageLike,
  options?: StorageOptions<T>
): RemovableRef<T>
export interface Serializer<T> {
  read(raw: string): T
  write(value: T): string
}
export interface SerializerAsync<T> {
  read(raw: string): Awaitable<T>
  write(value: T): Awaitable<string>
}
export declare const StorageSerializers: Record<
  "boolean" | "object" | "number" | "any" | "string" | "map" | "set",
  Serializer<any>
>
export interface StorageOptions<T>
  extends ConfigurableEventFilter,
    ConfigurableWindow,
    ConfigurableFlush {
  /**
   * Watch for deep changes
   *
   * @default true
   */
  deep?: boolean
  /**
   * Listen to storage changes, useful for multiple tabs application
   *
   * @default true
   */
  listenToStorageChanges?: boolean
  /**
   * Write the default value to the storage when it does not exist
   *
   * @default true
   */
  writeDefaults?: boolean
  /**
   * Custom data serialization
   */
  serializer?: Serializer<T>
  /**
   * On error callback
   *
   * Default log error to `console.error`
   */
  onError?: (error: unknown) => void
  /**
   * Use shallow ref as reference
   *
   * @default false
   */
  shallow?: boolean
}
export declare function useStorage(
  key: string,
  initialValue: MaybeRef<string>,
  storage?: StorageLike,
  options?: StorageOptions<string>
): RemovableRef<string>
export declare function useStorage(
  key: string,
  initialValue: MaybeRef<boolean>,
  storage?: StorageLike,
  options?: StorageOptions<boolean>
): RemovableRef<boolean>
export declare function useStorage(
  key: string,
  initialValue: MaybeRef<number>,
  storage?: StorageLike,
  options?: StorageOptions<number>
): RemovableRef<number>
export declare function useStorage<T>(
  key: string,
  initialValue: MaybeRef<T>,
  storage?: StorageLike,
  options?: StorageOptions<T>
): RemovableRef<T>
export declare function useStorage<T = unknown>(
  key: string,
  initialValue: MaybeRef<null>,
  storage?: StorageLike,
  options?: StorageOptions<T>
): RemovableRef<T>

Source

SourceDemoDocs

Contributors

Anthony Fu
Jeffrey Li
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

v7.5.3 on 1/5/2022
77fe0 - fix(storage): caught DOMException accessing storage (#1124)
v7.4.1 on 12/23/2021
3aa49 - feat: ssr handlers (#1060)
v7.3.0 on 12/12/2021
169b0 - feat(useStorageAsync): new function
v6.9.2 on 11/19/2021
80409 - fix: interface typos (#938)
v6.6.2 on 10/18/2021
c6435 - fix: macro task for listening to storage change
bdce1 - feat: new writeDefaults option
bc223 - feat: support Map and Set
v6.6.0 on 10/16/2021
ad5d5 - feat: support shallow ref (#805)
v6.3.3 on 9/12/2021
d6dd1 - feat: support writing null value to storage, close #452
8a9c4 - feat: support pass ref to useStorage
v6.1.0 on 9/2/2021
dee2f - fix: support TypeScript 4.4
v6.0.0-beta.2 on 8/9/2021
29032 - fix: default null values will not be stored in local storage (#642)
v6.0.0-beta.1 on 7/16/2021
8b942 - feat: new onError callback
v5.1.3 on 7/7/2021
2c8ac - feat: expose StorageSerializers, close #576
v5.1.1 on 7/6/2021
49334 - fix: read type with default null as null instead of string (#606)
v4.11.1 on 5/24/2021
e6eb5 - feat: allow custom serializer (#528)
v4.11.0 on 5/14/2021
ad309 - feat: optimize event handling logic (#505)
v4.11.1 on 5/24/2021
f4d53 - feat: allow custom serializer (#528)
v4.11.0 on 5/14/2021
e2e20 - feat: optimize event handling logic (#505)
v4.6.4 on 4/4/2021
84c43 - fix: trigger render on key removal (#414)
useStorage has loaded