Skip to content
Sapphire UIv4.1.0

Theme Provider

Coordinate the selected colour scheme across a React application. Use it at the application boundary when controls need to read or change the theme.

Examples

Preferences

JSX usage

Install this example’s dependencies, load the package stylesheet from Setup, and add Example CSS where shown. The snippet includes its local helpers.

bun add @kongmy-dev/sapphire-ui react react-dom
"use client";
import { Button } from "@kongmy-dev/sapphire-ui/button";
import { ThemeToggle } from "@kongmy-dev/sapphire-ui/theme-toggle";
import { ThemeProvider, useTheme } from "@kongmy-dev/sapphire-ui/theme-provider";

function ThemeControls() {
  const { theme, preference, setTheme } = useTheme();
  return (
    <div className="sp-stack">
      <output>
        Theme: {theme}; preference: {preference}
      </output>
      <div className="sp-cluster">
        <Button onClick={() => setTheme('light')}>Use light theme</Button>
        <Button onClick={() => setTheme('dark')}>Use dark theme</Button>
        <Button onClick={() => setTheme('system')}>Use system theme</Button>
        <ThemeToggle />
      </div>
    </div>
  );
}
function ThemeProviderPreferences() {
  return (
    <ThemeProvider>
      <ThemeControls />
    </ThemeProvider>
  );
}

export default ThemeProviderPreferences;
HTML markup

Initial rendered HTML only. React handlers and portalled content require the JSX example; static HTML does not reproduce those interactions.

Props

Generated from the current public TypeScript signatures, including composed behaviour props. “—” means no default is declared in the local signature; forwarded behaviour defaults are not inferred.

ThemeProvider

ThemeProvider component props
PropTypeRequiredLocal default
defaultPreferenceThemePreference | undefinedNo'system'
childrenReactNodeYes—

ThemeContext

No additional Sapphire props; accepts the platform props below.

Inherited HTML / React props (2)
ThemeContext common platform props
PropTypeRequiredLocal default
valueThemeContextValue | nullYes—
childrenReactNodeNo—

All inherited prop names:

value children

ARIA attributes and native event handlers keep their React types. data-* attributes are also accepted by React.

ThemePreference

Supporting type used by this API.

ThemePreference definition
Type
Theme | "system"

ThemeContextValue

Supporting type used by this API.

ThemeContextValue component props
PropTypeRequiredLocal default
themeThemeYes—
preferenceThemePreferenceYes—
setTheme(preference: ThemePreference) => voidYes—

Theme

Supporting type used by this API.

Theme definition
Type
"dark" | "light"

Setup

bun add @kongmy-dev/sapphire-ui react react-dom

For an app using package components throughout, load the full stylesheet once. Add this component import where you use it.

import "@kongmy-dev/sapphire-ui/sapphire.css";
import { ThemeContext } from "@kongmy-dev/sapphire-ui/theme-provider";

Mixing package and vendored components? Follow application setup.

Search documentation