AppShellsibling
ThemeProvider typically wraps AppShellTheme
Theme management system with provider, toggle, and hook pattern. Supports light, dark, and system modes with localStorage persistence.
Setup
import { Theme } from '@fragments-sdk/ui';Examples
Default
ThemeProvider with system default
Loading preview...
With Toggle
ThemeProvider with toggle button
Loading preview...
Toggle Sizes
ThemeToggle in different sizes
Loading preview...
Props
| Prop | Type | Default | Description |
|---|---|---|---|
childrenRequired | node | Not set | Application content |
defaultMode | enumlightdarksystem | system | Default theme mode for uncontrolled usage |
defaultTheme | enumlightdarksystem | Not set | — |
mode | enumlightdarksystem | Not set | Controlled theme mode |
onModeChange | function | Not set | Callback when mode changes |
storageKey | string | fui-theme | localStorage key for persistence |
attribute | enumdata-themeclass | data-theme | How to apply theme to DOM |
Usage Guidelines
When to use
- Providing theme context to an application
- Toggling between light and dark modes
- Respecting system color scheme preference
- Persisting theme preference across sessions
When not to use
- Simple one-off color changes (use CSS variables)
- Component-level theming (use component props)
Best practices
- Wrap your app with ThemeProvider at the root level
- Use useTheme hook to access theme state in components
- ThemeToggle cycles through light → dark → system
- Use storageKey to customize localStorage key
- Set attribute="class" if your CSS uses .dark class instead of data-theme
- ThemeToggle forwards DOM props (id, data-*, className, handlers) to the toggle group
Accessibility
- ThemeToggle button has accessible label indicating current mode
- Theme changes are applied via CSS custom properties for smooth transitions
- System preference is detected via prefers-color-scheme media query