ThemeProvider
Owns application theme state, scoped overlays, messages, and root-only persistence.@gemologic/sheen · themingPlayground
<ThemeProvider defaultMode="dark" locale="en-US" defaultDensity="comfortable" defaultMode="dark" defaultMotion="full" defaultRadius="soft" direction="ltr" hydration="client" locale="en-US"><Button>Save</Button></ThemeProvider>Variant matrix
Dark application root
defaultMode: dark
defaultMode: light
defaultMode: system
defaultDensity: compact
defaultDensity: comfortable
defaultDensity: spacious
defaultRadius: sharp
defaultRadius: soft
defaultRadius: round
defaultMotion: full
defaultMotion: reduced
direction: ltr
direction: rtl
hydration: client
hydration: cookie
Anatomy
- Package
@gemologic/sheen- Source
packages/ui/src/theme/ThemeProvider.tsx- Tokens
- None
Accessibility
Role: context providerKeyboard: No component-owned keysDo
- Install the theme prepaint script in client hydration mode.
Do not
- Do not choose initial markup from browser-only state.
Generated props
| Name | Type | Default | Description |
|---|---|---|---|
initialState | ThemeState | — | Deterministic initial state; cookie mode requires identical server/client state. |
defaultMode | Mode | "system" | dark | Fresh-install preference; system follows the OS only when explicitly selected. |
defaultTheme | string | obsidian | Default registered theme ID. |
defaultAccent | import("@gemologic/sheen-tokens").AccentName | jade | Default independent accent preset. |
defaultDensity | "compact" | "comfortable" | "spacious" | comfortable | Default control density. |
defaultRadius | "sharp" | "soft" | "round" | soft | Default corner treatment. |
defaultMotion | "full" | "reduced" | full | Default motion preference; OS reduced motion still wins. |
direction | "ltr" | "rtl" | ltr | Explicit writing direction. |
locale | string | en-US | Explicit server/client Intl locale. |
themes | readonly ThemeMetadata[] | — | Registered themes. Load their CSS and configure the same prepaint catalog. |
storageKey | string | sheen | Root preference storage key. |
hydration | "client" | "cookie" | client | Client prepaint handoff or cookie-authoritative SSR. |
persist | (state: ThemeState) => Promise<void> | — | Cookie-mode app callback, awaited before accepting preference changes. |
onPersistenceError | (error: unknown) => void | — | Reports failed storage or cookie persistence. |
nonce | string | — | CSP nonce for generated scope scripts; match the document policy. |
messages | Partial<Messages> | — | Partial translations inheriting English defaults. |