Customization

Theme & ThemeOverride

Customize themes using ThemeProvider's theme and themeOverride properties (applied to providers, not components).

The themeOverride property is a function that receives the theme and returns it modified. Use it for changes the declarative options can't express, like adding base classes or changing defaults for any subtree of your application.

Basic usage

Modifying base classes

Add CSS classes that apply to all instances of a component:

Card with Shadow

<ThemeProvider themeOverride={(theme) => {
  // Compound themes are nested by sub-part: Button is `button.main`,
  // Card is `card.main`. Single-target themes (Badge, Chip, etc.) sit at the top level.
  theme.button.main.base += ' uppercase tracking-wide';
  theme.card.main.base += ' shadow-sm';
  return theme;
}}>
  <Button primary>Uppercase Button</Button>
  <Card>Card with Shadow</Card>
</ThemeProvider>

Modifying default props

Change the default boolean props for components:

<ThemeProvider themeOverride={(theme) => {
  theme.button.main.defaults = {
    ...theme.button.main.defaults,
    filled: true,
    pill: true,
  };
  return theme;
}}>
  <Button primary>Filled Pill Button</Button>
</ThemeProvider>

Note: For changing defaults, prefer using themeDefaults instead. It uses fewer pieces and the public ThemeDefaults type:

// Preferred approach for defaults
<ThemeProvider themeDefaults={{
  button: { main: { filled: true, pill: true } }
}}>

Combining with other props

Use themeOverride alongside themeDefaults and extraClasses:

<ThemeProvider
  themeDefaults={{ button: { main: { filled: true } } }}
  themeOverride={(theme) => {
    theme.button.main.base += ' tracking-wide';
    return theme;
  }}
  extraClasses={{
    button: { main: { primary: 'hover:shadow-lg' } }
  }}
>
  <Button>Fully Customized</Button>
</ThemeProvider>

Nested ThemeProviders

Child overrides build on parent modifications:

<ThemeProvider themeOverride={(theme) => {
  theme.button.main.base += ' uppercase';
  return theme;
}}>
  <Button>Uppercase</Button>

  <ThemeProvider themeOverride={(theme) => {
    theme.button.main.base += ' tracking-widest';
    return theme;
  }}>
    <Button>Uppercase + Wide Tracking</Button>
  </ThemeProvider>
</ThemeProvider>

When to use themeOverride

Use themeOverride when you need to add base CSS classes to all component instances
Use themeDefaults when you want to change default boolean props (smaller surface)
Use extraClasses when you want to add classes based on active props