Themes

Zen supports light and dark themes out of the box. Themes are applied using CSS custom properties that automatically adjust colors, backgrounds, and borders based on the active theme.

Setup#

Wrap your application with ZenProvider to enable theme support.

import { ZenProvider } from '@umami/react-zen';

function App() {
  return (
    <ZenProvider>
      <YourApp />
    </ZenProvider>
  );
}

Theme options#

You can configure the initial theme using the theme or colorScheme props.

// Force a specific theme
<ZenProvider theme="dark">

// Use system preference
<ZenProvider colorScheme="system">

// Default to light, but respect system preference
<ZenProvider colorScheme="light">

ThemeButton#

Use the ThemeButton component to let users toggle between light and dark themes.

<ThemeButton variant="outline" />

Local themes#

You can scope theme changes to a specific container using the target prop. This allows parts of your UI to have a different theme than the rest of the page.

function LocalThemeExample() {
  const containerRef = useRef(null);

  return (
    <Box ref={containerRef} padding="6" backgroundColor="surface">
      <Row alignItems="center" justifyContent="space-between">
        <Text>This container has its own theme</Text>
        <ThemeButton target={containerRef} />
      </Row>
    </Box>
  );
}

useTheme hook#

Access and control the current theme programmatically with the useTheme hook.

import { useTheme } from '@umami/react-zen';

function MyComponent() {
  const { theme, setTheme } = useTheme();

  return (
    <Button onPress={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
      Current theme: {theme}
    </Button>
  );
}

CSS variables#

Themes work by redefining CSS custom properties. The following variables change based on the active theme:

Theme persistence#

Theme preference is automatically saved to localStorage under the key theme. When the page loads, the stored preference is restored.

Dark mode classes#

Zen applies both data-theme="dark" attribute and the .dark class to the root element for maximum compatibility with Tailwind CSS and other frameworks.

Color palettes#

Zen supports multiple gray-scale palettes inspired by Tailwind CSS. Each palette has a different color temperature and character.

Available palettes#

Setting the palette#

You can set the palette via ZenProvider or programmatically with useTheme.

// Via provider
<ZenProvider palette="slate">
  <YourApp />
</ZenProvider>

// Programmatically
const { palette, setPalette } = useTheme();
setPalette('zinc');

Palette persistence#

Palette preference is automatically saved to localStorage under the key zen.palette. The data-palette attribute is applied to the root element.