ApollionProvider
ApollionProvider is the single entry point for theme configuration. It resolves the theme from your
seeds, density and text size, runs the mode engine, and supplies the result to every component through
styled-components' ThemeProvider. Without props it renders the stock theme.Usage
import { ApollionProvider } from '@apollion-dsi/core/themes';
<ApollionProvider colors={{ main: '#003750' }} defaultMode="system" persist="localStorage" dimension="compact">
<App />
</ApollionProvider>;The resolution order is: lightTheme/darkTheme when present, then theme, then colors (the stock seeds
when omitted). dimension, textSize, typeWeight and a11y apply only when the provider builds the
theme itself; a pre-built theme carries its own. Read the result with useApollionTheme(), which returns theme, mode, resolvedMode,
setMode, a11y and setA11y.
Modes
Pass one light-mode colors config and the provider derives both themes. The flip is a CSS attribute
change on <html>, not a re-render. The full contract — ladder, persistence, SSR — is on
Dark Mode.
Current mode: light
Same brand palette; base contrast flips between light/dark.For a dark design that is not the canonical swap, build both themes yourself and pass them as
lightTheme/darkTheme; toDarkColors from @apollion-dsi/core/themes/colors performs the swap
explicitly.
import { ApollionProvider, createTheme } from '@apollion-dsi/core/themes';
import { toDarkColors } from '@apollion-dsi/core/themes/colors';
const lightTheme = createTheme({ colors });
const darkTheme = createTheme({ colors: toDarkColors(colors) });
<ApollionProvider lightTheme={lightTheme} darkTheme={darkTheme} defaultMode="system">
<App />
</ApollionProvider>;Density, text size and surface
dimension scales spacing (Spacing & Dimensions); textSize scales type
(Text Size); surface="negative" inverts the Foundation and Semantic layers
(Surface Inversion). All three are props, with no hook and no getter.
A nested provider builds a whole new theme, so its mode and preset start fresh. Pass colors again for
a custom brand and syncDocument={false} so only the outer provider writes to <html>.
Properties
Prop | Type | Default | Description |
|---|---|---|---|
colors | ColorsInput | stock seeds | Light-mode seeds; the engine derives light and dark. |
theme | Theme | createTheme() | A pre-built theme; wins over colors. |
lightTheme / darkTheme | Theme | — | A pre-built pair for a non-canonical dark design; wins over both above. |
mode | 'light' | 'dark' | 'system' | — | Controlled preference; setMode only fires onModeChange. |
defaultMode | 'light' | 'dark' | 'system' | 'light' | Uncontrolled initial preference; restored from persist. |
initialMode | 'light' | 'dark' | — | The mode the server rendered; the stored preference applies before paint. |
onModeChange | (mode) => void | — | Fires on every setMode. |
persist | false | 'localStorage' | 'cookie' | ModeStorage | false | Stores mode under storageKey and a11y under `${storageKey}-a11y`. |
storageKey | string | 'apollion-mode' | Storage key of the preference. |
syncDocument | boolean | true | Writes data-apollion-mode, data-apollion-a11y and color-scheme on <html>. |
attribute | string | 'data-apollion-mode' | Attribute name written by syncDocument. |
a11y | null | 'grayscale' | 'high-contrast' | 'colorblind' | — | Controlled accessibility preset, orthogonal to the mode. |
defaultA11y | same as a11y | null | Uncontrolled initial preset; restored from persist. |
onA11yChange | (a11y) => void | — | Fires on every setA11y. |
dimension | 'compact' | 'normal' | 'spacious' | 'normal' | Spacing density. |
textSize | 'smaller' | 'default' | 'larger' | 'largest' | 'default' | Text and icon size, independent of dimension. |
typeWeight | 'light' | 'regular' | 'stronger' | 'regular' | Origin of the font-weight ladder. |
surface | 'positive' | 'negative' | 'positive' | Inverts the Foundation and Semantic layers app-wide. |
useSystemPreference | boolean | false | Deprecated: use defaultMode="system". |
themeMode / onThemeModeChange | 'light' | 'dark' / callback | — | Deprecated: use mode and onModeChange. |