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/components/config-provider.md.

ConfigProvider

Set a shared language, theme and component defaults for an application or a local region. Nested providers inherit settings that they do not override.

Basic usage

Use theme to configure a region, including its popups. This example changes only the primary color.

basic.tsx
import { ConfigProvider, Form, FormField, Input, Select } from '@ifhover/leaf-ui';

export function ConfigProviderBasic() {
  return (
    <ConfigProvider theme={{ primaryColor: '#1d9bf0' }}>
      <Form onSubmit={(event) => event.preventDefault()}>
        <FormField label="Project name">
          <Input defaultValue="Leaf UI" />
        </FormField>
        <FormField label="Project type">
          <Select
            defaultValue="website"
            options={[
              { value: 'website', label: 'Website' },
              { value: 'app', label: 'Application' },
            ]}
          />
        </FormField>
      </Form>
    </ConfigProvider>
  );
}

Examples

Switch languages

Multilingual

locale changes built-in text such as date panels and empty states. Translate application headings, field labels and options separately.

Built-in languages

Languagelocale
Simplified Chinesezh-CN
Traditional Chinesezh-TW
Englishen-US
Japaneseja-JP
Koreanko-KR

The default language is Simplified Chinese, regardless of the documentation language. These five resources are included; other languages need translation resources.

Update locale, then open a date panel or the empty select to inspect the built-in text. Application labels stay unchanged.

locale.tsx
import { ConfigProvider, DatePicker, Flex, Form, FormField, Select } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function ConfigProviderLocale() {
  const [locale, setLocale] = useState('en-US');
  return (
    <Flex direction="column" gap="lg">
      <FormField label="Component language">
        <Select
          value={locale}
          onChange={setLocale}
          options={[
            { value: 'zh-CN', label: '简体中文' },
            { value: 'zh-TW', label: '繁體中文' },
            { value: 'en-US', label: 'English' },
            { value: 'ja-JP', label: '日本語' },
            { value: 'ko-KR', label: '한국어' },
          ]}
        />
      </FormField>
      <ConfigProvider locale={locale}>
        <Form onSubmit={(event) => event.preventDefault()}>
          <FormField label="Date">
            <DatePicker />
          </FormField>
          <FormField label="Empty options">
            <Select options={[]} />
          </FormField>
        </Form>
      </ConfigProvider>
    </Flex>
  );
}

Nested regions inherit the language unless overridden. direction sets text and interaction direction; weekStartsOn sets the first day of the week. Popups inherit these settings.

Add your own language

Pass resources keyed by language tag through translations. This example supplies three French entries; missing entries use English. The field labels remain application content.

translations.tsx
import { ConfigProvider, DatePicker, Form, FormField, type LeafTranslations, Select } from '@ifhover/leaf-ui';

const translations = {
  'fr-FR': {
    datePicker: { placeholder: 'Choisir une date' },
    select: { placeholder: 'Choisir une option', empty: 'Aucun résultat' },
  },
} satisfies LeafTranslations;

export function ConfigProviderTranslations() {
  return (
    <ConfigProvider locale={['fr-FR', 'en-US']} translations={translations}>
      <Form onSubmit={(event) => event.preventDefault()}>
        <FormField label="Date">
          <DatePicker />
        </FormField>
        <FormField label="Empty options">
          <Select options={[]} />
        </FormField>
      </Form>
    </ConfigProvider>
  );
}

locale={['fr-FR', 'en-US']} searches each entry in order, with built-in English as the final fallback. The first tag controls regional date and number formatting. A string is a one-item chain; empty arrays are invalid. Regional fallback such as fr-CA → fr is not added automatically.

Nested resources merge by language and entry. An omitted locale inherits the chain; an explicit value replaces it. Component text props and components defaults take precedence. For a complete resource, download the English JSON template. See Translation resources for types, JSON Schema and validation.

Regional density

density="compact" reduces control sizes and content spacing; the default is comfortable. Explicit theme and component sizes take precedence over the preset.

Comfortable
Compact
density.tsx
import { ConfigProvider, Flex, Form, FormField, Input, Select, Text } from '@ifhover/leaf-ui';

