File: README.md Copy Chapter

Vant

Features Copy Chapter

• 🚀 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 for Nuxt
• 🍭 Support Tree Shaking
• 🍭 Support Custom Theme
• 🍭 Support Accessibility (still improving)
• 🍭 Support Dark Mode
• 🍭 Support SSR
• 🌍 Support i18n, built-in 30+ languages

Install Copy Chapter

Using npm to install:

# 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:

# with yarn
yarn add vant

# with pnpm
pnpm add vant

# with Bun
bun add vant

Scaffold Copy Chapter

It is recommended to use 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:

npm create rsbuild@latest

Please visit the Rsbuild repository for more information.

Quickstart Copy Chapter

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.

Browser Support Copy Chapter

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 Copy Chapter

Community Ecosystem Copy Chapter

Links Copy Chapter

• Documentation
• Documentation (backup)
• Changelog
• Discussions

Preview Copy Chapter

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

Core Team Copy Chapter

Core contributors of Vant and Vant Weapp:

Contribution Guide Copy Chapter

Please make sure to read the Contributing Guide before making a pull request.

Start On Web IDE Copy Chapter

https://github.dev/youzan/vant

LICENSE Copy Chapter

Vant is MIT licensed.

File: packages/vant-use/README.md Copy Chapter

Vant Use

Built-in composition APIs of Vant.

Install Copy Chapter

# 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 Copy Chapter

Vant Touch Emulator

在桌面端上模拟移动端 touch 事件，实现方式来自于 hammerjs/touchemulator.

Install Copy Chapter

# 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

使用指南 Copy Chapter

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

import '@vant/touch-emulator';

CDN 引入 Copy Chapter

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

禁用 touch 模拟 Copy Chapter

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

File: packages/vant-popperjs/README.md Copy Chapter

@vant/popperjs

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

Install Copy Chapter

# 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 Copy Chapter

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

Refer Copy Chapter

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

File: packages/vant-icons/README.md Copy Chapter

Vant Icons

Install Copy Chapter

# 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 Copy Chapter

• Usage in Vue
• Usage in Weapp

File: packages/vant-compat/README.md Copy Chapter

@vant/compat

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

Install Copy Chapter

# 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 Copy Chapter

// 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 Copy Chapter

Commands

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

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

Additionally, npx can used to be run those commands.

npx vant-cli dev

dev Copy Section

Start local dev server for browsering components and demo.

build Copy Section

Build Vue component library.

Files will be output to es and lib directory. More details directory structure

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

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

build-site Copy Section

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

release Copy Section

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

commit-lint Copy Section

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

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

命令

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

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

也可以通过 npm 自带的 npx 直接执行某个命令：

npx vant-cli dev

dev Copy Section

运行本地开发环境。

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

build Copy Section

构建组件库。

运行 build 命令会在 es 和 lib 目录下生成可用于生产环境的组件代码，详见 目录结构。

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

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

build-site Copy Section

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

release Copy Section

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

commit-lint Copy Section

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

File: packages/vant-cli/docs/config.md Copy Chapter

Config

• Config
  • rsbuild.config.mjs
  • vite.config.mjs
  • vant.config.mjs
    • name
    • build.css.base
    • build.css.preprocessor
    • build.site.publicPath
    • build.srcDir
    • build.namedExport
    • build.packageManager
    • site.title
    • site.logo
    • site.description
    • site.nav
    • site.versions
    • site.baiduAnalytics
    • site.hideSimulator
    • site.simulator.url
    • site.htmlMeta
    • site.enableVConsole
  • PostCSS
    • Default Config
  • browserslist

rsbuild.config.mjs Copy Chapter

Vant CLI uses 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.

// 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 for more information.

vite.config.mjs Copy Chapter

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 to learn more.

vant.config.mjs Copy Chapter

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:

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 Copy Section

• Type: string
• Default: ''

Component library name. kebab-case recommended.

build.css.base Copy Section

• 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.

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

build.css.preprocessor Copy Section

• Type: string
• Default: 'less'

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

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

build.css.removeSourceFile Copy Section

• Type: boolean
• Default: 'false'

Whether to remove the source style files after build.

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

build.site.publicPath Copy Section

• 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/.

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

build.srcDir Copy Section

• Type: string
• Default: src

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

build.namedExport Copy Section

• 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 Copy Section

• Type: (config: InlineConfig): InlineConfig | undefined
• Default: undefined

Custom vite config, requires @vant/cli>= 4.0.0.

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 Copy Section

• Type: 'npm' | 'yarn' | 'pnpm' | 'bun'
• Default: yarn

npm package manager.

build.bundleOptions Copy Section

• Type: BundleOptions[]

Specify the format of the bundled output.

The type of BundleOptions:

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：

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

site.title Copy Section

• Type: string
• Default: ''

Documentation site title.

site.logo Copy Section

• Type: string
• Default: ''

Documentation site logo.

site.description Copy Section

• Type: string
• Default: ''

Documentation site description.

site.nav Copy Section

• Type: object[]
• Default: undefined

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

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 Copy Section

• Type: object[]
• Default: undefined

Documentation site muti-version config.

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

site.baiduAnalytics Copy Section

• Type: object
• Default: undefined

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

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

site.hideSimulator Copy Section

• Type: boolean
• Default: false

Should hide phone emulator, false by default.

site.simulator.url Copy Section

• Type: string
• Default: -

Customize iframe URL.

site.htmlMeta Copy Section

• Type: Record<string, string>
• Default: undefined

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

site.headHtml Copy Section

• Type: string
• Default: undefined

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

site.enableVConsole Copy Section

• Type: boolean
• Default: false

Whether to enable vConsole debugging in dev, usually used for mobile debugging.

PostCSS Copy Chapter

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

Default Config Copy Section

PostCSS default config:

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

browserslist Copy Chapter

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:

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