ConfigProvider

free

ConfigProvider scopes shared UI defaults for product components beneath it.

import Button from '@/components/ui/button';
import ConfigProvider, {
  useConfig,
} from '@/components/ui/config-provider';

Installation

Add this component with the NateUI CLI.

npx nateui@latest add ConfigProvider

pnpm dlx nateui@latest add ConfigProvider

yarn dlx nateui@latest add ConfigProvider

Examples

Component Sizes

import { useState } from 'react';
import Button from '@/components/ui/button';
import ConfigProvider, {
  useConfig,

Direction

import ConfigProvider, {
  useConfig,
} from '@/components/ui/config-provider';
import Input from '@/components/ui/input';

Locale

import 'dayjs/locale/fr';
import Calendar from '@/components/ui/calendar';
import ConfigProvider, {
  useConfig,

Slot Class Names

import Tag from '@/components/ui/tag';
import Card from '@/components/ui/card';
import ConfigProvider, {
  useConfig,

Component Defaults

componentDefaults supplies fallback props for supported components. An explicit component prop, including false, takes precedence over the nearest provider; components without a provider keep their existing defaults.

import Button from '@/components/ui/button';
import ConfigProvider, {
  useConfig,
} from '@/components/ui/config-provider';
 
export default function ComponentDefaultsExample() {
  const config = useConfig();
 
  return (
    <ConfigProvider
      value={{
        ...config,
        componentDefaults: {
          button: { variant: 'solid', shape: 'circle', size: 'lg' },
          alert: { variant: 'info', showIcon: true },
          avatar: { shape: 'square' },
          card: { bordered: false },
          input: { size: 'sm' },
          table: { bordered: true },
          tabs: { variant: 'pill' },
        },
      }}
    >
      <Button>Uses the provider variant and shape</Button>
    </ConfigProvider>
  );
}

API

ConfigProvider is the exported React context provider for NateUI component configuration. It expects a full config value; spread the current useConfig() value or defaultConfig when changing one field.

Prop	Description	Type	Default
`value`	Complete configuration object used by descendant UI components.	`Config`	Required
`children`	Subtree that receives the supplied configuration.	`ReactNode`	-

Exports

Export	Description
`ConfigProvider`	Default provider component.
`useConfig`	Reads the nearest provider value, falling back to `defaultConfig`.
`defaultConfig`	Baseline config: light mode, English locale, left-to-right direction, and empty slot/default maps. Components use their own defaults when the provider sets nothing.
`ConfigContext`	Raw React context for advanced integrations.
`ConfigConsumer`	Context consumer export for non-hook consumers.

Types

type Config = {
  mode: 'light' | 'dark';
  locale: string;
  direction: TypeAttributes.Direction;
  classNames?: ConfigClassNames;
  componentDefaults?: ConfigComponentDefaults;
};
 
type ConfigComponentDefaults = Partial<{
  alert: {
    variant?: 'success' | 'warning' | 'destructive' | 'info';
    showIcon?: boolean;
  };
  avatar: {
    shape?: 'round' | 'circle' | 'square';
    size?: 'lg' | 'md' | 'sm' | number;
  };
  avatarGroup: {
    chained?: boolean;
  };
  button: {
    variant?: 'solid' | 'subtle' | 'default' | 'ghost' | 'link';
    shape?: TypeAttributes.Shape;
    size?: TypeAttributes.ControlSize;
    clickFeedback?: boolean;
  };
  card: {
    bordered?: boolean;
  };
  datePicker: {
    size?: TypeAttributes.ControlSize;
  };
  form: {
    size?: TypeAttributes.ControlSize;
  };
  input: {
    size?: TypeAttributes.ControlSize;
  };
  inputGroup: {
    size?: TypeAttributes.ControlSize;
  };
  multiValueInput: {
    size?: TypeAttributes.ControlSize;
  };
  progress: {
    size?: 'sm' | 'md';
  };
  rate: {
    size?: TypeAttributes.ControlSize;
  };
  segment: {
    size?: TypeAttributes.ControlSize;
  };
  select: {
    size?: TypeAttributes.ControlSize;
  };
  slider: {
    variant?: 'default' | 'capsule';
  };
  spinner: {
    size?: string | number;
  };
  table: {
    bordered?: boolean;
    compact?: boolean;
    hoverable?: boolean;
  };
  tabs: {
    variant?: 'underline' | 'pill';
  };
  tag: {
    size?: TypeAttributes.ControlSize;
  };
  timeInput: {
    size?: TypeAttributes.ControlSize;
  };
}>;
 
type SlotClassNames<TSlot extends string> =
  Partial<Record<TSlot, string>>;
 
declare namespace TypeAttributes {
  type Shape = 'round' | 'circle' | 'none';
  type Status = 'success' | 'warning' | 'danger' | 'info';
  type FormLayout = 'horizontal' | 'vertical' | 'inline';
  type ControlSize = 'lg' | 'md' | 'sm';
  type Direction = 'ltr' | 'rtl';
  type Placement =
    | 'top'
    | 'right'
    | 'bottom'
    | 'left'
    | 'top-start'
    | 'top-end'
    | 'right-start'
    | 'right-end'
    | 'bottom-start'
    | 'bottom-end'
    | 'left-start'
    | 'left-end';
}
 
type ActionBarConfigClassNames = SlotClassNames<'root' | 'content'>;
 
type AlertConfigClassNames = SlotClassNames<
  'root' | 'content' | 'icon' | 'title' | 'description' | 'close'
>;
 
type AvatarConfigClassNames = SlotClassNames<
  'root' | 'image' | 'icon' | 'fallback' | 'group' | 'overflow'
>;
 
type BadgeConfigClassNames = SlotClassNames<'root' | 'indicator'>;
 
type ButtonConfigClassNames = SlotClassNames<
  'root' | 'label' | 'icon' | 'spinner'
>;
 
type BreadcrumbConfigClassNames = SlotClassNames<
  | 'root'
  | 'list'
  | 'item'
  | 'link'
  | 'page'
  | 'separator'
  | 'ellipsis'
  | 'icon'
>;
 
type CalendarConfigClassNames = SlotClassNames<
  | 'root'
  | 'view'
  | 'header'
  | 'headerLabel'
  | 'previousTrigger'
  | 'nextTrigger'
  | 'table'
  | 'weekday'
  | 'week'
  | 'cell'
  | 'day'
  | 'monthGrid'
  | 'monthCell'
  | 'yearGrid'
  | 'yearCell'
>;
 
type RangeCalendarConfigClassNames = CalendarConfigClassNames;
 
type CardConfigClassNames = SlotClassNames<
  'root' | 'header' | 'body' | 'footer'
>;
 
type CarouselConfigClassNames = SlotClassNames<
  'root' | 'viewport' | 'content' | 'item' | 'previousTrigger' | 'nextTrigger'
>;
 
type CheckboxConfigClassNames = SlotClassNames<
  'root' | 'wrapper' | 'control' | 'indicator' | 'label' | 'group'
>;
 
type CollapsibleConfigClassNames = SlotClassNames<
  'root' | 'trigger' | 'triggerLabel' | 'indicator' | 'content'
>;
 
type DatePickerConfigClassNames = SlotClassNames<
  'trigger' | 'clearButton' | 'panel' | 'calendar' | 'timePanel' | 'action'
>;
 
type DialogConfigClassNames = SlotClassNames<
  'overlay' | 'wrapper' | 'content' | 'close'
>;
 
type DrawerConfigClassNames = SlotClassNames<
  | 'overlay'
  | 'wrapper'
  | 'content'
  | 'header'
  | 'title'
  | 'close'
  | 'handle'
  | 'body'
  | 'footer'
>;
 
type DropdownConfigClassNames = SlotClassNames<
  | 'trigger'
  | 'triggerLabel'
  | 'triggerIndicator'
  | 'contentWrapper'
  | 'content'
  | 'item'
  | 'itemLabel'
  | 'itemIndicator'
  | 'label'
  | 'separator'
  | 'customItem'
  | 'subTrigger'
  | 'subContent'
  | 'subIndicator'
  | 'contextArea'
>;
 
type FormConfigClassNames = SlotClassNames<'root'>;
 
type FormScopeConfigClassNames = SlotClassNames<'root'>;
 
type FormFieldConfigClassNames = SlotClassNames<
  'root' | 'label' | 'asterisk' | 'control' | 'message'
>;
 
type InputConfigClassNames = SlotClassNames<
  'root' | 'control' | 'prefix' | 'suffix'
>;
 
type InputGroupConfigClassNames = SlotClassNames<'root' | 'addon'>;
 
type MenuConfigClassNames = SlotClassNames<
  | 'root'
  | 'group'
  | 'groupLabel'
  | 'groupList'
  | 'item'
  | 'itemIndicator'
  | 'collapse'
  | 'collapseTrigger'
  | 'collapseLabel'
  | 'collapseIndicator'
  | 'collapseContent'
>;
 
type MenuItemConfigClassNames = SlotClassNames<'root' | 'indicator'>;
 
type MultiValueInputConfigClassNames = SlotClassNames<
  | 'root'
  | 'tagList'
  | 'tag'
  | 'tagLabel'
  | 'tagRemove'
  | 'overflowTrigger'
  | 'overflowContent'
  | 'input'
>;
 
type NotificationConfigClassNames = SlotClassNames<
  'root' | 'content' | 'icon' | 'title' | 'description' | 'close'
>;
 
type PaginationConfigClassNames = SlotClassNames<
  | 'root'
  | 'total'
  | 'list'
  | 'item'
  | 'ellipsis'
  | 'previousTrigger'
  | 'nextTrigger'
>;
 
type PopoverConfigClassNames = SlotClassNames<
  'trigger' | 'content' | 'body'
>;
 
type ProgressConfigClassNames = SlotClassNames<
  'root' | 'track' | 'trail' | 'indicator' | 'info'
>;
 
type RateConfigClassNames = SlotClassNames<
  'root' | 'item' | 'icon' | 'label'
>;
 
type RadioConfigClassNames = SlotClassNames<
  'root' | 'wrapper' | 'control' | 'indicator' | 'label' | 'group'
>;
 
type ResizableConfigClassNames = SlotClassNames<
  | 'root'
  | 'handleWrapper'
  | 'top'
  | 'right'
  | 'bottom'
  | 'left'
  | 'topRight'
  | 'bottomRight'
  | 'bottomLeft'
  | 'topLeft'
>;
 
type ScrollConfigClassNames = SlotClassNames<
  'root' | 'viewport' | 'content' | 'scrollbar' | 'thumb' | 'corner' | 'flexRoot'
>;
 
type SegmentConfigClassNames = SlotClassNames<
  'root' | 'item' | 'indicator'
>;
 
type SelectConfigClassNames = SlotClassNames<
  | 'root'
  | 'control'
  | 'trigger'
  | 'value'
  | 'placeholder'
  | 'indicator'
  | 'spinner'
  | 'clearButton'
  | 'menu'
  | 'menuContent'
  | 'filter'
  | 'filterInput'
  | 'group'
  | 'groupLabel'
  | 'item'
  | 'itemText'
  | 'itemIndicator'
  | 'message'
  | 'tag'
  | 'tagRemove'
  | 'multiInput'
>;
 
type SkeletonConfigClassNames = SlotClassNames<'root'>;
 
type SliderConfigClassNames = SlotClassNames<
  'root' | 'trackWrapper' | 'track' | 'range' | 'thumb' | 'tooltip' | 'mark' | 'markLabel'
>;
 
type SpinnerConfigClassNames = SlotClassNames<
  'root' | 'track' | 'indicator'
>;
 
type StepsConfigClassNames = SlotClassNames<
  | 'root'
  | 'item'
  | 'trigger'
  | 'icon'
  | 'content'
  | 'title'
  | 'description'
  | 'connector'
>;
 
type SwitcherConfigClassNames = SlotClassNames<
  'root' | 'control' | 'thumb' | 'spinner' | 'content'
>;
 
type TableConfigClassNames = SlotClassNames<
  | 'root'
  | 'overflow'
  | 'border'
  | 'head'
  | 'body'
  | 'foot'
  | 'row'
  | 'headerCell'
  | 'cell'
  | 'sorter'
  | 'sorterIcon'
>;
 
type TabsConfigClassNames = SlotClassNames<
  'root' | 'list' | 'trigger' | 'icon' | 'indicator' | 'content'
>;
 
type TagConfigClassNames = SlotClassNames<
  'root' | 'label' | 'prefix' | 'suffix'
>;
 
type TimeInputConfigClassNames = SlotClassNames<
  | 'root'
  | 'wrapper'
  | 'field'
  | 'separator'
  | 'period'
  | 'clearButton'
  | 'prefix'
  | 'suffix'
>;
 
type TimelineConfigClassNames = SlotClassNames<
  | 'root'
  | 'item'
  | 'wrapper'
  | 'media'
  | 'mediaContent'
  | 'mediaDot'
  | 'connector'
  | 'content'
>;
 
type TooltipConfigClassNames = SlotClassNames<
  'trigger' | 'content' | 'label'
>;
 
type UploadConfigClassNames = SlotClassNames<
  | 'root'
  | 'input'
  | 'trigger'
  | 'tip'
  | 'list'
  | 'item'
  | 'itemWrapper'
  | 'thumbnail'
  | 'fileIcon'
  | 'fileImage'
  | 'fileInfo'
  | 'fileName'
  | 'fileSize'
  | 'removeButton'
>;
 
type ConfigClassNames = Partial<{
  actionBar: ActionBarConfigClassNames;
  alert: AlertConfigClassNames;
  avatar: AvatarConfigClassNames;
  badge: BadgeConfigClassNames;
  button: ButtonConfigClassNames;
  breadcrumb: BreadcrumbConfigClassNames;
  calendar: CalendarConfigClassNames;
  card: CardConfigClassNames;
  carousel: CarouselConfigClassNames;
  checkbox: CheckboxConfigClassNames;
  collapsible: CollapsibleConfigClassNames;
  datePicker: DatePickerConfigClassNames;
  dialog: DialogConfigClassNames;
  drawer: DrawerConfigClassNames;
  dropdown: DropdownConfigClassNames;
  form: FormConfigClassNames;
  formScope: FormScopeConfigClassNames;
  formField: FormFieldConfigClassNames;
  input: InputConfigClassNames;
  inputGroup: InputGroupConfigClassNames;
  menu: MenuConfigClassNames;
  menuItem: MenuItemConfigClassNames;
  multiValueInput: MultiValueInputConfigClassNames;
  notification: NotificationConfigClassNames;
  pagination: PaginationConfigClassNames;
  popover: PopoverConfigClassNames;
  progress: ProgressConfigClassNames;
  rate: RateConfigClassNames;
  radio: RadioConfigClassNames;
  resizable: ResizableConfigClassNames;
  rangeCalendar: RangeCalendarConfigClassNames;
  scroll: ScrollConfigClassNames;
  segment: SegmentConfigClassNames;
  select: SelectConfigClassNames;
  skeleton: SkeletonConfigClassNames;
  slider: SliderConfigClassNames;
  spinner: SpinnerConfigClassNames;
  steps: StepsConfigClassNames;
  switcher: SwitcherConfigClassNames;
  table: TableConfigClassNames;
  tabs: TabsConfigClassNames;
  tag: TagConfigClassNames;
  timeInput: TimeInputConfigClassNames;
  timeline: TimelineConfigClassNames;
  tooltip: TooltipConfigClassNames;
  upload: UploadConfigClassNames;
}>;