Persistence

Remember the user's choice

Themvora remembers which theme the user picked so the next visit starts on the right one. Persistence is opt-in, pluggable, and designed to work alongside — not replace — cross-tab sync.

Prerequisites

Core Package

@themvora/core

Runtime

Theme runtime initialized with createThemeRuntime

Knowledge

Basic understanding of theme selection (mode + family)

1How persistence works

The default behavior stores only the user's selection (mode + family), not the full theme definition.

When a persistence adapter is present, the runtime reads the saved state on initialization and writes every subsequent user choice. Only the selection metadata is stored — the actual theme tokens stay in your bundle and are resolved at runtime.

core — default persistence with the plugin

TS / JS

import { createPersistencePlugin } from "@themvora/core";

// The persistence plugin writes the full selection state
// (mode + family) to localStorage under "theme-selection".
const persistence = createPersistencePlugin();

const runtime = createThemeRuntime({
  defaultTheme: "light",
  plugins: [persistence],
});

// On startup the plugin reads the saved state — if a returning
// user picked "dark" + "corporate" last visit, the runtime
// already resolves to that theme before the first paint.

Server-side rendering |Persistence adapters are null on the server — no localStorage access during SSR. The default initial theme resolves first, then the client-side adapter takes over.

2Storage keys

Customize the key under which the selection is stored to avoid collisions on shared origins.

By default the plugin uses theme-selection as the storage key. If multiple Themvora apps run on the same origin, pass a unique key to each one.

runtime — custom storage key

TS / JS

// Pass a custom key to avoid collisions with other
// apps on the same origin.
const runtime = createThemeRuntime({
  plugins: [createPersistencePlugin({ key: "my-app-theme" })],
});

3Custom adapters

Any object that implements ThemeSelectionPersistenceAdapter can be plugged in.

The ThemeSelectionPersistenceAdapter interface is four methods: get, set, remove, and subscribe. Implement them against any storage backend.

sessionStorage — tab-scoped, cleared on close

custom — sessionStorage adapter

import type { ThemeSelectionPersistenceAdapter } from "@themvora/core";

function createSessionStoragePersistence(
  key = "theme-selection",
): ThemeSelectionPersistenceAdapter {
  return {
    get() {
      const raw = sessionStorage.getItem(key);
      if (!raw) return null;
      try {
        return JSON.parse(raw) as ThemeSelectionState;
      } catch {
        return null;
      }
    },

    set(value) {
      sessionStorage.setItem(key, JSON.stringify(value));
    },

    remove() {
      sessionStorage.removeItem(key);
    },

    subscribe(listener) {
      // sessionStorage doesn't fire cross-tab storage events,
      // but we still implement the interface for consistency.
      return () => {};
    },
  };
}

Cookies — survives incognito, works server-side

custom — cookie adapter

import type { ThemeSelectionPersistenceAdapter } from "@themvora/core";

function parseCookies(header: string): Record<string, string> {
  return Object.fromEntries(
    header.split(";").map((c) => {
      const [k, ...v] = c.trim().split("=");
      return [k, decodeURIComponent(v.join("="))];
    }),
  );
}

function createCookiePersistence(
  name = "theme-selection",
): ThemeSelectionPersistenceAdapter {
  return {
    get() {
      const cookies = parseCookies(document.cookie);
      const raw = cookies[name];
      if (!raw) return null;
      try {
        return JSON.parse(raw) as ThemeSelectionState;
      } catch {
        return null;
      }
    },

    set(value) {
      document.cookie = `${name}=${encodeURIComponent(JSON.stringify(value))}; path=/; max-age=31536000; SameSite=Lax`;
    },

    remove() {
      document.cookie = `${name}=; path=/; max-age=0`;
    },

    subscribe(listener) {
      return () => {};
    },
  };
}

URL hash — shareable, bookmarkable

custom — URL hash adapter

import type { ThemeSelectionPersistenceAdapter } from "@themvora/core";

