Overview

Understanding the Apsara theming system and ThemeProvider.

Apsara provides a theming system built on CSS custom properties (tokens). Tokens are semantic variables that automatically resolve to appropriate values based on the active theme—so your UI adapts seamlessly when users switch between light and dark modes or when you change accent colors, without any code changes.

Installation

Wrap your application with the ThemeProvider component:

1import { ThemeProvider } from "@raystack/apsara";
2

3function App() {
4  return (
5    <ThemeProvider defaultTheme="system">
6      <YourApp />
7    </ThemeProvider>
8  );
9}

Customization

The ThemeProvider accepts props to control the visual identity of your application. Combine style variants with accentColor and grayColor to create distinct aesthetics—from sharp and technical to warm and editorial. The defaultTheme prop controls light/dark mode, with system respecting the user's OS preference.

1// Clean, technical aesthetic
2<ThemeProvider style="modern" accentColor="indigo" grayColor="slate">
3

4// Warm, editorial feel
5<ThemeProvider style="traditional" accentColor="orange" grayColor="mauve">
6

7// Vibrant and fresh
8<ThemeProvider style="modern" accentColor="mint" grayColor="gray">

See API Reference for all available props and options.

Tokens

Tokens follow two naming patterns:

Semantic tokens — for context-aware values that adapt to theme:

1--rs-{category}-{property}-{variant}-{state}

Scale tokens — for numerical progressions:

1--rs-{category}-{step}

Examples:

  • --rs-color-foreground-base-primary — primary text color
  • --rs-color-background-accent-emphasis — accent button background
  • --rs-space-5 — 16px spacing
  • --rs-radius-3 — medium border radius
  • --rs-shadow-lifted — elevated shadow

Using tokens in CSS:

1.custom-card {
2  background: var(--rs-color-background-base-secondary);
3  border: 1px solid var(--rs-color-border-base-primary);
4  border-radius: var(--rs-radius-4);
5  padding: var(--rs-space-5);
6  box-shadow: var(--rs-shadow-feather);
7}

Token Categories:

  • Colors — foreground, background, border, and overlay colors
  • Spacing — consistent scale from 2px to 120px
  • Radius — border radius that adapts to style variants
  • Typography — font families, sizes, weights, and line heights
  • Effects — shadows and blur for depth and elevation

API Reference

ThemeProvider

The ThemeProvider component wraps your application and manages theme state. It handles persisting the user's preference to localStorage, syncing with system preferences, and injecting the appropriate CSS variables into the document.

Prop

Type

useTheme

The useTheme hook provides access to the current theme state and methods to change it. Use this to build theme toggles, read the resolved theme for conditional rendering, or sync with external systems.

1import { useTheme } from "@raystack/apsara";
2

3function ThemeToggle() {
4  const { theme, setTheme, resolvedTheme } = useTheme();
5

6  return (
7    <button onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}>
8      Toggle theme
9    </button>
10  );
11}

Prop

Type

Framework Integration

HTML Attributes — the ThemeProvider sets data attributes on the document element for CSS targeting:

  • data-theme — current color scheme (light | dark)
  • data-style — active style variant (modern | traditional)
  • data-accent-color — active accent color (indigo | orange | mint)
  • data-gray-color — active gray variant (gray | mauve | slate)

SSR & Flash Prevention — the ThemeProvider includes an inline script that runs before React hydration to prevent flash of incorrect theme. For SSR frameworks, include the provider in your root layout:

1// Next.js App Router: app/layout.tsx
2import { ThemeProvider } from "@raystack/apsara";
3

4export default function RootLayout({ children }) {
5  return (
6    <html lang="en" suppressHydrationWarning>
7      <body>
8        <ThemeProvider>{children}</ThemeProvider>
9      </body>
10    </html>
11  );
12}

The suppressHydrationWarning is required because the theme script modifies the HTML element before React hydrates.

Scoped Theming

Themes are not limited to the document root. Any element with a data-theme attribute creates an isolated theme scope — descendants resolve every design token from the nearest scoped ancestor. This enables theme preview cards, split-screen comparisons, and dark sidebars in light apps without any extra plumbing.

