Overview

useUiConfig() is a React hook that 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.

✦

Use useUiConfig() when you need to read config values reactively inside a component — for example, to access registered fonts, themes, or media breakpoints. For non-component code, use getUiConfig() instead.

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 breakpoints = ui.getMedia()

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

  // Access all tokens
  const tokens = ui.getTokens()

  return (
    <div style={{ maxWidth: breakpoints.md }}>
      <span style={{ color: auroraTheme.text.primary.value }}>
        Hello from aurora theme
      </span>
    </div>
  )
}

Setup: UiConfigProvider

Wrap your app with UiConfigProvider to make the config available to all descendants. This is the recommended approach for Next.js and React apps.

// lib/ui.ts
import { createUi, token, motion, themes } from '@stareezy-ui/tokens'

export const ui = createUi({
  fonts: {
    inter: {
      family: 'Inter, system-ui, sans-serif',
      size: { sm: token(14, 'inter-sm'), md: token(16, 'inter-md') },
    },
  },
  themes: {
    aurora: themes.aurora,
  },
  animations: {
    fadeIn: { duration: motion.duration.enter, easing: motion.easing.easeOut },
    spring: { duration: motion.duration.normal, easing: motion.easing.spring },
  },
  media: { sm: 640, md: 768, lg: 1024, xl: 1280, '2xl': 1536 },
  shorthands: { bg: 'backgroundColor', p: 'padding', m: 'margin' },
})

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

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

Accessing Themes

Use getTheme(name) to retrieve a registered theme's full token map. Throws ThemeNotFoundError if the theme isn't registered.

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

function ThemedCard() {
  const ui = useUiConfig()

  let theme
  try {
    theme = ui.getTheme('aurora')
  } catch (e) {
    if (e instanceof ThemeNotFoundError) {
      theme = ui.getTheme('light') // fallback
    }
  }

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

Accessing Fonts

Use getFont(name) to retrieve a registered font config. Throws FontNotFoundError if the font isn't registered.

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

function StyledText({ children }: { children: React.ReactNode }) {
  const ui = useUiConfig()
  const inter = ui.getFont('inter')

  return (
    <span style={{
      fontFamily: inter.family,
      fontSize: inter.size?.md?.value,
    }}>
      {children}
    </span>
  )
}

Accessing Media Breakpoints

Use getMedia() to get the resolved breakpoint map. Useful for building responsive logic in components.

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

function ResponsiveGrid({ children }: { children: React.ReactNode }) {
  const ui = useUiConfig()
  const { width } = useDeviceLayout()
  const bp = ui.getMedia()

  const columns = width >= bp.lg ? 3 : width >= bp.md ? 2 : 1

  return (
    <div style={{
      display: 'grid',
      gridTemplateColumns: `repeat(${columns}, 1fr)`,
      gap: 16,
    }}>
      {children}
    </div>
  )
}

Accessing Animations

Use ui.getTokens().animations — or access the registered animation presets directly from the config object.

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

function AnimatedBox({ children }: { children: React.ReactNode }) {
  const ui = useUiConfig()

  // Animations are stored on the config object directly
  // (not via a getAnimations() method — access via the raw config)
  const fadeIn = (ui as any).animations?.fadeIn

  const style = fadeIn ? {
    animation: `fadeIn ${fadeIn.duration.value}ms ${fadeIn.easing.value} both`,
  } : {}

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

Accessing Shorthands

Shorthands registered via createUi are available on the config and automatically applied by the Box primitive.

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

function ShorthandDemo() {
  const ui = useUiConfig()

  // See what shorthands are registered
  console.log(ui.shorthands)
  // { bg: 'backgroundColor', p: 'padding', m: 'margin', ... }

  // Box automatically uses these — no extra wiring needed
  return (
    <Box bg={colors.aurora.surfaceDark} p={spacing[4]}>
      Shorthand props work automatically
    </Box>
  )
}

Fallback Behavior

When useUiConfig() is called outside a UiConfigProvider, it falls back to the global singleton created by createUi() and logs a development warning.

// This works even without UiConfigProvider — uses the singleton
import { useUiConfig } from '@stareezy-ui/tokens'

function AnyComponent() {
  // Falls back to getUiConfig() singleton + dev warning in console
  const ui = useUiConfig()
  return <div>{ui.breakpoints.md}</div>
}

// To silence the warning, wrap with UiConfigProvider:
<UiConfigProvider config={ui}>
  <AnyComponent />
</UiConfigProvider>

⚠

If createUi() has never been called and there's no UiConfigProvider, useUiConfig() will throw. Always call createUi() at app startup.

API Reference

useUiConfig()

Returns the active UiConfig from the nearest UiConfigProvider, or falls back to the getUiConfig() singleton.

UiConfig methods

Method	Returns	Description
`getTokens()`	`BuiltinTokens & TTokens`	All built-in + custom token groups.
`getTheme(name)`	`ThemeTokenMap`	Full token map for a named theme. Throws ThemeNotFoundError if not registered.
`getFont(name)`	`FontConfig`	Font config for a named font. Throws FontNotFoundError if not registered.
`getMedia()`	`UiBreakpointConfig`	Resolved media query breakpoint map.
`registerTokens(t)`	`UiConfig<T & TNew>`	Add more token groups. Returns a new typed config.
`updateBreakpoints(o)`	`void`	Mutate breakpoints at runtime.
`tokens`	`BuiltinTokens & TTokens`	Direct token access (same as getTokens()).
`breakpoints`	`UiBreakpointConfig`	Resolved breakpoints (same as getMedia()).
`shorthands`	`Record<string, string>`	Registered prop shorthand mappings.

createUi() — configure the design system at startup
Theming guide — useTheme() and useThemeSwitch()
Token Explorer — browse all built-in tokens visually

useUiConfig