n-config-provider

name	n-config-provider
description	Global configuration provider for theme, locale, and component options. Invoke when user needs to set up global theme, internationalization, or configure default component behaviors in Naive UI.
metadata	{"author":"jiaiyan","version":"1.0.0"}

Naive UI Config Provider Component

Config Provider is the root configuration component used to set global theme, language, namespace, and component-level defaults.

When to Use

Use this component when:

• Theme setup: Configure light/dark theme for the entire application
• Internationalization: Set locale and date locale for all components
• Component defaults: Configure default sizes and options for components
• Namespace isolation: Add class names to detached DOM elements
• SSR optimization: Disable inline theme for server-side rendering

When to Invoke

Invoke this skill when:

• User needs to implement dark/light theme switching
• User wants to configure global language settings
• User needs to set default sizes for multiple components
• User wants to customize theme variables
• User asks about namespace for detached components
• User needs to configure breakpoints for responsive design

Features

• Theme Management: Light/dark theme with inheritance support
• Theme Overrides: Customize theme CSS variables
• Locale Support: Internationalization for all components
• Date Locale: Date formatting localization
• Component Options: Global component size and behavior configuration
• Namespace: Class name for detached DOM elements
• Breakpoints: Custom responsive breakpoints
• Class Prefix: Custom CSS class prefix
• Abstract Mode: No wrapper DOM option
• SSR Support: Disable inline theme for server-side rendering

API Reference

ConfigProvider Props

Name	Type	Default	Description
abstract	boolean	false	If n-config-provider has no wrapper DOM.
breakpoints	{ [k: string]: number }	{ xs: <640, s: ≥640, m: ≥1024, l: ≥1280, xl: ≥1536, xxl: ≥1920 }	Responsive breakpoints for n-grid. Not responsive after mount.
cls-prefix	string	undefined	Class prefix for all inner components. Not reactive.
component-options	GlobalComponentConfig	undefined	Global component options for sizes and behaviors.
date-locale	DateLocale | null	undefined	Date locale object. null uses default dateEnUS. undefined inherits from parent.
inline-theme-disabled	boolean	false	Disable inline theme CSS variables. Useful for SSR. Not responsive.
katex	object	undefined	Katex object for n-equation component.
locale	Locale | null	undefined	Locale object. null uses default enUS. undefined inherits from parent.
namespace	string	undefined	Class name for detached parts of components.
preflight-style-disabled	boolean	false	Disable preflight style. Use n-global-style for reactive global styles.
style-mount-target	ParentNode	undefined	Mounting target for style elements. Not reactive.
tag	string	'div'	The HTML tag to render as.
theme	Theme | null	undefined	Theme object. null uses light theme. undefined inherits from parent.
theme-overrides	ThemeOverrides | null	undefined	Theme variable overrides. null clears overrides. undefined inherits from parent.

GlobalComponentConfig Type

interface GlobalComponentConfig {
  AutoComplete?: { size?: AutoCompleteSize }
  Button?: { size?: ButtonSize }
  Card?: { size?: CardSize }
  Cascader?: { size?: CascaderSize; renderEmpty?: () => VNodeChild }
  Checkbox?: { size?: CheckboxSize }
  ColorPicker?: { size?: ColorPickerSize }
  DataTable?: {
    size?: DataTableSize
    renderFilter?: DataTableRenderFilter
    renderSorter?: DataTableRenderSorter
    renderEmpty?: () => VNodeChild
  }
  DatePicker?: { size?: DatePickerSize; timePickerSize?: TimePickerSize }
  Descriptions?: { size?: DescriptionsSize }
  Dialog?: { iconPlacement?: IconPlacement }
  Dropdown?: { size?: DropdownSize }
  DynamicInput?: { buttonSize?: ButtonSize }
  DynamicTags?: { size?: DynamicTagsSize }
  Empty?: Pick<EmptyProps, 'description' | 'renderIcon'>
  Form?: { size?: FormSize }
  Input?: { size?: InputSize }
  InputNumber?: { size?: InputNumberSize }
  InputOtp?: { size?: InputOtpSize }
  Mention?: { size?: MentionSize }
  Pagination?: { size?: PaginationSize; inputSize?: InputSize; selectSize?: SelectSize }
  Popselect?: { size?: PopselectSize }
  Radio?: { size?: RadioSize }
  Rate?: { size?: RateSize }
  Result?: { size?: ResultSize }
  Select?: { size?: SelectSize; renderEmpty?: () => VNodeChild }
  Skeleton?: { size?: SkeletonSize }
  Space?: { size?: SpaceSize }
  Switch?: { size?: SwitchSize }
  Table?: { size?: TableSize }
  Tabs?: { size?: TabsSize }
  Tag?: { size?: TagSize }
  TimePicker?: { size?: TimePickerSize }
  Transfer?: { size?: TransferSize; renderEmpty?: () => VNodeChild }
  Tree?: { renderEmpty?: () => VNodeChild }
  TreeSelect?: { size?: TreeSelectSize; renderEmpty?: () => VNodeChild }
}

Basic Usage

Theme Switching

<template>
  <n-config-provider :theme="theme">
    <n-card>
      <n-space>
        <n-button @click="theme = darkTheme">Dark</n-button>
        <n-button @click="theme = null">Light</n-button>
      </n-space>
    </n-card>
  </n-config-provider>
</template>

<script setup>
import { ref } from 'vue'
import { darkTheme } from 'naive-ui'

const theme = ref(null)
</script>

Locale Configuration

