Theme Customization

Customize Xaui to match your brand by overriding only the tokens you need. You can define separate light and dark themes while keeping all defaults for tokens you do not override.

How It Works

  • Pass a partial object to theme for light mode.
  • Pass a partial object to darkTheme for dark mode.
  • Xaui merges your overrides with defaults, so you only customize what you need.

Provider Setup

Start by configuring your app-level provider with custom light and dark tokens.

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


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


const customDarkTheme = {
  colors: {
    primary: {
      main: '#60A5FA',
      foreground: '#0B1220',
      background: '#1E3A8A',
    },
    background: '#020617',
    foreground: '#E2E8F0',
  },
}


export default function App() {
  return (
    <XUIProvider theme={customLightTheme} darkTheme={customDarkTheme}>
      <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

  1. Set core brand colors: primary, background, and foreground.
  2. Tune border radius and spacing to match your product identity.
  3. Adjust typography tokens only when needed for readability.
  4. Validate both light and dark modes on real screens.