Storage Backends

useIndexedDB

Promise-based key-value access to an IndexedDB object store. The store is created automatically if it does not exist.

function useIndexedDB<T>(
  dbName: string,
  storeName: string,
  onError?: (err: StorageError) => void,
  options?: UseIndexedDBOptions,
): UseIndexedDBReturn<T>

Options

indexes

IDBIndexDefinition[]

Secondary indexes to create on the store, each { name, keyPath, unique?, multiEntry? } — created once, when the store is first opened (schema changes require bumping version).

version

number · default: 1

IndexedDB database version. Bump this whenever indexes changes — IndexedDB only re-runs the upgrade (and therefore only applies new/changed indexes) when the requested version is higher than the stored one.

Methods

get

(key: IDBValidKey) => Promise<T | null>

Read a value by key.

set

(key: IDBValidKey, value: T) => Promise<void>

Write a value.

delete

(key: IDBValidKey) => Promise<void>

Remove a key.

keys

() => Promise<IDBValidKey[]>

All keys in the store.

getAll

() => Promise<T[]>

All values.

clear

() => Promise<void>

Delete everything in the store.

count

() => Promise<number>

Number of entries.

transaction

<R>(fn: (store: IDBObjectStore) => IDBRequest<R>) => Promise<R>

Raw IDB transaction, for anything the wrapper above doesn't cover.

getByIndex

(indexName: string, value: IDBValidKey) => Promise<T | null>

Read the first value whose secondary index (declared via the indexes option) matches value.

getAllByIndex

(indexName: string, value: IDBValidKey) => Promise<T[]>

Read every value whose secondary index matches value.

Example

import { useIndexedDB } from 'vue-storage-kit'

interface Person {
  id: number
  email: string
  data: ArrayBuffer
}

const idb = useIndexedDB<Person>('my-db', 'people', (err) => console.error(err), {
  indexes: [{ name: 'by-email', keyPath: 'email', unique: true }],
  version: 1,
})

await idb.set(1, { id: 1, email: 'ada@example.com', data: buffer })
const person = await idb.get(1)
console.log(await idb.count())

// Query by the secondary index instead of the primary key
const byEmail = await idb.getByIndex('by-email', 'ada@example.com')

// Raw transaction
await idb.transaction((store) => store.put({ id: 2, email: 'b@example.com', data: buffer2 }, 2))

await idb.delete(1)
await idb.clear()

useIDBRef

A reactive Ref that reads from and writes to a single IndexedDB key. Useful when you want the same reactive API as useStorage but backed by IndexedDB.

useIDBRef<T>(
  dbName: string,
  storeName: string,
  key: IDBValidKey,
  defaultValue: T,
): { value: Ref<T>; isReady: Ref<boolean>; error: Ref<StorageError | null> }

import { useIDBRef } from 'vue-storage-kit'

const { value: draft, isReady } = useIDBRef('editor-db', 'drafts', 'post-42', '')

// Once isReady.value === true, draft reflects the stored value
draft.value = 'Hello, world!' // writes back to IDB automatically

useCookie

A reactive Ref backed by document.cookie. Assigning to the ref sets the cookie. JSON serialization with Date, Map, Set support is included by default.

Imported directly from vue-storage-kit, this is client-only (SSR reads return defaultValue, since there's no document on the server). Inside a Nuxt app with the vue-storage-kit/nuxt module registered, auto-imported useCookie calls resolve to an SSR-aware version instead — same signature, but backed by the H3 request/response on the server. See Nuxt module.

useCookie<T>(name: string, options: CookieOptions<T>): Ref<T>

Options

defaultValue

T

Value returned when the cookie is absent.

expires

Date | number

Expiry as a Date or number of days.

path

string · default: '/'

Cookie path.

domain

string

Cookie domain.

secure

boolean

Add the Secure flag.

sameSite

'strict' | 'lax' | 'none'

SameSite attribute.

httpOnly

boolean

SSR only — passed to H3 setCookie; ignored by browsers, since document.cookie can never set this flag from client JS. Setting it on this base, client-only useCookie (i.e. outside the Nuxt SSR context) now triggers a dev-mode console.warn instead of failing silently — only the Nuxt module's SSR-aware useCookie replacement can actually honor it.

serializer

Serializer<T> · default: JSON

Custom serializer.

Examples

Session cookie (expires when browser closes):

const consent = useCookie('cookie-consent', { defaultValue: false })
consent.value = true

Persistent cookie — 30 days:

const locale = useCookie('locale', {
  defaultValue: 'en',
  expires: 30,
  sameSite: 'lax',
})

Nuxt SSR — same API works on server and client:

<script setup lang="ts">
// With the vue-storage-kit/nuxt module registered, this auto-import resolves
// to the SSR-aware useCookie — reads/writes via H3 on the server.
const token = useCookie('auth-token', {
  defaultValue: '',
  secure: true,
  httpOnly: true, // honored server-side via H3 setCookie
  sameSite: 'strict',
})
</script>