> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/config-provider.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.

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


Project name

Project type

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/config-provider/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>
  );
}
```

Expand code


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

| Language            | `locale` |
| ------------------- | -------- |
| Simplified Chinese  | `zh-CN`  |
| Traditional Chinese | `zh-TW`  |
| English             | `en-US`  |
| Japanese            | `ja-JP`  |
| Korean              | `ko-KR`  |

The default language is Simplified Chinese, regardless of the documentation language. These five resources are included; other languages need [translation resources](#add-your-own-language).

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


Component language

Date

Empty options

locale.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/config-provider/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>
  );
}
```

Expand code

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.


Date

Empty options

translations.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/config-provider/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>
  );
}
```

Expand code

`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
](/leaf-ui/locales/en-US.json). See [Translation resources](https://ifhover.github.io/leaf-ui/en/api/translations.md)
 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

Project name

Owner

Compact

Project name

Owner

density.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/config-provider/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>
  );
}
```

Expand code

### Base height

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


Base height

Current height: 34px

Small

Button

Medium

Button

Large

Button

sizes.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/config-provider/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>
  );
}
```

Expand code

See [Theming](https://ifhover.github.io/leaf-ui/en/guide/theming.md) for appearance and tokens, and [SSR](https://ifhover.github.io/leaf-ui/en/guide/ssr.md) 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.


Inherited defaults

Instance override

defaults.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/config-provider/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>
  );
}
```

Expand code

### Modal closing behavior

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


Open dialog

modal-defaults.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/config-provider/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>
  );
}
```

Expand code

### Inheritance and overrides

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


Outer defaults

Continue

Inner override

Continue

Instance override

Continue

inheritance.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/config-provider/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>
  );
}
```

Expand code

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.


Inherited defaults

Cleared defaults

reset.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/config-provider/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>
  );
}
```

Expand code

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](https://ifhover.github.io/leaf-ui/en/api/component-defaults.md#leafcomponentdefaults).

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

| Property            | Type                                                                                                                        | Default         | Description                                                                                                                                                            |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `locale`            | `LeafLocale \| readonly LeafLocale[]`                                                                                       | `'zh-CN'`       | Current language and per-entry fallback order; inherited when omitted                                                                                                  |
| `translations`      | `Readonly<Record<string, `[`LeafTranslation`](https://ifhover.github.io/leaf-ui/en/api/translations.md#leaftranslation)`>>` | —               | JSON resources indexed by language tag; nested entries merge                                                                                                           |
| `theme`             | [`LeafTheme`](#leaftheme)                                                                                                   | —               | Regional settings; omitted fields inherit                                                                                                                              |
| `density`           | `'comfortable' \| 'compact'`                                                                                                | `'comfortable'` | Inherited controls, forms, menus, lists and overlay spacing; explicit sizes override the preset.                                                                       |
| `components`        | [`LeafComponentDefaults`](https://ifhover.github.io/leaf-ui/en/api/component-defaults.md#leafcomponentdefaults)             | —               | Regional component defaults, inherited by component and prop.                                                                                                          |
| `direction`         | `'ltr' \| 'rtl'`                                                                                                            | —               | Text and interaction direction.                                                                                                                                        |
| `weekStartsOn`      | `0 \| 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.                                                                                                                      |
| `maskBlur`          | `boolean`                                                                                                                   | `false`         | Enable 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.

| Property        | Type                                                                                                                      | Default           | Description                                                                                                                                        |
| --------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `primaryColor`  | `string`                                                                                                                  | `'#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                                                                                                 |
| `borderRadius`  | `number \| string`                                                                                                        | `10`              | Base radius; small tags use × 0.5, sm/lg controls use × 0.8/1.2, and surface/popup radii use × 1.4/1.6.                                            |
| `controlHeight` | `number \| string`                                                                                                        | `34`              | Base height; small / large heights use − / + 6px                                                                                                   |
| `fontSize`      | `number \| string`                                                                                                        | `14`              | Base font; small font − 1px, large font + 2px                                                                                                      |
| `fontFamily`    | `string`                                                                                                                  | System sans-serif | Font family                                                                                                                                        |
| `motion`        | `boolean`                                                                                                                 | `true`            | Enable interaction motion in this region; reduced-motion preferences take precedence and portals inherit it.                                       |
| `spacing`       | `number`                                                                                                                  | —                 | Base spacing; other spacing values are derived.                                                                                                    |
| `lineHeight`    | `number \| string`                                                                                                        | `20`              | Body line height. Numbers are pixels, except numbers greater than 0 and up to 4 which keep the legacy multiplier meaning; strings are CSS lengths. |
| `headingWeight` | `400 \| 500 \| 700`                                                                                                       | `700`             | Card and Typography heading weight, default 700; other component labels use `tokens.fontWeight`, default 500.                                      |
| `elevation`     | `'none' \| 'soft' \| 'medium'`                                                                                            | —                 | Overall shadow strength.                                                                                                                           |
| `breakpoints`   | `Partial<Record<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl', number>>`                                                           | —                 | Responsive thresholds used by useBreakpoint.                                                                                                       |
| `tokens`        | [`LeafThemeTokens`](https://ifhover.github.io/leaf-ui/en/api/theme-tokens.md#leafthemetokens)                             | —                 | Optional advanced overrides                                                                                                                        |
| `components`    | `Record<string, `[`LeafComponentTokens`](https://ifhover.github.io/leaf-ui/en/api/theme-tokens.md#leafcomponenttokens)`>` | —                 | Override local styles by component name.                                                                                                           |
