For application developers

Developer quick start

Start the runtime with published packages in React, Vue, or the web, then make existing components respond to a theme.

Install the packages for your framework

In a consumer project, install only published packages from npm and keep the package manager and lockfile the project already uses.

bash

# React
pnpm add @oriatheme/presets @oriatheme/runtime-dom @oriatheme/react

# Vue 3
pnpm add @oriatheme/presets @oriatheme/runtime-dom @oriatheme/vue

# Framework-free web
pnpm add @oriatheme/presets @oriatheme/runtime-dom

Restore before mount, then let the runtime take over

Run Bootstrap first to restore the last successfully saved snapshot, then start the full runtime at framework mount. It revalidates state, handles system appearance, and writes variables atomically.

React

tsx

import { createRoot } from "react-dom/client";
import { OriaThemeProvider, useOriaTheme } from "@oriatheme/react";
import { oriaPresetThemes } from "@oriatheme/presets";
import { bootstrapTheme } from "@oriatheme/runtime-dom";

bootstrapTheme({ contract: { name: "oria-standard", version: 2 } });

function Controls() {
  const { setTheme, setAppearance } = useOriaTheme();
  return <>
    <button onClick={() => setTheme("oria-ocean")}>Ocean</button>
    <button onClick={() => setAppearance("dark")}>Dark</button>
  </>;
}

createRoot(document.querySelector("#root")!).render(
  <OriaThemeProvider config={{ presets: oriaPresetThemes, defaultThemeId: "oria-default" }}>
    <Controls />
  </OriaThemeProvider>,
);

Vue

import { createApp } from "vue";
import { createOriaTheme } from "@oriatheme/vue";
import { oriaPresetThemes } from "@oriatheme/presets";
import { bootstrapTheme } from "@oriatheme/runtime-dom";
import App from "./App.vue";

bootstrapTheme({ contract: { name: "oria-standard", version: 2 } });
createApp(App)
  .use(createOriaTheme({ presets: oriaPresetThemes, defaultThemeId: "oria-default" }))
  .mount("#app");

Native web

import { oriaPresetThemes } from "@oriatheme/presets";
import { bootstrapTheme, createOriaThemeRuntime } from "@oriatheme/runtime-dom";

bootstrapTheme({ contract: { name: "oria-standard", version: 2 } });
const runtime = createOriaThemeRuntime({
  presets: oriaPresetThemes,
  defaultThemeId: "oria-default",
});
runtime.start();
runtime.setTheme("oria-ocean");
runtime.setAppearance("system");
// Call runtime.destroy() when the app is removed.

See complete integrations in the example apps

The three official examples mirror this guide — browse or clone them on GitHub.

React + Vite

React example app

Provider setup, token gallery, and an on-demand local editor.

Vue 3 + Vite

Vue example app

Plugin setup sharing the same runtime state machine.

Next.js App Router

Next.js example app

SSR default CSS, first-paint Bootstrap, and an on-demand editor.

Verify the result

html receives data-oria-theme, data-oria-mode, and the correct color-scheme.
Switching a theme updates color, radius, shadow, and the other variables together.
Persistence stores the light, dark, or system preference—never resolvedMode.

Next: style components with semantic tokens