> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/en/guide/theming.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt.

# Theming

Set colors, corner radii and dark mode through ConfigProvider's `theme`. A few settings are usually enough; related styles update automatically.

## Change colors and corners

Wrap your application in ConfigProvider. This example uses a purple primary color and an 8px base radius:


Save changes

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/theming/basic.tsx"
import { Button, ConfigProvider } from '@ifhover/leaf-ui';

export function ThemeBasic() {
  return (
    <ConfigProvider theme={{ primaryColor: '#7654c6', borderRadius: 8 }}>
      <Button>Save changes</Button>
    </ConfigProvider>
  );
}
```

Expand code

Replace Button with your application content. Buttons, fields, selectors and popups share the theme. Hover, pressed and focus colors derive automatically.

`primaryColor` is a base input. The library keeps the supplied color and generates seven semantic shades: `light-3`, `light-7`, `light-9`, `dark-1`, `dark-3`, `dark-7` and `dark-9`. Light and dark modes share the bases and semantic shades, switching only neutral roles and the `soft`, `border` and `ink` mappings; neutral keeps its `100`–`900` scale.

Text on solid fills defaults to white. Set `theme.tokens.onPrimaryColor` to `#000000` for black text. Change colors through ConfigProvider JS configuration; DOM style changes do not trigger JS palette recalculation.

`borderRadius` sets the base radius. Cards, dialogs and other surfaces derive radii for their own level, so you do not need to configure each component. Numbers represent pixels; CSS lengths such as `'0.5rem'` also work.

### Common settings

These fields all belong inside `theme`. Set only what you want to change.

| Setting         | Example               | Purpose                                                                                                                      |
| --------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `primaryColor`  | `'#7654c6'`           | Set the primary base and generate seven semantic shades; the color is not rewritten.                                         |
| `borderRadius`  | `10`                  | Set the base radius; use `0` for square corners.                                                                             |
| `appearance`    | `'light'` / `'dark'`  | Choose light or dark appearance.                                                                                             |
| `controlHeight` | `40`                  | Set the base single-line control height; small and large sizes follow.                                                       |
| `fontSize`      | `14`                  | Set the base component font size.                                                                                            |
| `lineHeight`    | `20`                  | Set the body line height; numbers are pixels, `1`–`4` keep the legacy multiplier meaning, and CSS lengths are also accepted. |
| `fontFamily`    | `'Inter, sans-serif'` | Set the font family; your application loads the font files.                                                                  |
| `motion`        | `false`               | Disable regional animations while keeping interactions available.                                                            |

Unspecified fields inherit the outer configuration. Defaults are light appearance, an 8px base radius, 34px base control height, 14px font size and a 20px body line height.

