Skip to main content
196

Search Lumen

Find components, APIs, guides, and recipes.

GitHub
Web docs
Editors and workspaces

useThemeBuilder

Interactive theme builder with controllable hue, accent, mode (generated/manual), scheme (light/dark), color pickers, and export in CSS, Figma variables, or design token formats.

Live component preview · Astro

Explore ThemeBuilder

Try the component this hook connects to. The preview uses the Astro adapter; the React example below uses useThemeBuilder.

Brand theme

React usage

Import from @santi020k/lumen-react and spread the controller props onto the matching components.

tsxuseThemeBuilder example
import { ThemeBuilder, Card, Button, Label, Slider, Textarea } from '@santi020k/lumen-react'
import { useThemeBuilder } from '@santi020k/lumen-react'

export function CustomThemeBuilder() {
  const builder = useThemeBuilder({ defaultHue: 264, defaultScheme: 'dark' })

  return (
    <ThemeBuilder {...builder.rootProps}>
      <div style={builder.previewStyle}>
        <Card glass>
          <Label htmlFor="theme-brand-hue">Brand hue</Label>
          <Slider {...builder.hueProps} id="theme-brand-hue" min={0} max={359} />
          <Label htmlFor="theme-accent-hue">Accent hue</Label>
          <Slider {...builder.accentHueProps} id="theme-accent-hue" min={0} max={359} />
          <div>
            <Button {...builder.getSchemeProps('light')}>Light</Button>
            <Button {...builder.getSchemeProps('dark')}>Dark</Button>
          </div>
          <Label htmlFor="theme-output">Generated theme CSS</Label>
          <Textarea {...builder.outputProps} aria-label="Generated theme CSS" id="theme-output" readOnly rows={6} />
          <Button {...builder.exportButtonProps}>Copy CSS</Button>
        </Card>
      </div>
    </ThemeBuilder>
  )
}
import { ThemeBuilder, Card, Button, Label, Slider, Textarea } from '@santi020k/lumen-react'
import { useThemeBuilder } from '@santi020k/lumen-react'

export function CustomThemeBuilder() {
  const builder = useThemeBuilder({ defaultHue: 264, defaultScheme: 'dark' })

  return (
    <ThemeBuilder {...builder.rootProps}>
      <div style={builder.previewStyle}>
        <Card glass>
          <Label htmlFor="theme-brand-hue">Brand hue</Label>
          <Slider {...builder.hueProps} id="theme-brand-hue" min={0} max={359} />
          <Label htmlFor="theme-accent-hue">Accent hue</Label>
          <Slider {...builder.accentHueProps} id="theme-accent-hue" min={0} max={359} />
          <div>
            <Button {...builder.getSchemeProps('light')}>Light</Button>
            <Button {...builder.getSchemeProps('dark')}>Dark</Button>
          </div>
          <Label htmlFor="theme-output">Generated theme CSS</Label>
          <Textarea {...builder.outputProps} aria-label="Generated theme CSS" id="theme-output" readOnly rows={6} />
          <Button {...builder.exportButtonProps}>Copy CSS</Button>
        </Card>
      </div>
    </ThemeBuilder>
  )
}

Load @santi020k/lumen-react/styles.css once in your application. With React Server Components, put 'use client' at the top of the module that calls the hook. Follow the React setup guide for the framework boundary.

Options

PropertyTypeDefaultDescription
defaultHuenumber210Initial hue value.
huenumber-Controlled hue.
onHueChange(hue: number) => void-Callback when the hue changes.
defaultAccentHuenumber-Initial accent hue.
accentHuenumber-Controlled accent hue.
onAccentHueChange(hue: number) => void-Callback when the accent hue changes.
defaultScheme"light" | "dark""dark"Initial color scheme.
scheme"light" | "dark"-Controlled color scheme.
onSchemeChange(scheme) => void-Callback when the scheme changes.
defaultMode"generated" | "manual""generated"Initial builder mode.
mode"generated" | "manual"-Controlled builder mode.
defaultExportFormat"css" | "figma" | "tokens""css"Initial export format.
onThemeChange(detail: ThemeBuilderChangeDetail) => void-Callback when any theme value changes.
onThemeExport(detail: ThemeBuilderExportDetail) => void-Callback when the user exports the theme.

Controller return values

PropertyTypeDescription
rootPropsLumenProps<"section">Spread onto the theme builder root.
huePropsLumenProps<"input">Spread onto the hue range input.
accentHuePropsLumenProps<"input">Spread onto the accent hue range input.
primaryColorPropsLumenProps<"input">Spread onto the primary color picker input.
secondaryColorPropsLumenProps<"input">Spread onto the secondary color picker input.
outputPropsLumenProps<"textarea">Spread onto the export output textarea.
exportButtonPropsLumenProps<"button">Spread onto the copy/export button.
getModeProps(mode, props?) => LumenProps<"button">Returns toggle props for a mode button.
getSchemeProps(scheme, props?) => LumenProps<"button">Returns toggle props for a scheme button.
getExportFormatProps(format, props?) => LumenProps<"button">Returns toggle props for an export format button.
previewStyleCSSPropertiesInline style object with generated CSS custom properties for live preview.
exportValuestringCurrent export string (CSS, Figma JSON, or design tokens JSON).
exportFormat"css" | "figma" | "tokens"Current export format.
tokensLumenThemeTokensCurrent generated theme tokens.
copyExport() => Promise<string>Copy the export value to clipboard and return it.
Web docsFull catalog