<template>
  <n-space vertical>
    <n-space>
      <n-button @click="setEnglish">en-US</n-button>
      <n-button @click="setChinese">zh-CN</n-button>
    </n-space>
    <n-config-provider :locale="locale" :date-locale="dateLocale">
      <n-date-picker />
    </n-config-provider>
  </n-space>
</template>

<script setup>
import { ref } from 'vue'
import { zhCN, dateZhCN } from 'naive-ui'

const locale = ref(null)
const dateLocale = ref(null)

const setEnglish = () => {
  locale.value = null
  dateLocale.value = null
}

const setChinese = () => {
  locale.value = zhCN
  dateLocale.value = dateZhCN
}
</script>

Use OS Theme

<template>
  <n-config-provider :theme="theme">
    <n-card>
      Your current system theme is {{ osTheme }}.
    </n-card>
  </n-config-provider>
</template>

<script setup>
import { computed } from 'vue'
import { useOsTheme, darkTheme } from 'naive-ui'

const osTheme = useOsTheme()
const theme = computed(() => osTheme.value === 'dark' ? darkTheme : null)
</script>

Abstract Mode (No Wrapper DOM)

<template>
  <n-config-provider abstract>
    <n-card>
      <n-tag>No Wrapper DOM</n-tag>
    </n-card>
  </n-config-provider>
</template>

Namespace for Detached Components

<template>
  <n-config-provider :namespace="ns">
    <n-tooltip placement="bottom" trigger="click">
      <template #trigger>
        <n-button>Activate Component with Detached Content</n-button>
      </template>
      Tooltip content
    </n-tooltip>
  </n-config-provider>
</template>

<script setup>
const ns = 'my-namespace'
</script>

Common Patterns

Global Component Size Configuration

<template>
  <n-config-provider :component-options="componentOptions">
    <n-space vertical>
      <n-button>Button</n-button>
      <n-tag closable>Tag</n-tag>
      <n-card title="Card">Card Content</n-card>
      <n-pagination :page-count="20" />
    </n-space>
  </n-config-provider>
</template>

<script setup>
import { ref } from 'vue'

const size = ref('medium')

const componentOptions = computed(() => ({
  Button: { size: size.value },
  Tag: { size: size.value },
  Card: { size: size.value },
  Pagination: { size: size.value }
}))
</script>

Nested Config Providers with Inheritance

<template>
  <n-config-provider :theme="darkTheme">
    <n-card title="Dark Theme">
      <n-config-provider :theme-overrides="customOverrides">
        <n-card title="Custom Overrides">
          <n-button type="primary">Custom Primary</n-button>
        </n-card>
      </n-config-provider>
    </n-card>
  </n-config-provider>
</template>

<script setup>
import { darkTheme } from 'naive-ui'

const customOverrides = {
  common: {
    primaryColor: '#FF6B6B'
  }
}
</script>

SSR-Friendly Configuration

<template>
  <n-config-provider
    inline-theme-disabled
    :theme="theme"
  >
    <n-button>No inline CSS variable on the button</n-button>
  </n-config-provider>
</template>

Custom Breakpoints

<template>
  <n-config-provider :breakpoints="customBreakpoints">
    <n-grid :cols="24">
      <n-gi :span="12">Half</n-gi>
      <n-gi :span="12">Half</n-gi>
    </n-grid>
  </n-config-provider>
</template>

<script setup>
const customBreakpoints = {
  xs: 0,
  sm: 640,
  md: 768,
  lg: 1024,
  xl: 1280,
  xxl: 1536
}
</script>

Complete Application Setup

<template>
  <n-config-provider
    :theme="theme"
    :theme-overrides="themeOverrides"
    :locale="locale"
    :date-locale="dateLocale"
    :component-options="componentOptions"
  >
    <n-global-style />
    <n-message-provider>
      <n-dialog-provider>
        <n-notification-provider>
          <router-view />
        </n-notification-provider>
      </n-dialog-provider>
    </n-message-provider>
  </n-config-provider>
</template>

<script setup>
import { ref } from 'vue'
import { darkTheme, zhCN, dateZhCN } from 'naive-ui'

const theme = ref(null)
const locale = ref(zhCN)
const dateLocale = ref(dateZhCN)

const themeOverrides = {
  common: {
    primaryColor: '#18A058'
  }
}

const componentOptions = {
  Button: { size: 'medium' },
  Input: { size: 'medium' },
  Select: { size: 'medium' }
}
</script>

Best Practices

1. Place at root level: Wrap your entire application with n-config-provider

   <n-config-provider :theme="theme">
     <App />
   </n-config-provider>
   

2. Use n-global-style together: Sync global styles to document.body

   <n-config-provider :theme="theme">
     <n-global-style />
     <App />
   </n-config-provider>
   

3. Inheritance behavior: Use undefined to inherit, null to reset to default

   • undefined: inherits from parent config provider
   • null: uses the default value
   • specific value: overrides the configuration

4. SSR optimization: Enable inline-theme-disabled for server-side rendering

   <n-config-provider inline-theme-disabled>
     <App />
   </n-config-provider>
   

5. Abstract mode: Use abstract when you don't need wrapper DOM

   <n-config-provider abstract>
     <App />
   </n-config-provider>
   

6. Theme switching: Use useOsTheme() to follow system preferences

   import { useOsTheme, darkTheme } from 'naive-ui'
   const osTheme = useOsTheme()
   const theme = computed(() => osTheme.value === 'dark' ? darkTheme : null)
   

7. Component options: Configure default sizes for consistency

   const componentOptions = {
     Button: { size: 'small' },
     Input: { size: 'small' }
   }
   

8. Namespace for isolation: Use namespace when multiple Naive UI instances exist

   <n-config-provider namespace="app-a">
     <App />
   </n-config-provider>