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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/en/guide/theming.md.

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:

basic.tsx
import { Button, ConfigProvider } from '@ifhover/leaf-ui';

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

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.

SettingExamplePurpose
primaryColor'#7654c6'Set the primary base and generate seven semantic shades; the color is not rewritten.
borderRadius10Set the base radius; use 0 for square corners.
appearance'light' / 'dark'Choose light or dark appearance.
controlHeight40Set the base single-line control height; small and large sizes follow.
fontSize14Set the base component font size.
lineHeight20Set 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.
motionfalseDisable 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 for all theme fields. For individual text colors, backgrounds or sizes, use 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.

StyleAppearance
defaultThe unmodified library defaults, with no additional theme tokens.
illustrationContrasting borders, vivid colors and offset hard shadows.
windows-xpSmall corners, Tahoma typography, beveled highlights and a gradient card header.
materialMUI-inspired shapes, 4px corners and layered elevation.
skeuomorphicSoft surfaces, two-sided relief shadows and an inset pressed effect.

Your next good idea

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>
  );
}

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:

<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 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:

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>
  );
}

Follow the system

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

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:

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>
  );
}

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:

<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 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:

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 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:

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

See 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.

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:

<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 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:

<ConfigProvider theme={{ appearance: 'dark' }}>
  <section className="app-panel">Application content</section>
</ConfigProvider>
.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 variablePurpose
--leaf-color-primaryCurrent 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-activeSoft semantic surfaces and feedback fills.
--leaf-color-<family>-borderScale-mapped semantic borders.
--leaf-color-<family>-inkReadable semantic text on ordinary surfaces.
--leaf-color-primary-indicatorPrimary selected, progress and outline indicators.
--leaf-color-primary-focusPrimary focus feedback, used by Input and Select by default; other fields and buttons retain their own focus styles.
--leaf-color-primary-fill-borderSupporting 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-infoContent colors on solid fills.
--leaf-color-text / --leaf-color-text-mutedPrimary and secondary text.
--leaf-color-surface / --leaf-color-surface-mutedContent and supporting backgrounds.
--leaf-color-borderBorder color.
--leaf-color-option-hoverNeutral feedback fill for options, menus and candidate rows.
--leaf-border-widthOuter border width.
--leaf-control-shadow / --leaf-surface-shadowControl and content surface shadows.
--leaf-radiusBase 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 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 for setup, server-side rendering for frameworks such as Next.js, and Browser compatibility for support targets.