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.
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
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.
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.
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.
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.
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.
Set shared placeholders and clear behavior through components. An instance prop overrides its configured default.
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 closing behavior
Modal: { maskClosable: false } prevents mask clicks from closing modals in the region. The close button, footer actions and Escape still work.
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.
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.
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
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.