useStorage

Reactive storage binding powered by Legend-State’s persist & sync engine.

Creates an Observable<T> that automatically persists to a storage backend. The plugin option is required — use useLocalStorage or useSessionStorage from @usels/web for convenience wrappers with pre-configured plugins.

Demo

count0

+1Reset

Usage

import { useStorage } from "@usels/web";
import { ObservablePersistLocalStorage } from "@legendapp/state/persist-plugins/local-storage";

function Component() {
  const { data$: count$, isPersistLoaded$ } = useStorage("count", 0, {
    plugin: ObservablePersistLocalStorage,
  });

  return (
    <>
      {isPersistLoaded$.get() ? (
        <button onClick={() => count$.set(count$.get() + 1)}>Count: {count$.get()}</button>
      ) : (
        <div>Loading...</div>
      )}
    </>
  );
}

Async plugin (IndexedDB)

import { useStorage } from "@usels/web";
import { ObservablePersistIndexedDB } from "@legendapp/state/persist-plugins/indexeddb";

function Component() {
  const { data$, isPersistLoaded$, error$ } = useStorage(
    "app-data",
    { items: [] },
    {
      plugin: ObservablePersistIndexedDB,
    }
  );

  return (
    <div>
      {error$.get() ? (
        <div>Error: {error$.get()?.message}</div>
      ) : isPersistLoaded$.get() ? (
        <div>{data$.items.get().length} items</div>
      ) : (
        <div>Loading storage...</div>
      )}
    </div>
  );
}

Type Declarations

export interface UseStorageOptions {
    plugin: PersistOptions["plugin"];
    transform?: PersistOptions["transform"];
    retrySync?: PersistOptions["retrySync"];
    readonly?: PersistOptions["readonly"];
    options?: PersistOptions["options"];
}
export interface UseStorageReturn<T> {
    data$: Observable<T>;
    isLoaded$: ReadonlyObservable<boolean>;
    isPersistLoaded$: ReadonlyObservable<boolean>;
    error$: ReadonlyObservable<Error | undefined>;
}
export declare function useStorage<T>(key: string, defaults: T, options: UseStorageOptions): UseStorageReturn<T>;

Source

View on GitHub

Contributors

• tigerwest

Changelog

• a7392ab 2026-03-06 - feat(core,browser): add sync strategy hooks (tigerwest)