export function ConfigProviderDensity() {
  return (
    <Flex direction="column" gap="lg">
      {(['comfortable', 'compact'] as const).map((density) => (
        <ConfigProvider key={density} density={density}>
          <Flex direction="column" gap="sm">
            <Text tone="muted">{density === 'compact' ? 'Compact' : 'Comfortable'}</Text>
            <Form onSubmit={(event) => event.preventDefault()}>
              <FormField label="Project name">
                <Input defaultValue="Leaf UI" />
              </FormField>
              <FormField label="Owner">
                <Select
                  defaultValue="lin"
                  options={[
                    { value: 'lin', label: 'Lin' },
                    { value: 'alex', label: 'Alex' },
                  ]}
                />
              </FormField>
            </Form>
          </Flex>
        </ConfigProvider>
      ))}
    </Flex>
  );
}

Base height

Set theme.controlHeight to change the size baseline. Small and large sizes derive from it.

Current height: 34px
Small
Medium
Large
sizes.tsx
import { Button, ConfigProvider, Flex, FormField, Grid, Slider, Text } from '@ifhover/leaf-ui';
import { Fragment, useState } from 'react';

export function ConfigProviderSizes() {
  const [height, setHeight] = useState(34);
  return (
    <Flex direction="column" gap="lg">
      <FormField label="Base height">
        <Slider min={28} max={44} value={height} onChange={setHeight} showValue={false} />
      </FormField>
      <Text tone="muted">Current height: {height}px</Text>
      <ConfigProvider theme={{ controlHeight: height }}>
        <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
          {(
            [
              ['sm', 'Small'],
              ['md', 'Medium'],
              ['lg', 'Large'],
            ] as const
          ).map(([size, label]) => (
            <Fragment key={size}>
              <Text tone="muted">{label}</Text>
              <Flex align="start">
                <Button size={size}>Button</Button>
              </Flex>
            </Fragment>
          ))}
        </Grid>
      </ConfigProvider>
    </Flex>
  );
}

See Theming for appearance and tokens, and SSR for server rendering. theme.components sets component style tokens; components below sets default props.

Shared input defaults

Set shared placeholders and clear behavior through components. An instance prop overrides its configured default.

defaults.tsx
import { ConfigProvider, Form, FormField, Input } from '@ifhover/leaf-ui';

export function ConfigProviderDefaults() {
  return (
    <ConfigProvider components={{ Input: { placeholder: 'Enter a name', allowClear: true } }}>
      <Form onSubmit={(event) => event.preventDefault()}>
        <FormField label="Inherited defaults">
          <Input />
        </FormField>
        <FormField label="Instance override">
          <Input placeholder="Enter a team name" />
        </FormField>
      </Form>
    </ConfigProvider>
  );
}

Modal: { maskClosable: false } prevents mask clicks from closing modals in the region. The close button, footer actions and Escape still work.

modal-defaults.tsx
import { Button, ConfigProvider, Modal, Paragraph } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function ConfigProviderModalDefaults() {
  const [open, setOpen] = useState(false);
  return (
    <ConfigProvider components={{ Modal: { maskClosable: false } }}>
      <Button onClick={() => setOpen(true)}>Open dialog</Button>
      <Modal open={open} title="Keep current content" onClose={() => setOpen(false)}>
        <Paragraph>
          Clicking the mask keeps this dialog open. Use the close button, footer actions or Escape
          to close it.
        </Paragraph>
      </Modal>
    </ConfigProvider>
  );
}

Inheritance and overrides

The priority is instance props > inner defaults > outer defaults > built-in defaults.

Outer defaults
Inner override
Instance override
inheritance.tsx
import { Button, ConfigProvider, Flex, Grid, Text } from '@ifhover/leaf-ui';

export function ConfigProviderInheritance() {
  return (
    <ConfigProvider components={{ Button: { size: 'sm' } }}>
      <Grid columns={1} gap={24}>
        <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
          <Text tone="muted">Outer defaults</Text>
          <Flex align="start">
            <Button>Continue</Button>
          </Flex>
        </Grid>
        <ConfigProvider components={{ Button: { size: 'lg' } }}>
          <Grid columns={1} gap={24}>
            <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
              <Text tone="muted">Inner override</Text>
              <Flex align="start">
                <Button>Continue</Button>
              </Flex>
            </Grid>
            <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
              <Text tone="muted">Instance override</Text>
              <Flex align="start">
                <Button size="md">Continue</Button>
              </Flex>
            </Grid>
          </Grid>
        </ConfigProvider>
      </Grid>
    </ConfigProvider>
  );
}

