vant/packages/vant/docs/markdown/quickstart.en-US.md

Quickstart

Install

npm

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

CDN

The easiest way to use Vant is to include a CDN link in the HTML file, after which you can access all components via the global variable vant.

<!-- import style -->
<link
  rel="stylesheet"
  href="https://fastly.jsdelivr.net/npm/vant@4/lib/index.css"
/>

<!-- import script -->
<script src="https://fastly.jsdelivr.net/npm/vue@3"></script>
<script src="https://fastly.jsdelivr.net/npm/vant@4/lib/vant.min.js"></script>

<script>
  // Render the Button component
  const app = Vue.createApp({
    template: `<van-button>Button</van-button>`,
  });
  app.use(vant);

  // Register Lazyload directive
  app.use(vant.Lazyload);

  // Call function component
  vant.showToast('Message');

  app.mount('#app');
</script>

Free CDN

You can use Vant through these free CDN services:

• jsdelivr
• cdnjs
• unpkg

Note: Free CDN is generally used for making prototypes or personal projects. It is not recommended to use free CDN in production environment.

For enterprise developers, we recommend:

• install with npm, use build tools to bundle it
• download the scripts, host it on your own server

CLI

We recommend to use Vite to create a new project.

# npm 6.x
npm create vite@latest my-vue-app --template vue

# npm 7+, extra double-dash is needed:
npm create vite@latest my-vue-app -- --template vue

# yarn
yarn create vite my-vue-app --template vue

# pnpm
pnpm create vite my-vue-app --template vue

then

cd my-vue-app

# with npm
npm install vant

# with yarn
yarn add vant

# with pnpm
pnpm add vant

Usage

Basic Usage

The basic usage of Vant components:

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

Tip: Vant supports Tree Shaking by default, so you don't need to configure any plugins, the unused JS code will be removed by Tree Shaking, but CSS styles cannot be optimized by it.

Import on demand

If you are using vite, webpack or vue-cli, you can use unplugin-vue-components, this plugin can help you to auto importing components.

Vant officially wrote an automatic import style parser @vant/auto-import-resolver based on unplugin-vue-components, both of which are used together.

Compared with conventional usage, this method can introduce the CSS style of components on demand, thus reducing part of the code volume, but it will become more cumbersome to use. If the business's volume requirements for CSS are not particularly extreme, we recommend a simpler general usage.

1. Install Plugin

# with npm
npm i @vant/auto-import-resolver unplugin-vue-components -D

# with yarn
yarn add @vant/auto-import-resolver unplugin-vue-components -D

# with pnpm
pnpm add @vant/auto-import-resolver unplugin-vue-components -D

# with Bun
bun add @vant/auto-import-resolver unplugin-vue-components -D

2. Configure Plugin

For vite based project，configure the plugin in the vite.config.js file:

import vue from '@vitejs/plugin-vue';
import Components from 'unplugin-vue-components/vite';
import { VantResolver } from '@vant/auto-import-resolver';

export default {
  plugins: [
    vue(),
    Components({
      resolvers: [VantResolver()],
    }),
  ],
};

For vue-cli based project，configure the plugin in the vue.config.js file:

const { VantResolver } = require('@vant/auto-import-resolver');
const ComponentsPlugin = require('unplugin-vue-components/webpack');

module.exports = {
  configureWebpack: {
    plugins: [
      ComponentsPlugin({
        resolvers: [VantResolver()],
      }),
    ],
  },
};

For webpack based project，configure the plugin in the webpack.config.js file:

const { VantResolver } = require('@vant/auto-import-resolver');
const ComponentsPlugin = require('unplugin-vue-components/webpack');

module.exports = {
  plugins: [
    ComponentsPlugin({
      resolvers: [VantResolver()],
    }),
  ],
};

3. Using Components

Then you can using components from Vant in the template, the unplugin-vue-components will automatically import the corresponding Vant components,@vant/auto-import-resolver The corresponding component style will be automatically introduced.

<template>
  <van-button type="primary" />
</template>

4. Style of Function Components

Some components of Vant are provided as function, including Toast, Dialog, Notify and ImagePreview. When using function components, unplugin-vue-components cannot parse the automatic registration component, resulting in @vant/auto-import-resolver unable to parse the style, so the style needs to be introduced manually.

// Toast
import { showToast } from 'vant';
import 'vant/es/toast/style';

// Dialog
import { showDialog } from 'vant';
import 'vant/es/dialog/style';

// Notify
import { showNotify } from 'vant';
import 'vant/es/notify/style';

// ImagePreview
import { showImagePreview } from 'vant';
import 'vant/es/image-preview/style';

Tip: "Full Import" and "On-demand Import" should not be used at the same time, otherwise it will lead to problems such as code duplication and style overrides.

Tips

• "Full Import" and "On-demand Import" should not be used at the same time, otherwise it will lead to problems such as code duplication and style overrides.
• During use, if the component cannot be imported, because unplugin-vue-components is not a plug-in officially maintained by Vant, it is recommended to give feedback under the antfu/unplugin-vue-components repository.
• If it is a similar problem that the style does not take effect, feedback under the Vant repository

With Frameworks

Use Vant in Nuxt 3

When using Vant in Nuxt 3, you can use vant-nuxt, this module can help you to auto importing components and reduce CSS file size.

1. Install Module

# with npm
npm i @vant/nuxt -D

# with yarn
yarn add @vant/nuxt -D

# with pnpm
pnpm add @vant/nuxt -D

# with Bun
bun add @vant/nuxt -D

2. Add Module

add the module in the nuxt.config.js file:

export default defineNuxtConfig({
  modules: ['@vant/nuxt'],
});

3. Using Components

Then you can using components from Vant in the template, Go to the Nuxt documentation to learn more.

<template>
  <van-button type="primary" @click="showToast('toast')">button</van-button>
  <VanButton type="success" @click="showNotify('notify')">button</VanButton>
  <LazyVanButton type="default">lazy button</LazyVanButton>
</template>