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 a consistent naming pattern:

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

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.