use-storage

Typed built-in serializers, usable directly as the serializer option.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { inferStorageSerializerKind, storageSerializers, useLocalStorage, useSessionStorage, useStorage } from "@vizejs/composable/use-storage";

Try it

Remember reading progress

Persist a selected guide section in the current browser and provide an explicit way to remove the saved choice.

Open the interactive example

What to observe: Choose Components, then reload this page to keep that choice. Reset reading progress removes the saved key and restores Getting started, including after another reload.

state is writable; supported and error describe the real localStorage capability. A validator accepts only the three guide sections. writeDefaults: false leaves an absent or removed key absent. SSR uses Getting started without accessing storage; the default post-flush initial read preserves hydration before restoring a saved choice. When storage is unavailable, choices still update in this tab but reload returns to the default. Storage can fail in restricted browsers. The key belongs to this example's origin; an embedded frame may have a different origin or storage policy from its parent. Watches and storage listeners follow the component scope.

Compare the initial and interacted states

When browser storage is unavailable

Choices still change in this tab. Reloading restores Getting started because the browser cannot save the choice. This capture uses actual Chromium with localStorage disabled.

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { computed, useId } from "vue";
import { useStorage } from "@vizejs/composable/use-storage";

type GuideSection = "getting-started" | "components" | "publishing";

const sectionId = useId();
const {
  state: section,
  supported,
  error,
  remove,
} = useStorage<GuideSection>("vize:docs:reading-progress", "getting-started", {
  writeDefaults: false,
  validate: (candidate): candidate is GuideSection =>
    candidate === "getting-started" || candidate === "components" || candidate === "publishing",
});
const sectionTitle = computed(() => {
  if (section.value === "components") return "Components";
  if (section.value === "publishing") return "Publishing";
  return "Getting started";
});
</script>

<template>
  <div class="composable-example">
    <label :for="sectionId">Guide section</label>
    <select :id="sectionId" v-model="section" :aria-describedby="`${sectionId}-help`">
      <option value="getting-started">Getting started</option>
      <option value="components">Components</option>
      <option value="publishing">Publishing</option>
    </select>
    <p :id="`${sectionId}-help`">
      Choose where to resume reading, then reload this page. Available browser storage keeps your
      choice.
    </p>
    <output aria-live="polite">Resume at: {{ sectionTitle }}</output>
    <p role="status">
      {{
        error
          ? `Storage error: ${error.code}. The current section may not be saved.`
          : supported
            ? "Browser storage is available."
            : "Browser storage is unavailable; changes stay in this tab."
      }}
    </p>
    <button type="button" @click="() => remove()">Reset reading progress</button>
    <p>Reset removes the saved choice and restores Getting started.</p>
  </div>
</template>

Runtime contract

API

storageSerializers

Typed built-in serializers, usable directly as the serializer option. object round-trips JSON-compatible values; map and set store their entries as JSON arrays; date stores an ISO-8601 string.

const storageSerializers: { /** Decimal `bigint` text. */ readonly bigint: StorageSerializer<bigint>; /** `"true"` / `"false"`. */ readonly boolean: StorageSerializer<boolean>; /** ISO-8601 timestamp. */ readonly date: StorageSerializer<Date>; /** JSON array of `[key, value]` entries. */ readonly map: StorageSerializer<Map<unknown, unknown>>; /** Decimal number text. */ readonly number: StorageSerializer<number>; /** JSON text. */ readonly object: StorageSerializer<unknown>; /** JSON array of members. */ readonly set: StorageSerializer<Set<unknown>>; /** Raw string. */ readonly string: StorageSerializer<string>; }

inferStorageSerializerKind

Select the built-in serializer kind for a default value. null, arrays, and plain objects use JSON ("object"); Map, Set, and Date use their dedicated kinds; primitives use their typeof. Functions and symbols cannot be stored and fall back to "string".

function inferStorageSerializerKind(value: unknown): StorageSerializerKind

useStorage

Synchronize a typed reactive value with a Web Storage compatible backend. The serializer is inferred from defaultValue (numbers stay numbers, Map/Set/Date round-trip), and every decoded value passes the validate hook before it is accepted, so corrupted or foreign data falls back to the default instead of leaking the wrong type. Writes follow the reactive value; changes from other tabs (storage events) and from other instances in the same document using the same key are applied live. Server rendering: without a browser window no storage is touched and state holds the default. Node's global localStorage is intentionally ignored because it would be shared between requests. Inside a component initialRead defaults to "post-flush", so hydrating markup that rendered the default matches before switching to the stored value. Failures (quota, disabled storage, malformed data) never throw; they are exposed through error and onError.

function useStorage<Value>( key: MaybeRefOrGetter<string>, defaultValue: MaybeRefOrGetter<Value>, options: UseStorageOptions<Value> = {}, ): StorageControls<Value>

const { state: theme } = useStorage("theme", "light" as "light" | "dark");
theme.value = "dark"; // persisted

useLocalStorage

useStorage bound to window.localStorage by default.

function useLocalStorage<Value>( key: MaybeRefOrGetter<string>, defaultValue: MaybeRefOrGetter<Value>, options: UseStorageOptions<Value> = {}, ): StorageControls<Value>

useSessionStorage

useStorage bound to window.sessionStorage by default.

function useSessionStorage<Value>( key: MaybeRefOrGetter<string>, defaultValue: MaybeRefOrGetter<Value>, options: UseStorageOptions<Value> = {}, ): StorageControls<Value>

Types

StorageLike

Minimal synchronous key-value store compatible with the Web Storage API.

StorageSerializer

Converts one value type to and from its stored string representation.

StorageFailure

Failure observed while synchronizing a value with storage.

UseStorageOptions

Options for useStorage.

StorageControls

Reactive state and controls returned by useStorage.