API Reference
⚛

useUiConfig

Access the active UiConfig reactively from any component — tokens, themes, breakpoints, fonts, and shorthands.

Overview

useUiConfig() returns the active UiConfig created by createUi(). It reads from the nearest UiConfigProvider in the tree, falling back to the global singleton if no provider is present.

✦
For most use cases you don't need useUiConfig() — use the t accessor for theme-reactive props and useTheme() for raw theme values. Reserve useUiConfig() for when you need breakpoints, fonts, or custom token groups inside a component.

Basic usage

import { useUiConfig } from '@stareezy-ui/tokens'

function MyComponent() {
  const ui = useUiConfig()

  // Access registered themes
  const auroraTheme = ui.getTheme('aurora')

  // Access media breakpoints
  const { md, lg } = ui.getMedia()

  // Access registered fonts
  const inter = ui.getFont('inter')

  // Access custom tokens (typed if you used module augmentation)
  const brandPrimary = ui.tokens.brand?.primary.value

  return (
    <div style={{ maxWidth: md }}>
      <span style={{ color: auroraTheme.text.importantBrand.value }}>
        {brandPrimary}
      </span>
    </div>
  )
}

Setup: UiConfigProvider

Wrap your app with UiConfigProvider to make the config available to all descendants without relying on the singleton:

// app/layout.tsx (Next.js)
import { UiConfigProvider, ThemeProvider } from '@stareezy-ui/tokens'
import { ui } from '../stareezy.config'

export default function RootLayout({ children }) {
  return (
    <html lang="en"><body>
      <UiConfigProvider config={ui}>
        <ThemeProvider theme="aurora">
          {children}
        </ThemeProvider>
      </UiConfigProvider>
    </body></html>
  )
}

Accessing themes

import { useUiConfig } from '@stareezy-ui/tokens'

function ThemedCard() {
  const ui = useUiConfig()
  const theme = ui.getTheme('steins-gate')

  return (
    <div style={{
      background: theme.backgrounds.secondary.value,
      color: theme.text.primary.value,
      border: `1px solid ${theme.border.primaryBrand.value}`,
    }}>
      Steins;Gate themed card
    </div>
  )
}

Accessing breakpoints

import { useUiConfig } from '@stareezy-ui/tokens'

function ResponsiveGrid({ children }) {
  const ui = useUiConfig()
  const bp = ui.getMedia()

  // Use breakpoints for JS-driven responsive logic
  // (prefer CSS media queries when possible)
  const style = {
    display: 'grid',
    gridTemplateColumns: `repeat(auto-fill, minmax(${bp.sm}px, 1fr))`,
  }

  return <div style={style}>{children}</div>
}

Accessing custom tokens

import { useUiConfig } from '@stareezy-ui/tokens'

function BrandButton() {
  const ui = useUiConfig()

  // Fully typed if you used module augmentation in stareezy.config.ts
  const primary = ui.tokens.brand.primary.value   // "#FF6B35"
  const secondary = ui.tokens.brand.secondary.value // "#004E89"

  return (
    <button style={{ background: primary, color: '#fff' }}>
      Brand button
    </button>
  )
}

Fallback behavior

When called outside a UiConfigProvider, useUiConfig() falls back to the global singleton and logs a dev warning. If createUi() was never called, it throws.

// Works without UiConfigProvider — uses the singleton
const ui = useUiConfig()  // dev warning in console, but works

// To silence the warning:
<UiConfigProvider config={ui}>
  <AnyComponent />
</UiConfigProvider>
⚠
If createUi() has never been called and there's no UiConfigProvider, useUiConfig() will throw. Always import your stareezy.config.ts before rendering any components.

API reference

Method / PropertyReturnsDescription
tThemeTokenAccessorTheme-reactive token accessor — same as standalone t import.
tokensBuiltinTokens & TTokensAll built-in + custom token groups.
shorthandsRecord<string, string>Registered prop shorthand mappings.
breakpointsUiBreakpointConfigResolved breakpoints (same as getMedia()).
getTheme(name)ThemeTokenMapFull token map for a named theme. Throws ThemeNotFoundError if not registered.
getFont(name)FontConfigFont config for a named font. Throws FontNotFoundError if not registered.
getMedia()UiBreakpointConfigResolved media query breakpoint map.
getTokens()BuiltinTokens & TTokensReturns the merged token registry.
registerTokens(t)UiConfig<T & TNew>Add more token groups. Returns a new typed config.
updateBreakpoints(o)voidMutate breakpoints at runtime.

Related