ConfigProvider

Context provider for global configuration. Enables consistent component sizing, localization, RTL support, and portal container management across your application.

Import

import { ConfigProvider, useConfig } from 'asterui'

Usage

Basic Setup

Wrap your app with ConfigProvider to set global defaults:

main.tsx

import { ConfigProvider } from 'asterui'

createRoot(document.getElementById('root')!).render(
  <ConfigProvider componentSize="sm">
    <App />
  </ConfigProvider>
)

Component Size

Set a global size for all components. Individual components can still override this:

function App() {
  const [size, setSize] = useState<'xs' | 'sm' | 'md' | 'lg' | 'xl'>('md')

  return (
    <ConfigProvider componentSize={size}>
      <div className="space-y-4">
        <select value={size} onChange={(e) => setSize(e.target.value)}>
          <option value="xs">Extra Small</option>
          <option value="sm">Small</option>
          <option value="md">Medium</option>
          <option value="lg">Large</option>
          <option value="xl">Extra Large</option>
        </select>

        {/* All these components will use the global size */}
        <Button>Button</Button>
        <Input placeholder="Input" />
        <Pagination total={100} />
      </div>
    </ConfigProvider>
  )
}

Localization

Customize locale strings for internationalization:

import { ConfigProvider } from 'asterui'
import { zhCN } from 'asterui/locale'

// Use a built-in locale
<ConfigProvider locale={zhCN}>
  <App />
</ConfigProvider>

// Or provide custom strings
<ConfigProvider locale={{ Empty: { description: 'Keine Daten' } }}>
  <Empty />
</ConfigProvider>

RTL Support

Enable right-to-left layout for languages like Arabic and Hebrew:

<ConfigProvider direction="rtl">
  <div dir="rtl">
    <Button>First</Button>
    <Button>Second</Button>
    <Button>Third</Button>
  </div>
</ConfigProvider>

Nested Providers

Nested ConfigProvider components inherit and override parent settings:

<ConfigProvider componentSize="lg">
  <Button>Large Button</Button>

  <ConfigProvider componentSize="sm">
    {/* This section uses small size */}
    <Button>Small Button</Button>
  </ConfigProvider>
</ConfigProvider>

Portal Container

Specify where modals, dropdowns, and other portals render:

<ConfigProvider getPopupContainer={() => document.getElementById('modal-root')!}>
  <Modal open={isOpen}>
    {/* Renders inside #modal-root instead of document.body */}
  </Modal>
</ConfigProvider>

Global Disabled State

Disable all interactive components at once, useful during form submission or loading:

function App() {
  const [submitting, setSubmitting] = useState(false)

  return (
    <ConfigProvider componentDisabled={submitting}>
      <Input placeholder="Username" />
      <Input placeholder="Password" type="password" />
      <Button onClick={handleSubmit}>
        {submitting ? 'Submitting...' : 'Submit'}
      </Button>
    </ConfigProvider>
  )
}

Custom Empty States

Provide a custom renderer for empty states across components:

<ConfigProvider
  renderEmpty={(componentName) => (
    <div className="text-center py-8">
      <Icon name="inbox" className="text-4xl text-base-content/30" />
      <p className="mt-2 text-base-content/50">
        {componentName === 'Table' ? 'No records found' : 'Nothing here'}
      </p>
    </div>
  )}
>
  <Table dataSource={[]} columns={columns} />
  <Select options={[]} />
</ConfigProvider>

Combining with ThemeProvider

Use both providers together for full customization:

import { ConfigProvider, ThemeProvider } from 'asterui'
import { zhCN } from 'asterui/locale'

<ThemeProvider theme="dark">
  <ConfigProvider locale={zhCN} componentSize="sm">
    <App />
  </ConfigProvider>
</ThemeProvider>

API

ConfigProvider Props

Property	Type	Default	Description
locale	Locale	enUS	Locale configuration object.
componentSize	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Default size for all components.
direction	'ltr' | 'rtl'	'ltr'	Layout direction.
prefixCls	string	-	Prefix for CSS classes.
getPopupContainer	(triggerNode?: HTMLElement) => HTMLElement	-	Default container for portals.
componentDisabled	boolean	-	Globally disable all interactive components.
renderEmpty	(componentName: string) => ReactNode	-	Custom empty state renderer.
children	React.ReactNode	-	Child components.

useConfig Return Value

Property	Type	Description
locale	Locale	Current locale configuration.
componentSize	string	Current global component size.
direction	'ltr' | 'rtl'	Current layout direction.
getPopupContainer	function	Current portal container function.
componentDisabled	boolean	Current global disabled state.
renderEmpty	function	Current empty state renderer.

import { useConfig } from 'asterui'

function MyComponent() {
  const { locale, componentSize, direction } = useConfig()
  // Use configuration values...
}

useLocale

Access just the current locale:

import { useLocale } from 'asterui'

function MyComponent() {
  const locale = useLocale()
  // Use locale strings...
}

Available Locales

Import locales from asterui/locale:

import { zhCN, jaJP, koKR, deDE, frFR, esES, ptBR, enGB, enCA } from 'asterui/locale'

Locale	Language
enUS	English (US) - default
enGB	English (UK)
enCA	English (Canada)
zhCN	Chinese (Simplified)
jaJP	Japanese
koKR	Korean
deDE	German
frFR	French
esES	Spanish
ptBR	Portuguese (Brazil)

Accessibility

• Use direction="rtl" for right-to-left languages like Arabic and Hebrew
• Locale settings affect screen reader text in components like Empty, Pagination, etc.
• Nested providers allow different regions of your app to have different configurations