Animation & Transition

The full framework-specific setup is in Section 3 below.

import { ThemeProvider } from "@themvora/react";

// Renders with an instant switch…
<ThemeProvider transition={false}>
  <App />
</ThemeProvider>;

// …then animates the next change, without a remount.
<ThemeProvider transition={{ duration: 600, easing: "ease-in-out" }}>
  <App />
</ThemeProvider>;

Transitions run on the properties that actually changed between themes.preset selects a curated list, or pass an exact properties array to allow only those CSS properties to animate:

transition={{ enabled: true, properties: ["color", "background-color"] }}

Pass the same transition object to your provider (or runtime). Every framework exposes it with the same shape — only the binding syntax changes.

import { ThemeProvider, ThemeScope } from "@themvora/react";

export function App() {
  return (
    <ThemeProvider
      defaultTheme="light"
      transition={{ enabled: true, preset: "smooth" }}
    >
      <YourApp />

      {/* Nested region with its own theme + transition */}
      <ThemeScope
        theme="plum-dark"
        transition={{ enabled: true, duration: 300, easing: "ease" }}
      >
        <Widget />
      </ThemeScope>
    </ThemeProvider>
  );
}

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

const runtime = createThemeRuntime({
  transition: {
    enabled: true,
    useViewTransition: true,
    duration: 300,
  },
});

To opt out and go back to plain CSS-property interpolation, pass useViewTransition: false together with the duration and easing you want — the rest of the transition options are unchanged, and the switch still animates, just without the snapshot.

The runtime's own transition engine covers anything that reads the inherited --theme-* variables. When you need to animate a target the runtime does not own — a widget that writes its own properties, a canvas host, a third-party element — use createAnimationsPlugin. It applies a CSS transition rule to one element on onBeforeThemeChange and removes it on onDestroy.

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

// The plugin applies a CSS transition to the target element before every theme
// change, so the token updates it writes animate instead of snapping.
const runtime = createThemeRuntime({
  plugins: [
    createAnimationsPlugin({
      transition: { enabled: true, duration: 300, easing: "ease-in-out" },
    }),
  ],
});

It takes two options — the transition to apply and the element to apply it to. The element defaults to document.documentElement in a browser and to null (a no-op) elsewhere, so a themed subtree has to name itself:

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

const plugin = createAnimationsPlugin({
  transition: {
    enabled: true,
    duration: 300,
    easing: "ease-in-out",
    properties: ["color", "background-color", "border-color"],
  },
  // Defaults to document.documentElement. Point it at the element the theme
  // variables are actually written to.
  element: document.querySelector<HTMLElement>("#widget") ?? document.documentElement,
});

Sometimes one switch must not animate — a first paint, a screenshot, a bulk import. suppressTransition on a store write wins over whatever the live configuration says, for that update only:

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

const runtime = createThemeRuntime({ defaultTheme: "light" });
const themes = getBuiltInThemes();
const target = themes.find((theme) => theme.name === "plum-dark") ?? runtime.store.get();

// One switch, no animation — regardless of the configured transition.
runtime.store.set(target, { suppressTransition: true });

Framework-free runtimes configure the transition with runtime.configure() and read it back from runtime.transition. The value is live: the next change uses it, and the theme already on screen is not re-applied.

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

const runtime = createThemeRuntime({ defaultTheme: "light" });

// Replaces the transition used by subsequent changes; the theme on screen is
// not re-applied.
runtime.configure({ transition: { enabled: true, duration: 600 } });

// The live options, after the update above.
const transition = runtime.transition;

Token overrides are theme changes too, so they animate on the same path — runtime.update() merges the tokens, resolves references, runs plugin transforms, then commits through the transition:

import { useThemeRuntime } from "@themvora/react";

export function LiveEditor() {
  const runtime = useThemeRuntime();

  function softenCorners() {
    // A token override is a theme change: the configured transition animates
    // the radius variables exactly like a light→dark switch.
    runtime.update({
      radius: { sm: "8px", md: "12px", lg: "16px", xl: "20px" },
    });
  }

  return <button onClick={softenCorners}>Soften all corners</button>;
}

Theme transitions are owned by themvora. The provider's transition engine (configured via the transition prop on ThemeProvider or createThemeRuntime) interpolates the inherited --theme-color-* variables every time the active theme changes — automatically, with no extra CSS from you. This is how every theme switch on this docs site animates smoothly, and it works the same way in your app. You don't need to (and should not) add your own color transition.

If you do add one — a transition-colors utility class in Tailwind, or a plain transition: background-color 0.3s in native CSS — that element re-eases the same value again, on top of themvora's own interpolation. The result is a double-eased, laggy switch. Leave color transitions to the library, in both Tailwind and hand-written CSS.

/* ── Tailwind ─────────────────────────────────────────────────────── */
/* ✗ DON'T — animating theme tokens via Tailwind utility classes     */
.btn {
  @apply transition-colors;            /* ← re-eases theme colors → lag */
}
.card {
  @apply transition-all;               /* ← catches managed properties too */
}

/* ✓ DO — animate non-theme properties with Tailwind                  */
.btn {
  @apply transition-transform duration-200;
}
.btn:hover {
  @apply -translate-y-0.5;             /* hover lift — fine */
}

/* ── Native CSS ───────────────────────────────────────────────────── */
/* ✗ DON'T — color transition on themed elements                      */
button {
  transition: background-color 0.3s;   /* ← re-eases inherited var → lag */
}
* {
  transition: color 0.2s, background-color 0.2s; /* ← catches everything */
}

/* ✓ DO — animate properties the theme doesn't manage                 */
.toast {
  transition: opacity 0.2s ease, transform 0.2s ease;
}
.card {
  transition: box-shadow 0.2s ease, transform 0.2s ease;
}