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

useStorage

Value persists across page reloads via localStorage.

-1

0

+1

Reset

Usage

Hook

import { useStorage } from "@usels/web";
import { ObservablePersistLocalStorage } from "@usels/web";

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>
      )}
    </>
  );
}

Scope

import { createStorage, observable } from "@usels/web";
import { ObservablePersistLocalStorage } from "@usels/web";

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

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

Async plugin (IndexedDB)

Hook

import { useStorage } from "@usels/web";
import { ObservablePersistIndexedDB } from "@usels/web";

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>
  );
}

Scope

import { createStorage, observable } from "@usels/web";
import { ObservablePersistIndexedDB } from "@usels/web";

function Component() {
  "use scope"
  const { data$, isPersistLoaded$, error$ } = createStorage(
    "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

export { createStorage } from "./core";
export type { StorageOptions, StorageReturn } from "./core";
/**
 * Reactive storage binding powered by Legend-State's
 * [persist & sync](https://legendapp.com/open-source/state/v3/sync/persist-sync/) engine.
 *
 * Creates an `Observable<T>` that automatically persists to a storage backend.
 *
 * @param key - Storage key (maps to `persist.name`).
 * @param defaults - Initial value and type inference source.
 * @param options - Configuration options. `plugin` is required.
 * @returns `{ data$, isPersistLoaded$, error$ }`
 *
 * @example
 * ```ts
 * import { ObservablePersistLocalStorage } from "@legendapp/state/persist-plugins/local-storage";
 *
 * const { data$: count$, isPersistLoaded$ } = useStorage('count', 0, {
 *   plugin: ObservablePersistLocalStorage,
 * });
 * data$.set(42); // persisted to storage
 * data$.get();   // 42
 * ```
 */
export type UseStorage = typeof createStorage;
export declare const useStorage: UseStorage;

Source

View on GitHub