LucentProvider

The runtime theming spine: seeds the initial theme/accent/density/glass axes, provides useLucent(), and wires the SSR no-flash + RTL direction. Optional — components also read defaults straight from :root.

Group: Theming · Import path: @orionshub/lucent/theme · Client component — ships a "use client" boundary.

Import

import { LucentProvider, useLucent } from '@orionshub/lucent'
import '@orionshub/lucent/styles.css' // once, at your app root

Examples

useLucent + setters

useLucent + setters

Show source

function AxisReadout() {
  const { theme, accent, density, glassOpacity, glassBlur, contrast } = useLucent()
  const axes = { theme, accent, density, glassOpacity, glassBlur, contrast }
  return (
    <dl style={{ display: 'grid', gridTemplateColumns: 'auto auto', gap: '4px 16px', margin: 0 }}>
      {Object.entries(axes).map(([k, v]) => (
        <Fragment key={k}>
          <dt style={{ opacity: 0.7 }}>{k}</dt>
          <dd style={{ margin: 0, fontWeight: 600 }}>{String(v)}</dd>
        </Fragment>
      ))}
    </dl>
  )
}

export function LucentProviderBasic() {
  return (
    <LucentProvider>
      <GlassSurface style={{ padding: 16, borderRadius: 12 }}>
        <AxisReadout />
      </GlassSurface>
    </LucentProvider>
  )
}

Props

Prop	Type	Default	Description
children*	React.ReactNode	—
defaultAccent	Accent | undefined	—	Default accent preset (default: "cyan")
defaultDensity	Density | undefined	—	Default density (default: "airy")
defaultGlassBlur	number | undefined	—	Default backdrop blur in px (default: 12)
defaultGlassOpacity	number | undefined	—	Default glass opacity (default: 0.72)
defaultTheme	Theme | undefined	—	Default colour theme (default: "dark")
dir	"ltr" | "rtl" | undefined	—	Text directionality for Radix DirectionProvider (default: "ltr")
persist	boolean | undefined	—	Persist axis values to localStorage (default: true)

Guidance

One-time CSS import

Import the compiled stylesheet once at your app root: import '@orionshub/lucent/styles.css'. Components ship stable class names and read design tokens from CSS custom properties — there is no style runtime. See CSS Import.

Transparency & solid mode

Every glass surface reads --lucent-glass-opacity (0.60–1.0). Dial it at runtime with setGlassOpacity(), or switch to setContrast('solid') for a fully opaque, high-contrast rendering. See Transparency & Solid Mode.

RTL

Authored with CSS logical properties — set dir="rtl" on a parent (or the document) and layout mirrors with no JS. Toggle RTL from the glass-controls panel to preview. See RTL Support.

SSR / Next.js

Client component — ships a "use client" boundary. All components are safe to import in a Server Component tree; interactive ones carry their own "use client" boundary. See SSR & Next.js.