// Persist the theme in the URL hash so links share the state.
function createUrlHashPersistence(): ThemeSelectionPersistenceAdapter {
  return {
    get() {
      const hash = window.location.hash.slice(1);
      if (!hash) return null;
      const params = new URLSearchParams(hash);
      const mode = params.get("mode");
      const family = params.get("family");
      if (
        (mode === "light" || mode === "dark" || mode === "system") &&
        family
      ) {
        return { mode, family };
      }
      return null;
    },

    set(value) {
      const params = new URLSearchParams({
        mode: value.mode,
        family: value.family,
      });
      window.location.hash = params.toString();
    },

    remove() {
      history.replaceState(null, "", window.location.pathname);
    },

    subscribe(listener) {
      const handler = () => listener(null); // re-read on popstate
      window.addEventListener("popstate", handler);
      return () => window.removeEventListener("popstate", handler);
    },
  };
}

4Server-side persistence

Use HTTP cookies to persist selection across environments where localStorage is unavailable.

In Next.js and other server-rendered frameworks, the initial render has no access to localStorage. Writing the selection to a cookie lets the server read it, apply the correct theme on the first paint, and pass it to the client runtime.

next.js — cookie-based server-side persistence

// app/providers.tsx — client component
"use client";

import { useEffect, useState } from "react";
import { ThemeProvider } from "@themvora/react";
import type { ThemeSelectionState } from "@themvora/core";

export function Providers({ children }: { children: React.ReactNode }) {
  const [selection, setSelection] = useState<ThemeSelectionState | null>(null);

  useEffect(() => {
    // Read the cookie on mount — no localStorage involved.
    const cookie = document.cookie
      .split("; ")
      .find((c) => c.startsWith("theme-selection="));

    if (cookie) {
      try {
        setSelection(JSON.parse(decodeURIComponent(cookie.split("=")[1])));
      } catch {}
    }
  }, []);

  return (
    <ThemeProvider
      defaultTheme="light"
      initialMode={selection?.mode}
      initialFamily={selection?.family}
    >
      {children}
    </ThemeProvider>
  );
}

// app/actions.ts — server action
"use server";

import { cookies } from "next/headers";

export async function saveThemeSelection(state: ThemeSelectionState) {
  const cookieStore = await cookies();
  cookieStore.set("theme-selection", JSON.stringify(state), {
    path: "/",
    maxAge: 60 * 60 * 24 * 365,
    sameSite: "lax",
  });
}

Zero-flash on return visits |The cookie is read server-side during SSR, so the page renders with the correct theme from the very first byte — no client-side flash.

5Disabling persistence

Pass null to the persistence option or omit the plugin entirely.

Some apps treat every visit as fresh — kiosk mode, demos, or situations where the default theme is always correct. Disable persistence by passing null to the runtime.

core — disabling persistence

TS / JS

const runtime = createThemeRuntime({
  defaultTheme: "light",
  // Pass null explicitly to disable persistence.
  persistence: null,

  // If you are using the plugin instead of the raw option,
  // simply omit it or pass an empty array.
  plugins: [],
});

// The runtime starts fresh every page load — no localStorage
// reads, no writes on theme change.

6Persistence vs. sync

Persistence and broadcast solve different problems — they are complementary, not competing.

Persistence remembers the user's choice across visits. Sync (broadcast) propagates changes across open tabs in real-time. Use both together — they don't conflict. See the multi-window sync guide for details.

persistence vs. broadcast

TS / JS

import {
  createThemeRuntime,
  createThemeSelectionBroadcast,
  createPersistencePlugin,
} from "@themvora/core";

const runtime = createThemeRuntime({
  defaultTheme: "light",

  // Persistence: survives page reloads, writes to storage,
  // read once on init.
  plugins: [createPersistencePlugin()],

  // Broadcast: syncs across tabs in real-time, no storage
  // writes — messages travel through BroadcastChannel.
  broadcast: createThemeSelectionBroadcast(),
});

