ConfigProvider - Vant 4

⚙️ ConfigProvider

Global configuration and theming powerhouse for your entire application

🌟 Introduction

Transform your entire application with global configuration! ConfigProvider is your central control hub for dark mode, theme customization, and component-wide settings. Perfect for creating consistent, branded experiences across all Vant components.

📦 Installation

Register component globally via app.use, refer to Component Registration for more registration ways.

import { createApp } from'vue'; import { ConfigProvider } from'vant'; const app = createApp(); app.use(ConfigProvider);

🌙 Dark Mode

🌟 Enable Dark Mode

Transform your app into a sleek dark experience by setting the theme prop of the ConfigProvider component to dark.

This takes effect globally, making all Vant components on the page beautifully dark:

The theme prop will not change the text-color or background-color of the page, you can set it manually like this:

.van-theme-darkbody { color: #f5f5f5; background-color: black; }

Tips: The theme prop will not change the background color of the page, you need to set it manually.

🔄 Switch Theme

Create dynamic theme switching experiences by dynamically setting the theme property:

exportdefault { setup() { const theme = ref('light'); setTimeout(() => { theme.value = 'dark'; }, 1000); return { theme }; }, };

🎨 Custom Theme

🌟 Introduction

Unleash your creativity with Vant's powerful theming system! Vant organizes component styles through CSS Variables, allowing you to create stunning custom themes by overriding these CSS Variables.

Demo

Looking at the style of the Button component, you can see that the following variables exist on the .van-button--primary class:

.van-button--primary { color: var(--van-button-primary-color); background-color: var(--van-button-primary-background); }

The default values of these variables are defined on the :root node:

:root { --van-white: #fff; --van-blue: #1989fa; --van-button-primary-color: var(--van-white); --van-button-primary-background: var(--van-primary-color); }

🎯 Custom CSS Variables

🎨 Override by CSS

You can directly override these CSS variables in the code, and the style of the Button component will change accordingly:

/* the Primary Button will turn red */:root:root { --van-button-primary-background: red; }

Note: Why write two duplicate :root?

Since the theme variables in vant are also declared under :root, in some cases they cannot be successfully overwritten due to priority issues. Through :root:root you can explicitly make the content you write a higher priority to ensure the successful coverage of the theme variables.

⚙️ Override by ConfigProvider

The ConfigProvider component provides powerful CSS variable override capabilities. Simply wrap a ConfigProvider component at the root node and configure CSS variables through the theme-vars property:

import { ref, reactive } from'vue'; exportdefault { setup() { const rate = ref(4); const slider = ref(50); // ThemeVars will be converted to the corresponding CSS variable// For example, sliderBarHeight will be converted to `--van-slider-bar-height`const themeVars = reactive({ rateIconFullColor: '#07c160', sliderBarHeight: '4px', sliderButtonWidth: '20px', sliderButtonHeight: '20px', sliderActiveBackground: '#07c160', buttonPrimaryBackground: '#07c160', buttonPrimaryBorderColor: '#07c160', }); return { rate, slider, themeVars, }; }, };

🎯 Scope of CSS Variables

By default, the CSS variables generated by themeVars are applied to the root node of the component, thereby only affecting the styles of its child components and not the entire page.

You can modify the scope of CSS variables using the theme-vars-scope prop. For example, by setting theme-vars-scope to global, the CSS variables generated by themeVars will be applied to the root node of the HTML and affect all components within the entire page:

Use In TypeScript

Using ConfigProviderThemeVars type to get code intellisense.

importtype { ConfigProviderThemeVars } from'vant'; constthemeVars: ConfigProviderThemeVars = { sliderBarHeight: '4px', };

Combining dark mode with CSS variables

If you need to define CSS variables for dark mode or light mode separately, you can use the theme-vars-dark and theme-vars-light props.

• theme-vars-dark: define CSS variables that only take effect in dark mode, will override the variables defined in theme-vars.
• theme-vars-light: define CSS variables that only take effect in light mode, will override the variables defined in theme-vars.

Example

Take the buttonPrimaryBackground variable below as an example, the value will be blue in dark mode, and green in light mode.

import { ref, reactive } from'vue'; exportdefault { setup() { const themeVars = reactive({ buttonPrimaryBackground: 'red' }); const themeVarsDark = reactive({ buttonPrimaryBackground: 'blue' }); const themeVarsLight = reactive({ buttonPrimaryBackground: 'green' }); return { themeVars, themeVarsDark, themeVarsLight, }; }, };

Using Class Names

In addition, you can also use the class selectors .van-theme-light and .van-theme-dark to individually modify the base variables and component variables in the light or dark mode.

.van-theme-light { --van-white: white; } .van-theme-dark { --van-white: black; }

Variables

Variable Types

In Vant, CSS variables are divided into basic variables and component variables. Component variables inherit from basic variables, so modifying a basic variable will affect all related components.

Modifying Variables

CSS variables have an inheritance relationship, where component variables inherit from the nearest parent basic variable.

Therefore, there are certain limitations when modifying basic variables. You need to use the :root selector or the global mode of the ConfigProvider component to modify basic variables. Otherwise, component variables may not inherit basic variables correctly.

Taking the --van-primary-color basic variable as an example:

• You can modify it using the :root selector:

:root { --van-primary-color: red; }

• You can modify it using the global mode of the ConfigProvider component:

• You cannot modify it using the default local mode of the ConfigProvider component:

As for component variables, there are no such limitations, and you can modify them in any way you want.

Basic Variables List

There are all Basic Variables below, for component CSS Variables, please refer to the documentation of each component.

// Color Palette--van-black: #000; --van-white: #fff; --van-gray-1: #f7f8fa; --van-gray-2: #f2f3f5; --van-gray-3: #ebedf0; --van-gray-4: #dcdee0; --van-gray-5: #c8c9cc; --van-gray-6: #969799; --van-gray-7: #646566; --van-gray-8: #323233; --van-red: #ee0a24; --van-blue: #1989fa; --van-orange: #ff976a; --van-orange-dark: #ed6a0c; --van-orange-light: #fffbe8; --van-green: #07c160; // Gradient Colors--van-gradient-red: linear-gradient(to right, #ff6034, #ee0a24); --van-gradient-orange: linear-gradient(to right, #ffd01e, #ff8917); // Component Colors--van-primary-color: var(--van-blue); --van-success-color: var(--van-green); --van-danger-color: var(--van-red); --van-warning-color: var(--van-orange); --van-text-color: var(--van-gray-8); --van-text-color-2: var(--van-gray-6); --van-text-color-3: var(--van-gray-5); --van-active-color: var(--van-gray-2); --van-active-opacity: 0.6; --van-disabled-opacity: 0.5; --van-background: var(--van-gray-1); --van-background-2: var(--van-white); // Padding--van-padding-base: 4px; --van-padding-xs: 8px; --van-padding-sm: 12px; --van-padding-md: 16px; --van-padding-lg: 24px; --van-padding-xl: 32px; // Font--van-font-size-xs: 10px; --van-font-size-sm: 12px; --van-font-size-md: 14px; --van-font-size-lg: 16px; --van-font-bold: 600; --van-line-height-xs: 14px; --van-line-height-sm: 18px; --van-line-height-md: 20px; --van-line-height-lg: 22px; --van-base-font: -apple-system, BlinkMacSystemFont, 'Helvetica Neue', Helvetica, Segoe UI, Arial, Roboto, 'PingFang SC', 'miui', 'Hiragino Sans GB', 'Microsoft Yahei', sans-serif; --van-price-font: Avenir-Heavy, PingFang SC, Helvetica Neue, Arial, sans-serif; // Animation--van-duration-base: 0.3s; --van-duration-fast: 0.2s; --van-ease-out: ease-out; --van-ease-in: ease-in; // Border--van-border-color: var(--van-gray-3); --van-border-width: 1px; --van-radius-sm: 2px; --van-radius-md: 4px; --van-radius-lg: 8px; --van-radius-max: 999px;

API

Props

Attribute	Description	Type	Default
theme	Theme mode, can be set to dark	ConfigProviderTheme	light
theme-vars	Theme variables	object	-
theme-vars-dark	Theme variables that work in dark mode��will override theme-vars	object	-
theme-vars-light	Theme variables that work in light mode, will override theme-vars	object	-
theme-vars-scope	by default only affects its child components��set to global for the entire page to take effect	ConfigProviderThemeVarsScope	local
z-index	Set the z-index of all popup components, this property takes effect globally	number	2000
tag	HTML Tag of root element	string	div
icon-prefix	Icon className prefix	string	van-icon

Types

The component exports the following type definitions:

importtype { ConfigProviderProps, ConfigProviderTheme, ConfigProviderThemeVars, ConfigProviderThemeVarsScope, } from'vant';