Defaults merge by component and prop. Only undefined falls back; values such as false, 0 and empty strings are retained. Objects, arrays, class names and callbacks replace the previous value rather than merging.

Clear inherited defaults

Set a component entry to null to restore its built-in defaults in that region. An empty object or undefined continues to inherit. Other components and the theme are unaffected.

reset.tsx
import { ConfigProvider, Form, FormField, Input, type LeafComponentDefaults } from '@ifhover/leaf-ui';

const defaults = { Input: { readOnly: true } } satisfies LeafComponentDefaults;

export function ConfigProviderReset() {
  return (
    <ConfigProvider components={defaults}>
      <Form onSubmit={(event) => event.preventDefault()}>
        <FormField label="Inherited defaults">
          <Input defaultValue="Read-only content" />
        </FormField>
        <ConfigProvider components={{ Input: null }}>
          <FormField label="Cleared defaults">
            <Input defaultValue="Editable content" />
          </FormField>
        </ConfigProvider>
      </Form>
    </ConfigProvider>
  );
}

Use LeafComponentDefaults to check reusable configuration. Keys match public component names; DataTable uses only the DataTable key. Aliases use their canonical key, such as FloatButton for FAB. See the complete defaults reference.

Keep instance data, controlled state and events on each component. Pass a new configuration object when updating it. Internal controls are configured through their owner, such as Modal.confirmButtonProps; global Button defaults do not apply to them.

API

ConfigProvider API

PropertyTypeDefaultDescription
localeLeafLocale | readonly LeafLocale[]'zh-CN'Current language and per-entry fallback order; inherited when omitted
translationsReadonly<Record<string, LeafTranslation>>—JSON resources indexed by language tag; nested entries merge
themeLeafTheme—Regional settings; omitted fields inherit
density'comfortable' | 'compact''comfortable'Inherited controls, forms, menus, lists and overlay spacing; explicit sizes override the preset.
componentsLeafComponentDefaults—Regional component defaults, inherited by component and prop.
direction'ltr' | 'rtl'—Text and interaction direction.
weekStartsOn0 | 1 | 2 | 3 | 4 | 5 | 6—First day of the week; 0 is Sunday and 1 is Monday.
getPopupContainer() => Element | DocumentFragment—Return a popup container, including a ShadowRoot.
maskBlurbooleanfalseEnable mask blur for Modal, Drawer and Modal-based overlays such as confirmations and command palettes. Disable to reduce rendering cost; nested providers inherit it.

Native div props, className and style apply to the region wrapper. The default is a translucent gray mask without blur; maskBlur={true} explicitly enables blur; this is independent of theme.motion.

LeafTheme

Common theme options. Unspecified fields inherit from the outer region.

PropertyTypeDefaultDescription
primaryColorstring'#007aff'Primary base color shared by light and dark appearances; interaction colors are derived automatically.
appearance'light' | 'dark''light'Light or dark; inherits explicit ancestor settings
borderRadiusnumber | string10Base radius; small tags use × 0.5, sm/lg controls use × 0.8/1.2, and surface/popup radii use × 1.4/1.6.
controlHeightnumber | string34Base height; small / large heights use − / + 6px
fontSizenumber | string14Base font; small font − 1px, large font + 2px
fontFamilystringSystem sans-serifFont family
motionbooleantrueEnable interaction motion in this region; reduced-motion preferences take precedence and portals inherit it.
spacingnumber—Base spacing; other spacing values are derived.
lineHeightnumber | string20Body line height. Numbers are pixels, except numbers greater than 0 and up to 4 which keep the legacy multiplier meaning; strings are CSS lengths.
headingWeight400 | 500 | 700700Card and Typography heading weight, default 700; other component labels use tokens.fontWeight, default 500.
elevation'none' | 'soft' | 'medium'—Overall shadow strength.
breakpointsPartial<Record<'xs' | 'sm' | 'md' | 'lg' | 'xl', number>>—Responsive thresholds used by useBreakpoint.
tokensLeafThemeTokens—Optional advanced overrides
componentsRecord<string, LeafComponentTokens>—Override local styles by component name.