uikit.docs

Globals

Global APIs to control defaults, classes, and color scheme.

Overview

uikit exposes a few global utilities that influence styling and behavior across your UI:

  • setGlobalProperties, resetGlobalProperties
  • StyleSheet (global class registry)
  • setPreferredColorScheme, getPreferredColorScheme, basedOnPreferredColorScheme, isDarkMode

These are framework-agnostic (work in @pmndrs/uikit and @react-three/uikit).

Global properties

Use setGlobalProperties to set default properties that apply to all components. This is useful for global defaults such as fontFamilies, base color, pixelSize, or shared layout values. Later calls merge into existing defaults; use resetGlobalProperties to overwrite.

import { setGlobalProperties, resetGlobalProperties } from '@pmndrs/uikit'

// set or merge global defaults
setGlobalProperties({
  color: '#222',
  fontFamilies: { default: { normal: '/fonts/Inter-Medium.woff' } },
})

// completely replace the global defaults
resetGlobalProperties({
  color: 'white',
})
  • Merge behavior: setGlobalProperties(next) merges on top of the current global properties, while resetGlobalProperties(next) replaces them entirely.
  • Precedence: component props > conditional props > '*' star props > global properties. Globals provide the lowest-precedence defaults.

Global StyleSheet

StyleSheet is a global map of reusable classes. You can define named styles once and assign them via a component's classList (string names) or by passing inline objects.

import { StyleSheet } from '@pmndrs/uikit'

// define classes globally
StyleSheet.button = {
  paddingX: 12,
  paddingY: 8,
  borderRadius: 8,
}

StyleSheet['btn-primary'] = {
  backgroundColor: '#2563eb',
  color: 'white',
}

// usage in React
import { Container, Text } from '@react-three/uikit'

function Button({ children }) {
  return (
    <Container classList={['button', 'btn-primary']}>
      <Text>{children}</Text>
    </Container>
  )
}

Notes:

  • Unknown class names log a warning and are ignored.
  • classList also accepts inline objects: classList={[{ opacity: 0.8 }]}.
  • Element id styles can be predeclared via StyleSheet['__id__myId'] = { ... } and will auto-apply to elements with id="myId".

Preferred color scheme

Control or react to dark/light mode preferences.

import {
  setPreferredColorScheme,
  getPreferredColorScheme,
  basedOnPreferredColorScheme,
  isDarkMode,
} from '@pmndrs/uikit'

setPreferredColorScheme('light') // 'light' | 'dark' | 'system'
console.log(getPreferredColorScheme())

const theme = basedOnPreferredColorScheme({
  light: { background: 'white', foreground: '#222' },
  dark: { background: '#111', foreground: 'white' },
})

// Signals update when the scheme changes
// e.g. <Container backgroundColor={theme.background} color={theme.foreground} />

If you need a boolean in computed values, use isDarkMode.

Edit this page