wot-design-uni/docs/en-US/component/config-provider.md

ConfigProvider Global Configuration

Used for global configuration of Wot components, providing capabilities such as dark mode and theme customization.

Dark Mode

Set the theme property of the ConfigProvider component to dark to enable dark mode.

Dark mode will take effect globally, making all Wot components on the page appear in dark style.

<wd-config-provider theme="dark">...</wd-config-provider>

:::tip It's worth noting that enabling Wot's dark mode will only affect the UI of Wot components and will not affect global text color or background color. You can refer to the following CSS to set some global styles: :::

.wot-theme-dark body {
  color: #f5f5f5;
  background-color: black;
}

Dynamic Switching

By dynamically setting the theme property, you can switch between light and dark styles.

<wd-config-provider :theme="theme">...</wd-config-provider>

export default {
  setup() {
    const theme = ref('light')

    setTimeout(() => {
      theme.value = 'dark'
    }, 1000)

    return { theme }
  }
}

Theme Customization

Wot components organize styles through rich CSS variables. By overriding these CSS variables, you can achieve theme customization, dynamic theme switching, and other effects.

Example

These variables' default values are defined on the page node. If converting to H5, the default values are defined on the :root node.

:root,
page {
  --wot-color-success: red;
  --wot-color-warning: yellow;
}

Override via CSS

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

/* After adding this style, the default Button background color will become green */
:root,
page {
  --wot-button-normal-bg: green;
}

Override via ConfigProvider

The ConfigProvider component provides the ability to override CSS variables. You need to wrap a ConfigProvider component at the root node and configure some theme variables through the theme-vars property.

<wd-config-provider :theme-vars="themeVars">
  <div style="margin: 16px">
    <wd-button round block type="primary">Submit</wd-button>
  </div>
</wd-config-provider>

import { ref, reactive } from 'vue'

export default {
  setup() {
    // Values in themeVars will be converted to corresponding CSS variables
    // For example, buttonPrimaryBg will be converted to `--wot-button-primary-bg-color`
    const themeVars = reactive({
      buttonPrimaryBgColor: '#07c160',
      buttonPrimaryColor: '#07c160'
    })
    return {
      themeVars
    }
  }
}

Using with TypeScript

When defining themeVars in TypeScript, it's recommended to use the ConfigProviderThemeVars type provided by wot-design-uni, which can provide comprehensive type hints:

import type { ConfigProviderThemeVars } from 'wot-design-uni'

const themeVars: ConfigProviderThemeVars = {
  colorTheme: 'red'
}

:::tip Note: ConfigProvider only affects the styles of its child components, not the global root node. :::

Global Sharing

Requires the virtual root component (uni-ku-root) for global sharing

Installation

::: code-group

npm i -D @uni-ku/root

yarn add -D @uni-ku/root

pnpm add -D @uni-ku/root

:::

Import

• CLI project: Directly edit vite.config.(js|ts) in the root directory
• HBuilderX project: Need to create vite.config.(js|ts) in the root directory

// vite.config.(js|ts)

import { defineConfig } from 'vite'
import UniKuRoot from '@uni-ku/root'
import Uni from '@dcloudio/vite-plugin-uni'

export default defineConfig({
  plugins: [
    // ...plugins
    UniKuRoot(),
    Uni()
  ]
})

:::tip If there are plugins that change pages.json, UniKuRoot needs to be placed after them :::

Usage

1. Create a root component and handle global configuration components

• CLI project: Create App.ku.vue in the src directory
• HBuilderX project: Create App.ku.vue in the root directory

:::tip The <KuRootView /> tag in App.ku.vue represents the specified view placement location :::

<!-- src/App.ku.vue | App.ku.vue -->

<script setup lang="ts">
import { useTheme } from './composables/useTheme'

const { theme, themeVars } = useTheme({
  buttonPrimaryBgColor: '#07c160',
  buttonPrimaryColor: '#07c160'
})
</script>

<template>
  <div>Hello AppKuVue</div>
  <!-- Ensure WdConfigProvider component is registered -->
  <wd-config-provider :theme="theme" :theme-vars="themeVars">
    <KuRootView />
  </wd-config-provider>
</template>

2. Write a composable function for theme control

// src/composables/useTheme.ts

import type { ConfigProviderThemeVars } from 'wot-design-uni'
import { ref } from 'vue'

const theme = ref<'light' | 'dark'>()
const themeVars = ref<ConfigProviderThemeVars>()

export function useTheme(vars?: ConfigProviderThemeVars) {
  vars && (themeVars.value = vars)

  function toggleTheme(mode?: 'light' | 'dark') {
    theme.value = mode || (theme.value === 'light' ? 'dark' : 'light')
  }

  return {
    theme,
    themeVars,
    toggleTheme
  }
}

3. Use theme switching in any view file

<!-- src/pages/*.vue -->

<script setup lang="ts">
import { useTheme } from '@/composables/useTheme'

const { theme, toggleTheme } = useTheme()
</script>

<template>
  <button @click="toggleTheme">Toggle theme, current mode: {{ theme }}</button>
</template>

Attributes

Parameter	Description	Type	Options	Default	Version
theme	Theme style, set to dark to enable dark mode, takes effect globally	string	dark/light	-	-
theme-vars	Custom theme variables	ConfigProviderThemeVars	-	-	-

External Style Classes

Class Name	Description	Version
custom-class	Root node style	1.3.9
custom-style	Root node style	1.3.9