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:
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.
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.
Your next good idea
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:
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:
Follow the system
Use useSystemAppearance and pass its result to theme.appearance to follow the operating system:
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:
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:
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:
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:
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:
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:
--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.