API Reference

Theme API

The three React exports of @refraction-ui/react/theme — ThemeProvider, ThemeScript, and useTheme.

Installation

$pnpm add @refraction-ui/react

Full setup (SSR-safe)

Always pair <ThemeScript> in <head> with <ThemeProvider> in <body>, and keep their props in lockstep.

Code example not yet available for flutter.

`ThemeProvider` props

Prop	Type	Default	Description
`defaultMode`	`'light' \| 'dark' \| 'system'`	`'system'`	Theme applied when nothing is stored. Mirror this in <ThemeScript> for SSR.
`storageKey`	`string`	`'rfr-theme'`	localStorage key used to persist the user choice.
`attribute`	`'class' \| 'data-theme'`	`'class'`	How the theme is applied to <html>. 'class' toggles `light` / `dark` classes.
`enableSystem`	`boolean`	`true`	When false, the provider never falls through to `prefers-color-scheme` — `defaultMode` wins on first visit.

`ThemeScript` props

Inline <script> placed in <head> to prevent the dark-flash on first paint. Issue #317: defaultMode + enableSystem are now honoured, so the script no longer silently falls through to prefers-color-scheme when the provider says otherwise.

Prop	Type	Default	Description
`defaultMode`	`'light' \| 'dark' \| 'system'`	`'system'`	Theme to apply when nothing is stored. Match your <ThemeProvider defaultMode> so the pre-paint script and provider agree on the no-storage path (issue #317).
`enableSystem`	`boolean`	`true`	When false, the inline script never reads `prefers-color-scheme`. Combined with `defaultMode="light"`, this is the fix for the dark-flash → brand-light flicker on first visit.
`storageKey`	`string`	`'rfr-theme'`	Must match the ThemeProvider value.
`attribute`	`'class' \| 'data-theme'`	`'class'`	Must match the ThemeProvider value.

`useTheme`