// Tab A picks "dark" + "ocean" at 2:00 PM.
// Tab B (already open) receives the broadcast → switches instantly.
//
// User closes both tabs, comes back tomorrow.
// Tab C opens → reads localStorage → lands on "dark" + "ocean".

Next steps

Enable cross-tab sync

Sync theme changes across browser tabs in real-time with BroadcastChannel

→

Build custom adapters

Create custom persistence adapters for databases, IndexedDB, or server state

→

Zero-flash SSR setup

Combine persistence with SSR for instant correct-theme rendering

→

Remember the user's choice

Themvora remembers which theme the user picked so the next visit starts on the right one. Persistence is opt-in, pluggable, and designed to work alongside — not replace — cross-tab sync.

Prerequisites

Core Package

@themvora/core

Runtime

Theme runtime initialized with createThemeRuntime

Knowledge

Basic understanding of theme selection (mode + family)

1How persistence works

The default behavior stores only the user's selection (mode + family), not the full theme definition.

core — default persistence with the plugin

TS / JS

import { createPersistencePlugin } from "@themvora/core";

// The persistence plugin writes the full selection state
// (mode + family) to localStorage under "theme-selection".
const persistence = createPersistencePlugin();

const runtime = createThemeRuntime({
  defaultTheme: "light",
  plugins: [persistence],
});

// On startup the plugin reads the saved state — if a returning
// user picked "dark" + "corporate" last visit, the runtime
// already resolves to that theme before the first paint.

Server-side rendering |Persistence adapters are null on the server — no localStorage access during SSR. The default initial theme resolves first, then the client-side adapter takes over.

2Storage keys

Customize the key under which the selection is stored to avoid collisions on shared origins.

By default the plugin uses theme-selection as the storage key. If multiple Themvora apps run on the same origin, pass a unique key to each one.

runtime — custom storage key

TS / JS

// Pass a custom key to avoid collisions with other
// apps on the same origin.
const runtime = createThemeRuntime({
  plugins: [createPersistencePlugin({ key: "my-app-theme" })],
});

3Custom adapters

Any object that implements ThemeSelectionPersistenceAdapter can be plugged in.

The ThemeSelectionPersistenceAdapter interface is four methods: get, set, remove, and subscribe. Implement them against any storage backend.

sessionStorage — tab-scoped, cleared on close

custom — sessionStorage adapter

import type { ThemeSelectionPersistenceAdapter } from "@themvora/core";

function createSessionStoragePersistence(
  key = "theme-selection",
): ThemeSelectionPersistenceAdapter {
  return {
    get() {
      const raw = sessionStorage.getItem(key);
      if (!raw) return null;
      try {
        return JSON.parse(raw) as ThemeSelectionState;
      } catch {
        return null;
      }
    },

    set(value) {
      sessionStorage.setItem(key, JSON.stringify(value));
    },

    remove() {
      sessionStorage.removeItem(key);
    },

    subscribe(listener) {
      // sessionStorage doesn't fire cross-tab storage events,
      // but we still implement the interface for consistency.
      return () => {};
    },
  };
}

Cookies — survives incognito, works server-side

custom — cookie adapter

import type { ThemeSelectionPersistenceAdapter } from "@themvora/core";

function parseCookies(header: string): Record<string, string> {
  return Object.fromEntries(
    header.split(";").map((c) => {
      const [k, ...v] = c.trim().split("=");
      return [k, decodeURIComponent(v.join("="))];
    }),
  );
}

function createCookiePersistence(
  name = "theme-selection",
): ThemeSelectionPersistenceAdapter {
  return {
    get() {
      const cookies = parseCookies(document.cookie);
      const raw = cookies[name];
      if (!raw) return null;
      try {
        return JSON.parse(raw) as ThemeSelectionState;
      } catch {
        return null;
      }
    },

    set(value) {
      document.cookie = `${name}=${encodeURIComponent(JSON.stringify(value))}; path=/; max-age=31536000; SameSite=Lax`;
    },

    remove() {
      document.cookie = `${name}=; path=/; max-age=0`;
    },

    subscribe(listener) {
      return () => {};
    },
  };
}

