Overview

Understanding the Apsara theming system and ThemeProvider.

Apsara provides a flexible theming system that supports light and dark modes, multiple accent colors, gray color variants, and style presets. The ThemeProvider component manages theme state and applies the appropriate CSS variables to your application.

Installation

Wrap your application with the ThemeProvider component:

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

3function App() {
4  return (
5    <ThemeProvider>
6      {/* Your application */}
7    </ThemeProvider>
8  );
9}

Theme Modes

Apsara supports three theme modes:

ModeDescription
lightLight color scheme
darkDark color scheme
systemFollows the user's system preference

Style Variants

Style variants affect the overall visual appearance, including border radius and typography:

StyleDescription
modernSharp corners, Inter font family (default)
traditionalSofter, rounded corners, Lora/Josefin Sans fonts

Accent Colors

Accent colors define the primary brand color used throughout the interface:

ColorDescription
indigoBlue-violet accent (default)
orangeWarm orange accent
mintFresh mint/teal accent

Gray Colors

Gray color variants affect neutral tones throughout the interface:

ColorDescription
grayPure neutral gray (default)
mauveWarm gray with purple undertone
slateCool gray with blue undertone

ThemeProvider Props

Prop

Type

useTheme Hook

Access and control the current theme using the useTheme hook:

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

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

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

useTheme Return Values

Prop

Type

Examples

Basic Setup

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

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

Custom Accent Color

1<ThemeProvider accentColor="orange" grayColor="slate">
2  <YourApp />
3</ThemeProvider>

Traditional Style

1<ThemeProvider style="traditional">
2  <YourApp />
3</ThemeProvider>

Force Dark Mode

1<ThemeProvider forcedTheme="dark">
2  <YourApp />
3</ThemeProvider>

Complete Configuration

1<ThemeProvider
2  defaultTheme="system"
3  enableSystem={true}
4  style="modern"
5  accentColor="indigo"
6  grayColor="gray"
7  storageKey="my-app-theme"
8  disableTransitionOnChange={false}
9>
10  <YourApp />
11</ThemeProvider>

HTML Attributes

The ThemeProvider sets the following attributes on the document element:

AttributeExample ValueDescription
data-theme"light" or "dark"Current color scheme
data-style"modern" or "traditional"Visual style variant
data-accent-color"indigo"Accent color
data-gray-color"gray"Gray color variant

Avoiding Flash

The ThemeProvider includes an inline script that runs before React hydration to prevent flash of incorrect theme. This ensures the correct theme is applied immediately on page load.

For SSR frameworks, ensure the ThemeProvider is included in your root layout:

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

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

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