Theme Provider

Owns the theme preset (data-theme) and color mode (.dark), including "system" mode.

Import

import { ThemeProvider } from '@marbleui/ui'
import { useTheme } from '@marbleui/ui'

Props

<ThemeProvider>

Prop	Type	Default	Description
children *required	`ReactNode`	`—`
className	`string`	`—`
defaultMode	`ColorMode`	`'system'`
defaultTheme	`ThemePreset`	`'minimal'`
scope	`'local' \| 'document'`	`'document'`	Apply to <html> (default) or render a wrapper <div> that scopes the theme.
storageKey	`string`	`—`	Persist choices in localStorage under this key. Omit to disable.

Hooks

useTheme(): ThemeContextValue

Usage notes

Owns the theme preset (data-theme="minimal" | "soft") and color mode (.dark), including following the system setting.

<ThemeProvider defaultTheme="soft" defaultMode="system" storageKey="acme-theme">
  <App />
</ThemeProvider>

useTheme() reads and sets theme and mode (for a ThemeToggle or settings page).
scope="local" renders a wrapper <div> that themes only its subtree (previews, embedded widgets) instead of <html>. With storageKey, the choice persists in localStorage.

Example source · show

import { Button } from '../button'
import { Card, CardBody, CardHeader } from '../card'
import { Segment, SegmentedControl } from '../segmented-control'
import { ThemeProvider, useTheme } from './theme-provider'

function Controls() {
  const { theme, setTheme, resolvedMode } = useTheme()
  return (
    <Card className="w-80">
      <CardHeader title="Scoped theme" description={`${theme} · ${resolvedMode}`} />
      <CardBody className="flex flex-col gap-3">
        <SegmentedControl aria-label="Preset" value={theme} onChange={(k) => setTheme(String(k))}>
          <Segment id="minimal">Minimal</Segment>
          <Segment id="soft">Soft</Segment>
        </SegmentedControl>
        <Button>Accent button</Button>
      </CardBody>
    </Card>
  )
}

export const styles = {
  Local: () => (
    <ThemeProvider scope="local" defaultTheme="soft" defaultMode="light" className="rounded-2xl p-6">
      <Controls />
    </ThemeProvider>
  ),
}

Source: packages/ui/src/theme-provider/theme-provider.tsx

Catalog

Category: utilities
Priority: Core
Primitive: custom
Base UI: CSP Provider