URL hash — shareable, bookmarkable

custom — URL hash adapter

import type { ThemeSelectionPersistenceAdapter } from "@themvora/core";

// Persist the theme in the URL hash so links share the state.
function createUrlHashPersistence(): ThemeSelectionPersistenceAdapter {
  return {
    get() {
      const hash = window.location.hash.slice(1);
      if (!hash) return null;
      const params = new URLSearchParams(hash);
      const mode = params.get("mode");
      const family = params.get("family");
      if (
        (mode === "light" || mode === "dark" || mode === "system") &&
        family
      ) {
        return { mode, family };
      }
      return null;
    },

    set(value) {
      const params = new URLSearchParams({
        mode: value.mode,
        family: value.family,
      });
      window.location.hash = params.toString();
    },

    remove() {
      history.replaceState(null, "", window.location.pathname);
    },

    subscribe(listener) {
      const handler = () => listener(null); // re-read on popstate
      window.addEventListener("popstate", handler);
      return () => window.removeEventListener("popstate", handler);
    },
  };
}

4Server-side persistence

Use HTTP cookies to persist selection across environments where localStorage is unavailable.

next.js — cookie-based server-side persistence

// app/providers.tsx — client component
"use client";

import { useEffect, useState } from "react";
import { ThemeProvider } from "@themvora/react";
import type { ThemeSelectionState } from "@themvora/core";

export function Providers({ children }: { children: React.ReactNode }) {
  const [selection, setSelection] = useState<ThemeSelectionState | null>(null);

  useEffect(() => {
    // Read the cookie on mount — no localStorage involved.
    const cookie = document.cookie
      .split("; ")
      .find((c) => c.startsWith("theme-selection="));

    if (cookie) {
      try {
        setSelection(JSON.parse(decodeURIComponent(cookie.split("=")[1])));
      } catch {}
    }
  }, []);

  return (
    <ThemeProvider
      defaultTheme="light"
      initialMode={selection?.mode}
      initialFamily={selection?.family}
    >
      {children}
    </ThemeProvider>
  );
}

// app/actions.ts — server action
"use server";

import { cookies } from "next/headers";

export async function saveThemeSelection(state: ThemeSelectionState) {
  const cookieStore = await cookies();
  cookieStore.set("theme-selection", JSON.stringify(state), {
    path: "/",
    maxAge: 60 * 60 * 24 * 365,
    sameSite: "lax",
  });
}

Zero-flash on return visits |The cookie is read server-side during SSR, so the page renders with the correct theme from the very first byte — no client-side flash.

5Disabling persistence

Pass null to the persistence option or omit the plugin entirely.

Some apps treat every visit as fresh — kiosk mode, demos, or situations where the default theme is always correct. Disable persistence by passing null to the runtime.

core — disabling persistence

TS / JS

const runtime = createThemeRuntime({
  defaultTheme: "light",
  // Pass null explicitly to disable persistence.
  persistence: null,

  // If you are using the plugin instead of the raw option,
  // simply omit it or pass an empty array.
  plugins: [],
});

// The runtime starts fresh every page load — no localStorage
// reads, no writes on theme change.

6Persistence vs. sync

Persistence and broadcast solve different problems — they are complementary, not competing.

persistence vs. broadcast

TS / JS

import {
  createThemeRuntime,
  createThemeSelectionBroadcast,
  createPersistencePlugin,
} from "@themvora/core";

const runtime = createThemeRuntime({
  defaultTheme: "light",

  // Persistence: survives page reloads, writes to storage,
  // read once on init.
  plugins: [createPersistencePlugin()],

  // Broadcast: syncs across tabs in real-time, no storage
  // writes — messages travel through BroadcastChannel.
  broadcast: createThemeSelectionBroadcast(),
});

// Tab A picks "dark" + "ocean" at 2:00 PM.
// Tab B (already open) receives the broadcast → switches instantly.
//
// User closes both tabs, comes back tomorrow.
// Tab C opens → reads localStorage → lands on "dark" + "ocean".