useStorage

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>