# Vant Theming

> Helps customize Vant themes using CSS Variables and ConfigProvider. Invoke when user needs to customize colors, enable dark mode, or modify component styles.

- Skill: `jiaiyan/vant-theming` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jiaiyan/vant-theming`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jiaiyan/vant-theming/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: jiaiyan (https://skillmd.com/u/jiaiyan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jiaiyan/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](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties). You can customize themes by overriding these CSS Variables.

### How CSS Variables Work

Looking at the Button component style:

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

Default values are defined on the `:root` node:

```css
: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:

```css
/* 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:

```html
<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>
```

```js
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:

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

### TypeScript Support

Use `ConfigProviderThemeVars` type for code intellisense:

```ts
import type { ConfigProviderThemeVars } from 'vant';

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

## Dark Mode

### Enable Dark Mode

Set the `theme` prop to `dark`:

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

### Switch Theme Dynamically

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

```js
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:

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

### Theme-Specific CSS Variables

Define CSS variables for dark or light mode separately:

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

```js
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:

```css
.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:

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

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

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

## Basic Variables Reference

```less
// 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