Theming

PanelUI ships three theme families, each in a light and a dark form. A family sets its own radius scale as well as its own palette, so switching one restyles the shape of the UI, not just its colour.

What each theme actually sets is the token list on Colors. This page is about choosing between them and adding your own.

Registering the themes

light and dark work everywhere. The other four must be listed in extraThemes in your Metro config, or setTheme('moon') throws "it was not registered".

module.exports = withUniwindConfig(config, {
  cssEntryFile: './src/global.css',
  extraThemes: ['moon', 'moon-dark', 'grass', 'grass-dark'],
});

PANEL_EXTRA_THEMES is exported with exactly that list, if you would rather not keep two copies in step.

Switching at runtime

import { useTheme, useThemeMode, PANEL_THEMES } from 'panelui-native';

// By name
const { theme, setTheme } = useTheme();
setTheme('moon-dark');
setTheme('system'); // follow the device

// Or as two independent axes
const { family, mode, setFamily, setMode, toggleMode } = useThemeMode();
toggleMode();          // dark ↔ light, staying in the current family
setFamily('grass');    // switch family, staying in the current mode

Uniwind applies the change natively without re-rendering the tree, so a theme switch costs nothing beyond the repaint.

Why there are two hooks

Uniwind gives prefers-color-scheme handling to light and dark and to nothing else — any other theme compiles to a plain class selector and cannot adapt on its own. Each family therefore ships as a light/dark pair, and useThemeMode treats family and mode as separate axes so a sun toggle keeps working inside a brand theme. Without it, someone in Moon dark who taps the sun lands in default light rather than in Moon light.

PANEL_THEMES is the list of families, each with a display name and a representative swatch colour for both modes — enough to build a theme picker without hardcoding anything.

{PANEL_THEMES.map((entry) => (
  <Pressable key={entry.id} onPress={() => setFamily(entry.id)}>
    <View style={{ backgroundColor: entry.swatch[mode === 'dark' ? 1 : 0] }} />
    <Text>{entry.name}</Text>
  </Pressable>
))}

Radius

--radius-xs through --radius-3xl are themed, and that is what gives each family its shape. Use rounded-md, rounded-xl and friends as normal — the values move with the theme.

Moon tightens the scale and Grass opens it out. Override them the way you would override a colour, and every rounded corner in the library follows.

Writing a theme

A theme is a @variant block that defines every token. Start by copying an existing one rather than from nothing — the build fails on the first token you miss, and the error names the rule rather than the token.

@import 'tailwindcss';
@import 'uniwind';
@import 'panelui-native/theme.css';

@source './node_modules/panelui-native/src';

@custom-variant sunset (&:where(.sunset, .sunset *));

@layer theme {
  :root {
    @variant sunset {
      --color-background: #fffaf5;
      --color-foreground: #2b1a12;
      /* …every remaining token… */
    }
  }
}

Then add sunset to extraThemes and restart the server.

Why theme.css declares its own variants

panelui-native/theme.css carries a @custom-variant line for each of the four named themes, which looks redundant next to extraThemes. It is not.

The variants Uniwind generates from extraThemes live in an artifact it produces by compiling theme.css — so on a fresh install, at the moment moon was first used, nothing had defined it yet. The dev server got away with it because it registers themes in memory; a production bundle failed with Cannot use @variant with unknown variant. Declared in the file itself the cycle does not exist, and extraThemes goes back to meaning only what it reads like it means: which themes can be switched to at runtime.

Next