The ThemeProvider component manages theme state including dark mode, light mode, and system preference. It includes the ThemeSwitcher component for toggling themes and the useTheme hook for accessing theme state.
Usage
import { ThemeProvider } from '@raystack/apsara';
function App() {
return (
<ThemeProvider>
{/* Your app content */}
</ThemeProvider>
);
}
Theme configuration
import { ThemeProvider } from '@raystack/apsara';
<ThemeProvider
defaultTheme="dark"
storageKey="my-app-theme"
style="modern"
accentColor="indigo"
grayColor="slate"
>
{/* Your app */}
</ThemeProvider>
Custom themes
<ThemeProvider
themes={['light', 'dark', 'custom']}
defaultTheme="light"
enableSystem={false}
>
{/* Your app */}
</ThemeProvider>
ThemeSwitcher
A pre-built component for toggling between light and dark themes.
import { ThemeProvider, ThemeSwitcher } from '@raystack/apsara';
function App() {
return (
<ThemeProvider>
<header>
<ThemeSwitcher size={24} />
</header>
{/* Your app content */}
</ThemeProvider>
);
}
useTheme hook
Access and control theme state from any component.
import { useTheme } from '@raystack/apsara';
function MyComponent() {
const { theme, setTheme, resolvedTheme, systemTheme } = useTheme();
return (
<div>
<p>Current theme: {theme}</p>
<p>Resolved theme: {resolvedTheme}</p>
<p>System theme: {systemTheme}</p>
<button onClick={() => setTheme('light')}>Light</button>
<button onClick={() => setTheme('dark')}>Dark</button>
<button onClick={() => setTheme('system')}>System</button>
</div>
);
}
Forced theme
Force a specific theme for certain pages or components.
<ThemeProvider forcedTheme="dark">
{/* This section will always use dark theme */}
</ThemeProvider>
Disable transitions
<ThemeProvider disableTransitionOnChange>
{/* Theme changes will not trigger CSS transitions */}
</ThemeProvider>
API reference
ThemeProvider
The default theme to use. If enableSystem is false, defaults to ‘light’.
themes
string[]
default:"['light', 'dark']"
List of all available theme names.
Force a specific theme for the current page or component tree.
Whether to enable system theme preference (prefers-color-scheme).
Whether to indicate to browsers which color scheme is used for built-in UI elements.
disableTransitionOnChange
Disable all CSS transitions when switching themes to prevent flickering.
Key used to store theme setting in localStorage.
attribute
string | 'class'
default:"data-theme"
HTML attribute modified based on the active theme. Accepts ‘class’ or any data attribute like ‘data-theme’, ‘data-mode’, etc.
Mapping of theme name to HTML attribute value. Object where key is theme name and value is the attribute value.
style
'modern' | 'traditional'
default:"modern"
Style variant of the theme. Affects radius and font properties.
accentColor
'indigo' | 'orange' | 'mint'
default:"indigo"
Accent color for the theme.
grayColor
'gray' | 'mauve' | 'slate'
default:"gray"
Gray color variant for the theme.
Nonce string to pass to the inline script for CSP headers.
ThemeSwitcher
Size of the theme toggle icon in pixels.
useTheme
Returns an object with the following properties:
Function to update the theme.
List of all available theme names.
The forced theme for the current page, if any.
If enableSystem is true and the active theme is ‘system’, this returns the resolved system preference (‘dark’ or ‘light’). Otherwise, identical to theme.
systemTheme
'dark' | 'light' | undefined
If enableSystem is true, returns the system theme preference, regardless of the active theme.