Skip to the content

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.
Theming

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.
Scrolls sideways inside the table. The page does not.

See also