## File: README.md

<h1 align="center">Vant</h1>







---

## Features

- 🚀 1KB Component average size (min+gzip)
- 🚀 80+ High quality components
- 🚀 Zero third-party dependencies
- 💪 90%+ Unit test coverage
- 💪 Written in TypeScript
- 📖 Extensive documentation and demos
- 📖 Provide Sketch and Axure design resources
- 🍭 Support Vue 2 & Vue 3
- 🍭 Support Nuxt 2 & Nuxt 3, provide [Vant Module](https://github.com/vant-ui/vant-nuxt) for Nuxt
- 🍭 Support Tree Shaking
- 🍭 Support Custom Theme
- 🍭 Support Accessibility (still improving)
- 🍭 Support Dark Mode
- 🍭 Support SSR
- 🌍 Support i18n, built-in 30+ languages

## Install

Using `npm` to install:

```bash
# install latest Vant for Vue 3 project
npm i vant

# install Vant 2 for Vue 2 project
npm i vant@latest-v2
```

Using `yarn`, `pnpm`, or `bun`:

```bash
# with yarn
yarn add vant

# with pnpm
pnpm add vant

# with Bun
bun add vant
```

## Scaffold

It is recommended to use [Rsbuild](https://github.com/web-infra-dev/rsbuild) to create a scaffold project.

Rsbuild is a build tool based on Rspack, developed by the author of Vant, with first-class build speed and development experience, providing first-priority support for Vant.

You can create a Rsbuild project with the following command:

```bash
npm create rsbuild@latest
```

Please visit the [Rsbuild repository](https://github.com/web-infra-dev/rsbuild) for more information.

## Quickstart

```js
import { createApp } from 'vue';
// 1. Import the components you need
import { Button } from 'vant';
// 2. Import the components style
import 'vant/lib/index.css';

const app = createApp();

// 3. Register the components you need
app.use(Button);
```

See more in [Quickstart](https://vant-ui.github.io/vant/#/en-US/quickstart).

## Browser Support

Vant 2 supports modern browsers and Android >= 4.0、iOS >= 8.0.

Vant 3/4 supports modern browsers and Chrome >= 51、iOS >= 10.0 (same as Vue 3).

## Official Ecosystem

| Project | Description |
| --- | --- |
| [vant-weapp](https://github.com/vant-ui/vant-weapp) | WeChat MiniProgram UI |
| [vant-demo](https://github.com/vant-ui/vant-demo) | Collection of Vant demos |
| [vant-cli](https://github.com/vant-ui/vant/tree/main/packages/vant-cli) | Scaffold for UI library |
| [vant-icons](https://github.com/vant-ui/vant/tree/main/packages/vant-icons) | Vant icons |
| [vant-touch-emulator](https://github.com/vant-ui/vant/tree/main/packages/vant-touch-emulator) | Using vant in desktop browsers |
| [vant-nuxt](https://github.com/vant-ui/vant-nuxt) | Vant module for Nuxt |

## Community Ecosystem

| Project | Description |
| --- | --- |
| [3lang3/react-vant](https://github.com/3lang3/react-vant) | React mobile UI Components based on Vant |
| [vant-theme](https://github.com/Aisen60/vant-theme) | Online theme preview built on Vant UI |
| [@antmjs/vantui](https://github.com/antmjs/vantui) | Mobile UI Components based on Vant, supporting Taro and React |
| [Taroify](https://github.com/mallfoundry/taroify) | Taroify is the Taro version of Vant |
| [vant-playground](https://github.com/LadyChatterleyLover/vant-playground) | Vant Playground |
| [sfc-playground-vant](https://github.com/zhixiaoqiang/sfc-playground-vant) | Vant Playground |
| [vue3-h5-template](https://github.com/yulimchen/vue3-h5-template) | Mobile project template based on Vant |
| [vue3-vant-mobile](https://github.com/vue-zone/vue3-vant-mobile) | Mobile project template based on Vant, out of the box |
| [vscode-common-intellisense](https://github.com/Simon-He95/vscode-common-intellisense) | A VS Code extension that provides better intellisense to Vant developers |
| [nuxt-vant-mobile](https://github.com/vue-zone/nuxt-vant-mobile) | Nuxt _⁴_ project template based on Vant, out of the box |
| [mobvue](https://github.com/un-pany/mobvue) | A well-crafted mobile web app template |

## Links

- [Documentation](https://vant-ui.github.io/vant/)
- [Documentation (backup)](https://vant.pro/vant/)
- [Changelog](https://vant-ui.github.io/vant/#/en-US/changelog)
- [Discussions](https://github.com/vant-ui/vant/discussions)

## Preview

You can scan the following QR code to access the demo：



## Core Team

Core contributors of Vant and Vant Weapp:

| [](https://github.com/chenjiahan/) | [](https://github.com/cookfront/) | [](https://github.com/w91/) | [](https://github.com/pangxie1991/) | [](https://github.com/rex-zsd/) | [](https://github.com/nemo-shen/) |
| :-: | :-: | :-: | :-: | :-: | :-: |
| [chenjiahan](https://github.com/chenjiahan/) | [cookfront](https://github.com/cookfront/) | [wangnaiyi](https://github.com/w91/) | [pangxie](https://github.com/pangxie1991/) | [rex-zsd](https://github.com/rex-zsd/) | [nemo-shen](https://github.com/nemo-shen/) |

| [](https://github.com/Lindysen/) | [](https://github.com/JakeLaoyu/) | [](https://github.com/landluck/) | [](https://github.com/wjw-gavin/) | [](https://github.com/inottn/) | [](https://github.com/zhousg/) |
| :-: | :-: | :-: | :-: | :-: | :-: |
| [Lindysen](https://github.com/Lindysen/) | [JakeLaoyu](https://github.com/JakeLaoyu/) | [landluck](https://github.com/landluck/) | [wjw-gavin](https://github.com/wjw-gavin/) | [inottn](https://github.com/inottn/) | [zhousg](https://github.com/zhousg/) |

## Contribution Guide

Please make sure to read the [Contributing Guide](./.github/CONTRIBUTING.md) before making a pull request.

## Start On Web IDE

[https://github.dev/youzan/vant](https://github.dev/youzan/vant)

## LICENSE

Vant is [MIT](https://github.com/youzan/vant/blob/main/LICENSE) licensed.

---

## File: packages/vant-use/README.md

# Vant Use

Built-in composition APIs of Vant.

## Install

```shell
# with npm
npm i @vant/use

# with yarn
yarn add @vant/use

# with pnpm
pnpm add @vant/use

# with Bun
bun add @vant/use
```

---

## File: packages/vant-touch-emulator/README.md

# Vant Touch Emulator

在桌面端上模拟移动端 touch 事件，实现方式来自于 [hammerjs/touchemulator](https://github.com/hammerjs/touchemulator).

## Install

```shell
# with npm
npm i @vant/touch-emulator

# with yarn
yarn add @vant/touch-emulator

# with pnpm
pnpm add @vant/touch-emulator

# with Bun
bun add @vant/touch-emulator
```

## 使用指南

直接在代码中引入模块即可，模块会自动完成初始化并生效

```js
import '@vant/touch-emulator';
```

## CDN 引入

```html
<script src="https://fastly.jsdelivr.net/npm/@vant/touch-emulator"></script>
```

## 禁用 touch 模拟

在标签上添加 `data-no-touch-simulate` 属性后，可以使这个标签（以及它的子元素）不触发 `touch` 模拟事件。

```html

```

---

## File: packages/vant-popperjs/README.md

# @vant/popperjs

@popperjs/core in commonjs format, added Object.assign polyfill.

## Install

```shell
# with npm
npm i @vant/popperjs

# with yarn
yarn add @vant/popperjs

# with pnpm
pnpm add @vant/popperjs

# with Bun
bun add @vant/popperjs
```

## Usage

see: https://popper.js.org/

## Refer

issue: https://github.com/vant-ui/vant/issues/7626

---

## File: packages/vant-icons/README.md

# Vant Icons

## Install

```shell
# with npm
npm i @vant/icons

# with yarn
yarn add @vant/icons

# with pnpm
pnpm add @vant/icons

# with Bun
bun add @vant/icons
```

## Document

- [Usage in Vue](https://vant-ui.github.io/vant/#/zh-CN/icon)
- [Usage in Weapp](https://vant-ui.github.io/vant-weapp/#/icon)

---

## File: packages/vant-compat/README.md

# @vant/compat

This package provides Vant 3 compatible behavior for Vant 4 users.

## Install

```shell
# with npm
npm i @vant/compat

# with yarn
yarn add @vant/compat

# with pnpm
pnpm add @vant/compat

# with Bun
bun add @vant/compat
```

## Usage

```js
// Same as Toast in Vant 3
import { Toast } from '@vant/compat';

// Same as Dialog in Vant 3
import { Dialog } from '@vant/compat';

// Same as Notify in Vant 3
import { Notify } from '@vant/compat';

// Same as ImagePreview in Vant 3
import { ImagePreview } from '@vant/compat';
```

---

## File: packages/vant-cli/docs/commands.md

# Commands

You can add built-in commands to `npm scripts` to use it.

```json
// package.json
{
  "scripts": {
    "dev": "vant-cli dev",
    "test": "vant-cli test",
    "release": "vant-cli release",
    "build-site": "vant-cli build-site"
  }
}
```

Additionally, [npx](https://github.com/npm/npx) can used to be run those commands.

```bash
npx vant-cli dev
```

### dev

Start local dev server for browsering components and demo.

### build

Build Vue component library.

Files will be output to `es` and `lib` directory. More details [directory structure](https://github.com/vant-ui/vant/tree/main/packages/vant-cli/docs/directory.md)

Please add the followed config to `package.json` when publish to npm.

```json
// package.json
{
  "main": "lib/index.js",
  "module": "es/index.js",
  "files": ["es", "lib"]
}
```

### build-site

Build documentation website. Files will be output to `site` directory.

### release

Publish to npm. `build` will be automatically execute when run `release`.

### commit-lint

Validate the format of commit message. Need `husky` to do this.

---

## File: packages/vant-cli/docs/commands.zh-CN.md

# 命令

Vant CLI 中内置了一系列的命令，可以将命令添加到 npm scripts 中进行使用。

```json
// package.json
{
  "scripts": {
    "dev": "vant-cli dev",
    "test": "vant-cli test",
    "release": "vant-cli release",
    "build-site": "vant-cli build-site"
  }
}
```

也可以通过 npm 自带的 [npx](https://github.com/npm/npx) 直接执行某个命令：

```bash
npx vant-cli dev
```

### dev

运行本地开发环境。

运行 dev 命令时，Vant CLI 会通过启动一个本地服务器，用于在开发过程中对文档和示例进行预览。

### build

构建组件库。

运行 build 命令会在 `es` 和 `lib` 目录下生成可用于生产环境的组件代码，详见 [目录结构](https://github.com/vant-ui/vant/tree/main/packages/vant-cli/docs/directory.zh-CN.md)。

发布 npm 时，请将以下配置加入到 `package.json` 中，使 npm 包能被正确识别:

```json
// package.json
{
  "main": "lib/index.js",
  "module": "es/index.js",
  "files": ["es", "lib"]
}
```

### build-site

构建文档站点，在 `site` 目录生成可用于生产环境的文档站点代码。

### release

发布组件库，发布前会自动执行 build 命令，并按照流程发布 npm 包。

### commit-lint

校验 commit message 的格式是否符合规范，需要配合 `husky` 在提交 commit 时触发。

---

## File: packages/vant-cli/docs/config.md

# Config

- [Config](#----)
  - [rsbuild.config.mjs](#rsbuildconfigmjs)
  - [vite.config.mjs](#viteconfigmjs)
  - [vant.config.mjs](#vantconfigmjs)
    - [name](#name)
    - [build.css.base](#buildcssbase)
    - [build.css.preprocessor](#buildcsspreprocessor)
    - [build.site.publicPath](#buildsitepublicpath)
    - [build.srcDir](#buildsrcdir)
    - [build.namedExport](#buildnamedexport)
    - [build.packageManager](#buildpackagemanager)
    - [site.title](#sitetitle)
    - [site.logo](#sitelogo)
    - [site.description](#sitedescription)
    - [site.nav](#sitenav)
    - [site.versions](#siteversions)
    - [site.baiduAnalytics](#sitebaiduanalytics)
    - [site.hideSimulator](#sitehidesimulator)
    - [site.simulator.url](#sitesimulatorurl)
    - [site.htmlMeta](#sitehtmlmeta)
    - [site.enableVConsole](#siteenablevconsole)
  - [PostCSS](#postcss)
    - [Default Config](#-----1)
  - [browserslist](#browserslist)

## rsbuild.config.mjs

Vant CLI uses [Rsbuild](https://github.com/web-infra-dev/rsbuild) to build the documentation site. You can create an Rsbuild configuration file in the same directory as `vant.config.mjs`. The contents of the file will be automatically read by Vant CLI.

```js
// rsbuild.config.mjs or rsbuild.config.ts
export default {
  plugins: [
    // Configure Rsbuild plugins
  ],
  dev: {
    // Options related to local development
  },
  html: {
    // Options related to HTML generation
  },
  // Other options
};
```

> Please refer to [Configure Rsbuild](https://rsbuild.dev/guide/basic/configure-rsbuild) for more information.

## vite.config.mjs

Vant Cli uses Vite to build component library code. You can create a Vite configuration file in the same directory as `vant.config.mjs`. In this file, you can add any Vite configuration.

> Please refer to [Vite Configuration](https://vitejs.dev/config/) to learn more.

## vant.config.mjs

`vant.config.mjs` includes bundle and documentation site config. Please create this file and place it in your project root directory. Here is a basic example:

```js
export default {
  // component library name
  name: 'demo-ui',
  // bundle config
  build: {
    site: {
      publicPath: '/demo-ui/',
    },
  },
  // documentation site config
  site: {
    // title
    title: 'Demo UI',
    // logo
    logo: 'https://fastly.jsdelivr.net/npm/@vant/assets/logo.png',
    // description
    // left nav
    nav: [
      {
        title: 'example',
        items: [
          {
            path: 'home',
            title: 'home',
          },
        ],
      },
      {
        title: 'basic components',
        items: [
          {
            path: 'my-button',
            title: 'MyButton',
          },
        ],
      },
    ],
  },
};
```

### name

- Type: `string`
- Default: `''`

Component library name. kebab-case recommended.

### build.css.base

- Type: `string`
- Default: `'style/base.less'`

Global style file path. Support absolute path and relative path both.

Note: relative path is calculated based on `src`.

```js
module.exports = {
  build: {
    css: {
      base: 'style/global.scss',
    },
  },
};
```

### build.css.preprocessor

- Type: `string`
- Default: `'less'`

CSS preprocessor config, support `less` and `sass`. Use `less` by default.

```js
module.exports = {
  build: {
    css: {
      preprocessor: 'sass',
    },
  },
};
```

### build.css.removeSourceFile

- Type: `boolean`
- Default: `'false'`

Whether to remove the source style files after build.

```js
module.exports = {
  build: {
    css: {
      removeSourceFile: true,
    },
  },
};
```

### build.site.publicPath

- Type: `string`
- Default: `/`

Equivalent to vite `build.outDir`.

Generally, documentation site will be deployed to subpath of domain. For example: `https://my.github.io/demo-ui/`, `publicPath` should be `/demo-ui/`.

```js
module.exports = {
  build: {
    site: {
      publicPath: '/demo-ui/',
    },
  },
};
```

### build.srcDir

- Type: `string`
- Default: `src`

```js
module.exports = {
  build: {
    srcDir: 'myDir',
  },
};
```

### build.namedExport

- Type: `boolean`
- Default: `false`

Should export components by Named Export.

When set to `false`, `export default from 'xxx'` will be used to export module.

When set to `true`, `export * from 'xxx'` will be used to export all modules and type definition.

### build.configureVite

- Type: `(config: InlineConfig): InlineConfig | undefined`
- Default: `undefined`

Custom [vite config](https://vitejs.dev/config/), requires `@vant/cli>= 4.0.0`.

```js
module.exports = {
  build: {
    configureVite(config) {
      config.server.port = 3000;
      return config;
    },
  },
};
```

If you need to configure some vite plugins, please create a `vite.config.ts` file in the same directory of `vant.config.mjs`, in which you can add any vite configuration (this feature requires @vant/cli 5.1.0).

### build.packageManager

- Type: `'npm' | 'yarn' | 'pnpm' | 'bun'`
- Default: `yarn`

`npm` package manager.

### build.bundleOptions

- Type: `BundleOptions[]`

Specify the format of the bundled output.

The type of `BundleOptions`:

```ts
type BundleOption = {
  // Whether to minify code (Tips: es format output can't be minified by vite)
  minify?: boolean;
  // Formats, can be set to 'es' | 'cjs' | 'umd' | 'iife'
  formats: LibraryFormats[];
  // Dependencies to external (Vue is externaled by default)
  external?: string[];
};
```

Default value：

```ts
const DEFAULT_OPTIONS: BundleOption[] = [
  {
    minify: false,
    formats: ['umd'],
  },
  {
    minify: true,
    formats: ['umd'],
  },
  {
    minify: false,
    formats: ['es', 'cjs'],
    external: allDependencies,
  },
];
```

### site.title

- Type: `string`
- Default: `''`

Documentation site title.

### site.logo

- Type: `string`
- Default: `''`

Documentation site logo.

### site.description

- Type: `string`
- Default: `''`

Documentation site description.

### site.nav

- Type: `object[]`
- Default: `undefined`

Documentation site left nav. Each item of `nav` means a navigation group.

```js
module.exports = {
  site: {
    nav: [
      {
        // group title
        title: 'Development Guide',
        // nav items
        items: [
          {
            // nav router
            path: 'home',
            // nav title
            title: 'title',
            // should hide phone emulator(false by default)
            hideSimulator: true,
          },
        ],
      },
    ],
  },
};
```

### site.versions

- Type: `object[]`
- Default: `undefined`

Documentation site muti-version config.

```js
module.exports = {
  site: {
    versions: [
      {
        label: 'v1',
        link: '/v1/',
      },
    ],
  },
};
```

### site.baiduAnalytics

- Type: `object`
- Default: `undefined`

Documentation site baidu analysis config. The script of Baidu Statistic will be automatically loaded when build documentation website.

```js
module.exports = {
  site: {
    baiduAnalytics: {
      // 打开百度统计 ->『管理』->『代码获取』
      // find the followed URL: "https://hm.baidu.com/hm.js?xxxxx"
      // add `xxxxx` in the seed
      seed: 'xxxxx',
    },
  },
};
```

### site.hideSimulator

- Type: `boolean`
- Default: `false`

Should hide phone emulator, `false` by default.

### site.simulator.url

- Type: `string`
- Default: -

Customize iframe URL.

### site.htmlMeta

- Type: `Record<string, string>`
- Default: `undefined`

Customize HTML meta tag, key means name, value means content.

### site.headHtml

- Type: `string`
- Default: `undefined`

Insert a custom HTML content in the `<head>` tag.

### site.enableVConsole

- Type: `boolean`
- Default: `false`

Whether to enable [vConsole](https://github.com/Tencent/vConsole) debugging in dev, usually used for mobile debugging.

## PostCSS

PostCSS can be configured through the `postcss.config.js` file in the root directory.

### Default Config

PostCSS default config:

```js
module.exports = {
  plugins: {
    autoprefixer: {},
  },
};
```

## browserslist

Add browserslist field to `package.json` file is recommended. It's used by `autoprefixer` to determine the version of target browser, ensuring compatibility of compiled code.

You can add the following config for mobile:

```json
{
  "browserslist": ["Chrome >= 51", "iOS >= 10"]
}
```