See [LeafTheme](https://ifhover.github.io/leaf-ui/en/components/config-provider.md#leaftheme) for all theme fields. For individual text colors, backgrounds or sizes, use [LeafThemeTokens](https://ifhover.github.io/leaf-ui/en/api/theme-tokens.md#leafthemetokens).

## Copy a theme example

The following example includes complete definitions for default, illustration, Windows XP, Material and skeuomorphic styles. Copy the source into your project and pass the resulting `LeafTheme` object to `ConfigProvider`. These definitions live in the example source and can be edited directly.

| Style          | Appearance                                                                       |
| -------------- | -------------------------------------------------------------------------------- |
| `default`      | The unmodified library defaults, with no additional theme tokens.                |
| `illustration` | Contrasting borders, vivid colors and offset hard shadows.                       |
| `windows-xp`   | Small corners, Tahoma typography, beveled highlights and a gradient card header. |
| `material`     | MUI-inspired shapes, 4px corners and layered elevation.                          |
| `skeuomorphic` | Soft surfaces, two-sided relief shadows and an inset pressed effect.             |


Default

Illustration

Windows XP

Material

Skeuomorphic

**#1e964f

### Your next good idea

Create projectMaybe later

presets.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/theming/presets.tsx"
import { Button, Card, ColorPicker, ConfigProvider, Flex, Input, type LeafTheme, Select, Space, Tabs } from '@ifhover/leaf-ui';
import { useState } from 'react';

export type ThemeStyle = 'default' | 'illustration' | 'windows-xp' | 'material' | 'skeuomorphic';

export function createExampleTheme(style: ThemeStyle, primaryColor?: string): LeafTheme {
  const base: LeafTheme = primaryColor ? { primaryColor } : {};
  if (style === 'default') return base;
  if (style === 'illustration') {
    return {
      ...base,
      borderRadius: 4,
      tokens: {
        borderWidth: 2,
        borderColor: 'color-mix(in srgb, var(--leaf-color-primary) 12%, var(--leaf-color-text))',
        mutedSurfaceColor:
          'color-mix(in srgb, var(--leaf-color-primary) 8%, var(--leaf-color-surface))',
        controlShadow: '3px 3px 0 var(--leaf-color-border)',
        surfaceShadow: '6px 6px 0 var(--leaf-color-border)',
      },
    };
  }
  if (style === 'windows-xp') {
    const bevel = 'inset 1px 1px 0 rgb(255 255 255 / 0.7), inset -1px -1px 0 rgb(0 0 0 / 0.18)';
    return {
      ...base,
      borderRadius: 3,
      fontFamily: 'Tahoma, "Microsoft YaHei", sans-serif',
      tokens: {
        borderColor:
          'color-mix(in srgb, var(--leaf-color-primary) 45%, var(--leaf-color-text-muted))',
        mutedSurfaceColor:
          'color-mix(in srgb, var(--leaf-color-primary) 6%, var(--leaf-color-surface))',
        controlShadow: `${bevel}, 0 1px 2px rgb(0 0 0 / 0.12)`,
        surfaceShadow: `${bevel}, 2px 3px 6px rgb(0 0 0 / 0.18)`,
      },
      components: {
        Card: {
          headerBackground:
            'linear-gradient(180deg, color-mix(in srgb, var(--leaf-color-primary) 28%, var(--leaf-color-surface)), color-mix(in srgb, var(--leaf-color-primary) 8%, var(--leaf-color-surface)) 48%, color-mix(in srgb, var(--leaf-color-primary) 14%, var(--leaf-color-surface)))',
        },
        Button: {
          active: { shadow: 'inset 1px 2px 3px rgb(0 0 0 / 0.25)' },
        },
      },
    };
  }
  if (style === 'material') {
    return {
      ...base,
      borderRadius: 4,
      fontFamily: 'Roboto, "Inter Variable", "Microsoft YaHei", sans-serif',
      tokens: {
        surfaceShadow: '0 3px 8px rgb(0 0 0 / 0.12), 0 1px 3px rgb(0 0 0 / 0.1)',
      },
      components: {
        Button: {
          shadow: '0 2px 3px rgb(0 0 0 / 0.16), 0 1px 2px rgb(0 0 0 / 0.1)',
          hover: { shadow: '0 4px 8px rgb(0 0 0 / 0.2)' },
          active: { shadow: '0 1px 2px rgb(0 0 0 / 0.18)' },
        },
      },
    };
  }
  const highlight = 'light-dark(rgb(255 255 255 / 0.95), rgb(255 255 255 / 0.06))';
  const shade = 'light-dark(rgb(0 0 0 / 0.16), rgb(0 0 0 / 0.5))';
  return {
    ...base,
    borderRadius: 14,
    tokens: {
      surfaceColor:
        'light-dark(color-mix(in srgb, var(--leaf-color-primary) 3%, #eef0f3), color-mix(in srgb, var(--leaf-color-primary) 3%, #26282d))',
      mutedSurfaceColor:
        'color-mix(in srgb, var(--leaf-color-primary) 5%, var(--leaf-color-surface))',
      borderColor: 'color-mix(in srgb, var(--leaf-color-text) 12%, var(--leaf-color-surface))',
      controlShadow: `3px 3px 7px ${shade}, -3px -3px 7px ${highlight}, inset 0 1px 0 ${highlight}`,
      surfaceShadow: `6px 6px 14px ${shade}, -6px -6px 14px ${highlight}`,
    },
    components: {
      Button: {
        active: { shadow: `inset 3px 3px 6px ${shade}, inset -3px -3px 6px ${highlight}` },
      },
    },
  };
}

export function ThemePresets() {
  const [preset, setPreset] = useState<ThemeStyle>('illustration');
  const [color, setColor] = useState('#1e964f');
  return (
    <ConfigProvider theme={createExampleTheme(preset, color)}>
      <Flex direction="column" gap="md">
        <Tabs
          type="card"
          aria-label="Theme style"
          activeKey={preset}
          onChange={(key) => setPreset(key as ThemeStyle)}
          items={[
            { key: 'default', label: 'Default' },
            { key: 'illustration', label: 'Illustration' },
            { key: 'windows-xp', label: 'Windows XP' },
            { key: 'material', label: 'Material' },
            { key: 'skeuomorphic', label: 'Skeuomorphic' },
          ]}
        />
        <ColorPicker
          aria-label="Primary color"
          value={color}
          onChange={setColor}
          format="hex"
          disableAlpha
          showText
        />
        <Card title="Your next good idea">
          <Flex direction="column" gap="md">
            <Input aria-label="Project name" placeholder="Name your project" />
            <Select
              aria-label="Project type"
              defaultValue="design"
              options={[
                { value: 'design', label: 'Design' },
                { value: 'development', label: 'Development' },
              ]}
            />
            <Space wrap>
              <Button>Create project</Button>
              <Button variant="outline">Maybe later</Button>
            </Space>
          </Flex>
        </Card>
      </Flex>
    </ConfigProvider>
  );
}
```

Expand code

The default style adds no tokens. Omit `density` for its default value. Active, focus and primary label colors come from the library, while buttons keep their resting appearance on hover, so these values do not need to be copied into your configuration. The examples only customize shadow feedback where the style calls for it.

Custom styles only define their differences: radius, border width, a global `tokens.borderColor`, shadows, and tinted surfaces using `color-mix()`. A single border color applies to all component frames, including solid buttons, switches, cards, tables and popups. Individual component overrides take precedence; error and selected states keep their meaning. Components that are borderless by design stay borderless.

`createExampleTheme('illustration', '#1d9bf0')` sets the primary color. Tinted surfaces and borders use `var(--leaf-color-primary)`, and shadows reuse `var(--leaf-color-border)`, so they update automatically without listing a new palette for each color. Omit the color argument to inherit the surrounding theme. Base surfaces keep the library's automatic light/dark palette; tinted backgrounds mix the primary color into those surfaces.

Windows XP and Material are style examples made with Leaf UI theme settings. Windows XP keeps the current primary color and uses bevels, typography and a gradient for a retro feel. Material uses locally available Roboto or fallback fonts. The skeuomorphic style uses `light-dark()` for light/dark surfaces and `color-mix()` to tint them with the primary color; neutral bases and lighting do not need a separate palette for each primary color. Component overrides only customize the card header gradient and button shadow feedback; global borders and shadows remain shared.

Changing styles keeps child components mounted, preserving input and selection values. Popups and service feedback inherit their calling region's theme. Expand the example source to view the complete theme definitions and copy them into your project's `ConfigProvider`. Applications provide their own illustrations, textures and font files.

## Use dark mode

Set `appearance: 'dark'`. Use `'light'` to switch back:

```tsx
<ConfigProvider theme={{ appearance: 'dark' }}>
  <App />
</ConfigProvider>
```

Component text, backgrounds and borders change together. When `primaryColor` is omitted, light and dark modes share the same default semantic bases. An explicit primary color keeps its value: black buttons retain a black fill and white labels in dark mode, with a subtle boundary when needed. Both appearances share the five semantic bands and the neutral scale; only neutral roles and mapped `soft`, `border` and `ink` steps switch.

Primary and status labels use mapped readable ink while solid fills retain their original colors. Input and Select use a primary focus border; other fields retain neutral focus. Explicit foreground, focus and interaction settings take precedence. CSS color expressions are preserved without DOM-based numeric resolution.

ConfigProvider styles the components in its region. It does not add a background to the page's `body`. To update your own page backgrounds and text, use the [CSS variables](#use-the-theme-in-application-css) below.

### Add an appearance switch

Theme settings are ordinary React props, so state can update them. Toggle the switch below to change the card, button and text together:


Dark modeSave changes

appearance.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/theming/appearance.tsx"
import { Button, Card, ConfigProvider, Flex, Switch } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function ThemeAppearance() {
  const [dark, setDark] = useState(false);

  return (
    <ConfigProvider theme={{ appearance: dark ? 'dark' : 'light' }}>
      <Card>
        <Flex direction="column" gap="md" align="start">
          <Switch checked={dark} onChange={(event) => setDark(event.target.checked)}>
            Dark mode
          </Switch>
          <Button>Save changes</Button>
        </Flex>
      </Card>
    </ConfigProvider>
  );
}
```

Expand code

### Follow the system

Use `useSystemAppearance` and pass its result to `theme.appearance` to follow the operating system:

```tsx
import { ConfigProvider, useSystemAppearance } from '@ifhover/leaf-ui';

export function AppTheme() {
  const appearance = useSystemAppearance('light');

  return (
    <ConfigProvider theme={{ appearance }}>
      <App />
    </ConfigProvider>
  );
}
```

The `'light'` argument is the initial appearance. After mounting, the hook reads and watches system preferences. Your application stores manual choices and decides when to keep following the system.

## Theme one region

Nest another ConfigProvider to theme a specific area. The inner provider overrides only the supplied fields and inherits the rest:


Global blue

Local purple

scoped.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/theming/scoped.tsx"
import { Button, ConfigProvider, Flex } from '@ifhover/leaf-ui';

export function ThemeScoped() {
  return (
    <ConfigProvider theme={{ primaryColor: '#1677ff', borderRadius: 8 }}>
      <Flex direction="column" gap="md" align="start">
        <Button>Global blue</Button>
        <ConfigProvider theme={{ primaryColor: '#7654c6' }}>
          <Button>Local purple</Button>
        </ConfigProvider>
      </Flex>
    </ConfigProvider>
  );
}
```

Expand code

Both buttons use an 8px base radius. The inner provider changes only the primary color to purple. Select popups, Modal, and feedback created with `useConfirm` or `useMessage` also use their calling region's theme.

## Adjust control size and density

For one control, prefer its `size="sm"` or `size="lg"` prop. To make an entire region more compact, set ConfigProvider's `density`:

```tsx
<ConfigProvider density="compact">
  <App />
</ConfigProvider>
```

`density` is a sibling of `theme`. It defaults to `'comfortable'`. The `'compact'` preset tightens control, form and popup spacing and changes the base control height from 34px to 30px without reducing text size.

Set `theme.controlHeight` when you need an explicit height; it overrides the density preset. For example, `controlHeight: 40` produces 34px / 40px / 46px controls. See [ConfigProvider](https://ifhover.github.io/leaf-ui/en/components/config-provider.md#base-height) for a size comparison.

## Advanced customization

Use the settings below when your design needs more specific overrides. For colors, corners and appearance, the basic settings above are sufficient.

### Override individual colors or sizes

Use `theme.tokens` for specific styles beyond the basic settings. This example adjusts the success color, large radius and animation duration:

```tsx
import type { LeafTheme } from '@ifhover/leaf-ui';

const theme = {
  primaryColor: '#7654c6',
  borderRadius: 8,
  tokens: {
    successColor: '#1e964f',
    borderRadiusLg: 18,
    motionDuration: 160,
  },
} satisfies LeafTheme;
```

Pass this object to `<ConfigProvider theme={theme}>`. Here, `borderRadiusLg` overrides the derived large radius, and numeric `motionDuration` values are milliseconds. See [LeafThemeTokens](https://ifhover.github.io/leaf-ui/en/api/theme-tokens.md#leafthemetokens) for the complete reference.

For a very light primary color, use `tokens.onPrimaryColor` to set the text color on solid primary buttons. Check readability in normal, pressed and disabled states after changing your palette. `motion: false` disables regional animations; system reduced-motion preferences always take precedence.

### Style one component type

`theme.components` assigns styles by component name. For example, use 4px button corners and change card padding:

```tsx
<ConfigProvider
  theme={{
    components: {
      Button: { borderRadius: 4 },
      Card: { padding: 24 },
    },
  }}
>
  <App />
</ConfigProvider>
```

See [LeafComponentTokens](https://ifhover.github.io/leaf-ui/en/api/theme-tokens.md#leafcomponenttokens) for style fields, and each component's documentation for the fields it supports.

`theme.components` changes styles. To set default button `size`, `variant` or other component props, use ConfigProvider's separate `components` prop; see [Component defaults](https://ifhover.github.io/leaf-ui/en/components/config-provider.md#component-defaults).

### Borders, shadows and interaction states

`tokens.borderWidth` sets outer borders on controls and content surfaces. `controlShadow` and `surfaceShadow` set control and content surface shadows. Section dividers keep their own fine lines. Component `borderWidth` and `shadow` take precedence over global values.

Components supporting state overrides also accept `hover`, `active`, `focus` and `disabled` colors, backgrounds, border colors and shadows:

```tsx
<ConfigProvider
  theme={{
    tokens: { borderWidth: 2, controlShadow: '3px 3px 0 #252525' },
    components: {
      Button: {
        borderColor: '#252525',
        hover: { shadow: '4px 4px 0 #252525' },
        active: { shadow: '1px 1px 0 #252525' },
        disabled: { shadow: 'none' },
      },
      Input: { focus: { borderColor: '#7654c6', shadow: '0 0 0 3px #7654c630' } },
    },
  }}
>
  <App />
</ConfigProvider>
```

State settings change appearance without changing events, dimensions, disabled or read-only behavior, or removing visible keyboard focus feedback. Nested providers merge each state's fields; `undefined` inherits. See [theme tokens](https://ifhover.github.io/leaf-ui/en/api/theme-tokens.md#leafcomponenttokens) for fields and support scope.

### Use the theme in application CSS

ConfigProvider exposes `--leaf-*` CSS variables within its region. Your own content can read them to follow color and appearance changes:

```tsx
<ConfigProvider theme={{ appearance: 'dark' }}>
  <section className="app-panel">Application content</section>
</ConfigProvider>
```

```css
.app-panel {
  padding: 16px;
  color: var(--leaf-color-text);
  background: var(--leaf-color-surface);
  border: 1px solid var(--leaf-color-border);
  border-radius: var(--leaf-radius);
}
```

| Common variable                                                                   | Purpose                                                                                                              |
| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `--leaf-color-primary`                                                            | Current primary color.                                                                                               |
| `--leaf-color-<family>-{light-3,light-7,light-9,dark-1,dark-3,dark-7,dark-9}`     | Seven shared semantic shades; `<family>` is primary, success, danger, warning or info.                               |
| `--leaf-color-neutral-{100..900}`                                                 | The nine-step neutral scale, shared by light and dark modes.                                                         |
| `--leaf-color-<family>-soft` / `-soft-hover` / `-soft-active`                     | Soft semantic surfaces and feedback fills.                                                                           |
| `--leaf-color-<family>-border`                                                    | Scale-mapped semantic borders.                                                                                       |
| `--leaf-color-<family>-ink`                                                       | Readable semantic text on ordinary surfaces.                                                                         |
| `--leaf-color-primary-indicator`                                                  | Primary selected, progress and outline indicators.                                                                   |
| `--leaf-color-primary-focus`                                                      | Primary focus feedback, used by Input and Select by default; other fields and buttons retain their own focus styles. |
| `--leaf-color-primary-fill-border`                                                | Supporting boundary for primary selections such as dates; solid buttons do not use this role.                        |
| `--leaf-color-on-primary` / `on-success` / `on-danger` / `on-warning` / `on-info` | Content colors on solid fills.                                                                                       |
| `--leaf-color-text` / `--leaf-color-text-muted`                                   | Primary and secondary text.                                                                                          |
| `--leaf-color-surface` / `--leaf-color-surface-muted`                             | Content and supporting backgrounds.                                                                                  |
| `--leaf-color-border`                                                             | Border color.                                                                                                        |
| `--leaf-color-option-hover`                                                       | Neutral feedback fill for options, menus and candidate rows.                                                         |
| `--leaf-border-width`                                                             | Outer border width.                                                                                                  |
| `--leaf-control-shadow` / `--leaf-surface-shadow`                                 | Control and content surface shadows.                                                                                 |
| `--leaf-radius`                                                                   | Base radius.                                                                                                         |

`--leaf-color-primary-soft` and the other `*-soft` roles are always derived from the semantic shades; settings such as `primarySoftColor` provide explicit overrides only. `ink` uses the base color when it reaches 4.5:1, otherwise a readable derived shade; the primary indicator similarly prefers the base at 3:1 and falls back to a readable shade. Prefer purpose roles over constructing shade values in application code.

Configure Leaf UI component themes through ConfigProvider and read the results from application CSS. Changing a single base CSS variable does not regenerate the full set of interaction colors.

For Tailwind CSS, import the package configuration to reuse the theme through utilities such as `bg-leaf-surface` and `text-leaf-primary`. See [Tailwind CSS](https://ifhover.github.io/leaf-ui/en/guide/tailwindcss.md) for Tailwind 3 / 4 setup.

## Server rendering

Use the same appearance for the server and the client's initial render. To remember a user's choice, read a cookie on the server and supply that initial value. System appearance updates after mounting.

Prefer concrete HEX, RGB or HSL colors. Solid foregrounds default to white; verify their contrast yourself. Expressions remain CSS expressions: they are not resolved to numeric scales after mounting or synchronized from DOM changes.

See [Installation & quick start](https://ifhover.github.io/leaf-ui/en/guide/getting-started.md) for setup, [server-side rendering](https://ifhover.github.io/leaf-ui/en/guide/ssr.md) for frameworks such as Next.js, and [Browser compatibility](https://ifhover.github.io/leaf-ui/en/guide/compatibility.md) for support targets.
