Vant Theming

Vant Theming

This skill provides comprehensive guidance for customizing Vant themes using CSS Variables and the ConfigProvider component, including dark mode support and theme customization.

When to Invoke

Invoke this skill when:

• User wants to customize Vant component styles
• User needs to enable dark mode
• User asks about CSS Variables in Vant
• User wants to change primary colors or other theme colors
• User needs to create a custom theme for their application

Theme Customization Overview

Vant organizes component styles through CSS Variables. You can customize themes by overriding these CSS Variables.

How CSS Variables Work

Looking at the Button component style:

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

Default values 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);
}

Customization Methods

Method 1: Override by CSS

Directly override CSS variables in your stylesheets:

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

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.

Method 2: Override by ConfigProvider

The ConfigProvider component provides the ability to override CSS variables:

<van-config-provider :theme-vars="themeVars">
  <van-form>
    <van-field name="rate" label="Rate">
      <template #input>
        <van-rate v-model="rate" />
      </template>
    </van-field>
    <van-field name="slider" label="Slider">
      <template #input>
        <van-slider v-model="slider" />
      </template>
    </van-field>
    <div style="margin: 16px">
      <van-button round block type="primary" native-type="submit">
        Submit
      </van-button>
    </div>
  </van-form>
</van-config-provider>

import { ref, reactive } from 'vue';

export default {
  setup() {
    const rate = ref(4);
    const slider = ref(50);

    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, CSS variables generated by themeVars are applied to the root node of the component, affecting only child components.

Use theme-vars-scope="global" to apply variables to the entire page:

<van-config-provider :theme-vars="themeVars" theme-vars-scope="global">
  ...
</van-config-provider>

TypeScript Support

Use ConfigProviderThemeVars type for code intellisense:

import type { ConfigProviderThemeVars } from 'vant';

const themeVars: ConfigProviderThemeVars = {
  sliderBarHeight: '4px',
};

Dark Mode

Enable Dark Mode

Set the theme prop to dark:

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

Switch Theme Dynamically

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

import { ref } from 'vue';

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

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

    return { theme };
  },
};

Manual Page Styling

The theme prop will not change the text-color or background-color of the page:

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

Theme-Specific CSS Variables

Define CSS variables for dark or light mode separately:

<van-config-provider
  :theme-vars="themeVars"
  :theme-vars-dark="themeVarsDark"
  :theme-vars-light="themeVarsLight"
>
  ...
</van-config-provider>

import { reactive } from 'vue';

export default {
  setup() {
    const themeVars = reactive({ buttonPrimaryBackground: 'red' });
    const themeVarsDark = reactive({ buttonPrimaryBackground: 'blue' });
    const themeVarsLight = reactive({ buttonPrimaryBackground: 'green' });

    return { themeVars, themeVarsDark, themeVarsLight };
  },
};

Using Class Names

Use class selectors for theme-specific styles:

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

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

Variable Types

Basic Variables vs Component Variables

• Basic Variables: Foundation variables inherited by components
• Component Variables: Variables specific to each component

Modifying Basic Variables

Basic variables must be modified using :root selector or global mode:

/* Correct - using :root selector */
:root {
  --van-primary-color: red;
}

<!-- Correct - using global mode -->
<van-config-provider
  :theme-vars="{ primaryColor: 'red' }"
  theme-vars-scope="global"
>
  ...
</van-config-provider>

<!-- Incorrect - local mode won't work for basic variables -->
<van-config-provider :theme-vars="{ primaryColor: 'red' }">
  ...
</van-config-provider>

Basic Variables Reference

// 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;

// 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;

Best Practices

1. Use global scope for basic variables: Basic variables like --van-primary-color should be modified globally to ensure proper inheritance.

2. Use local scope for component-specific variables: Component-specific variables can be scoped locally for better isolation.

3. Combine with dark mode: Use theme-vars-dark and theme-vars-light for theme-specific customizations.

4. TypeScript support: Always use ConfigProviderThemeVars type for better developer experience.

5. CSS specificity: Use :root:root when overriding variables in CSS to ensure proper priority.

Input Parameters

When using this skill, provide the following information:

• Customization type: Dark mode, color customization, or full theme
• Scope: Global or local CSS variable scope
• Components affected: Which components need customization
• Framework: Vue 3 with TypeScript or JavaScript

Output Format

This skill provides:

1. CSS variable override examples
2. ConfigProvider configuration code
3. Dark mode implementation guide
4. TypeScript type definitions
5. Best practices for theme customization