Theme Customization

Customize Xaui to match your brand by overriding only the tokens you need. Provide partial overrides and keep defaults for everything you do not specify.

How It Works

Pass a partial object to theme to override tokens.
Xaui merges your overrides with defaults, so you only customize what you need.

Provider Setup

Start by configuring your app-level provider with partial custom tokens.

import { XUIProvider } from '@xaui/native/core'

const customLightTheme = {
  colors: {
    primary: {
      main: '#2563EB',
      onMain: '#FFFFFF',
      container: '#DBEAFE',
      onContainer: '#1E40AF',
    },
    background: '#FFFFFF',
    foreground: '#0F172A',
  },
  borderRadius: {
    md: 12,
    lg: 16,
  },
}

export default function App() {
  return (
    <XUIProvider theme={customLightTheme}>
      <YourApp />
    </XUIProvider>
  )
}

Using Theme Values

Access resolved values in any component with useXUITheme() and check current mode with useColorMode() .

import { View, Text } from 'react-native'
import { useXUITheme, useColorMode } from '@xaui/native/core'

export function ThemeExample() {
  const theme = useXUITheme()
  const mode = useColorMode()

  return (
    <View
      style={{
        backgroundColor: theme.colors.background,
        padding: theme.spacing.md,
        borderRadius: theme.borderRadius.lg,
      }}
    >
      <Text style={{ color: theme.colors.foreground }}>
        Current mode: {mode}
      </Text>
      <Text style={{ color: theme.colors.primary.main }}>
        Brand color from theme
      </Text>
    </View>
  )
}

Recommended Customization Order

Set core brand colors: primary (main, onMain, container, onContainer), background, and foreground.
Tune border radius and spacing to match your product identity.
Adjust typography tokens only when needed for readability.
Validate both light and dark modes on real screens.