Bare attribute

Because scoping is implemented in CSS, you can opt in by simply setting the attribute on any element:

1<html data-theme="dark">
2  {/* Page is dark */}
3  <div data-theme="light">
4    {/* This subtree renders with light tokens */}
5    <Button>Light button inside dark page</Button>
6  </div>
7</html>

The package's stylesheet handles the rest: every --rs-color-* token, color-scheme for native form controls and scrollbars, and the smooth transition during theme switches all follow the scoped attribute.

Nested ThemeProvider

For a typed convenience wrapper, nest ThemeProvider:

1import { ThemeProvider } from "@raystack/apsara";
2

3<ThemeProvider forcedTheme="dark">
4  <Card>Dark scoped card</Card>
5</ThemeProvider>

When ThemeProvider is rendered inside another ThemeProvider, it switches to scope mode: it writes data-theme (and optionally data-accent-color, data-gray-color, data-style) onto a wrapper <div> rather than the document root. The outer provider's state remains the source of truth for useTheme().

Combining with accent and gray overrides

A scope can override accent or gray independently of theme. This is useful for highlighting a section without changing its color scheme:

1<ThemeProvider accentColor="orange">
2  <Button color="accent">Orange accent in this region only</Button>
3</ThemeProvider>
4

5<ThemeProvider forcedTheme="dark" accentColor="mint" grayColor="slate">
6  <Card>Dark mint-on-slate card</Card>
7</ThemeProvider>

State management

By default, a nested ThemeProvider is stateless — the consumer owns the theme value. For an interactive scope, drive it with React state:

1const [scopeTheme, setScopeTheme] = useState<'light' | 'dark'>('dark');
2

3<ThemeProvider forcedTheme={scopeTheme}>
4  <Toggle onClick={() => setScopeTheme(t => t === 'dark' ? 'light' : 'dark')}>
5    Toggle this scope
6  </Toggle>
7  <Card>...</Card>
8</ThemeProvider>

Persistent scope

Pass storageKey to a nested ThemeProvider and it becomes stateful, persisting the scope's theme to localStorage. Descendants read and update it through the same useTheme() hook — it returns the nearest provider's state, so inside a persistent scope it returns the scope's theme and setter:

1import { ThemeProvider, useTheme } from "@raystack/apsara";
2

3function ScopeToggle() {
4  const { theme, setTheme } = useTheme();
5

6  return (
7    <button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
8      Toggle (currently {theme ?? "inherited"})
9    </button>
10  );
11}
12

13<ThemeProvider storageKey="dashboard-theme" defaultTheme="dark">
14  <ScopeToggle />
15  <Dashboard />
16</ThemeProvider>

Behavior:

  • On mount, the scope reads localStorage[storageKey]. If present, that value wins. Otherwise the scope uses defaultTheme. If neither is set, the scope inherits from its parent (no data-theme on the wrapper).
  • Inside the scope, useTheme() returns layered state: scope-owned fields (theme, setTheme) come from the scope; the rest (themes, systemTheme, etc.) are inherited from the root.
  • setTheme(value) updates state and writes to the scope's localStorage key.
  • setTheme(undefined) clears the storage entry and re-inherits from the parent.
  • Changes from other tabs propagate automatically via the storage event.
  • forcedTheme, if passed, wins over storage for display but is not persisted — it's a developer override, not a user choice.

Gotchas:

  • Use a distinct storageKey per scope. Multiple scopes sharing one key is undefined behavior within the same tab.
  • There is no FOUC prevention for nested scopes. On reload, the scope renders with defaultTheme (or inherits) for one paint, then snaps to the saved value once React hydrates. For above-the-fold scopes you'll see a brief flash. The root provider's inline script protects <html> only; per-scope inline scripts are not emitted in this version.

When to reach for a nested provider vs. the bare attribute

  • Use the bare data-theme attribute when you're already rendering a custom element and don't want another wrapper. The CSS handles everything — components inside will theme correctly.
  • Use a nested ThemeProvider when you want typed props (forcedTheme, accentColor, etc.) and a single import that documents intent.