Vant: Mobile UI Components for Vue

Common errors

• Error: Failed to resolve component: van-button

  cause Vant component was used in a Vue template but not registered with the Vue app.
  fix Ensure all Vant components used in templates are explicitly registered with your Vue application instance via `app.use(ComponentName);` or are automatically imported through a build tool plugin.

• TypeError: Cannot read properties of undefined (reading 'use')

  cause Attempting to use `app.use()` on a Vant component that is not a plugin or trying to access a method on an undefined Vant export.
  fix Verify the correct import path and ensure the symbol being used is indeed a Vue plugin (e.g., `Button` is not a plugin directly, but a component. `Toast` or `Dialog` can be installed as plugins or used via their API methods after importing their functions).

• Uncaught SyntaxError: Cannot use import statement outside a module

  cause Attempting to use ES module `import` syntax in an environment that expects CommonJS (e.g., Node.js script without `--experimental-modules` or misconfigured Webpack/Rollup).
  fix Ensure your project is configured for ES modules, typically by setting `"type": "module"` in `package.json` or by using a modern bundler like Vite/Webpack configured for ESM output. If targeting an older Node.js environment, consider a transpilation step.

Warnings

• breaking Vant 3.x and 4.x are designed for Vue 3. Migrating from Vant 2.x (Vue 2) to Vant 3.x/4.x requires upgrading your Vue project to Vue 3, which involves significant breaking changes in Vue itself.
  Fix: For Vue 3 projects, use `npm i vant`. For Vue 2 projects, use `npm i vant@latest-v2`. Review the official Vant 3/4 migration guide and Vue 3 migration guide for detailed steps.
• gotcha Forgetting to import the global Vant CSS file (`vant/lib/index.css`) will result in components rendering without any styling, appearing as plain HTML elements.
  Fix: Ensure `import 'vant/lib/index.css';` is included in your main application entry file (e.g., `main.js`/`main.ts`) or a global style entry point. If using a CSS preprocessor, you might need to import the `.less` or `.scss` variant and configure your build.
• gotcha When using on-demand import (e.g., with `unplugin-vue-components` or `vite-plugin-components`), ensure the Vant resolver is correctly configured, otherwise components might not be automatically imported or their styles may be missing.
  Fix: Refer to the Vant documentation for the specific auto-import resolver (e.g., `@vant/auto-import-resolver`) and its configuration in your build tool (Vite, Webpack, etc.). Often, a post-processor like PostCSS is also required for proper theme customization and unit conversion.
• deprecated Older versions of Vant might have exposed components directly via `vant/es/{componentName}`, but the recommended and tree-shakable way is to use named imports from the main `vant` package.
  Fix: Always use `import { ComponentName } from 'vant';` for individual components to leverage tree-shaking effectively. If you are using a bundler with proper configuration (e.g., Vite), this should work out of the box.
• gotcha Vant components are designed for mobile environments. Using them directly in desktop browsers might lead to unexpected layout or interaction issues without `vant-touch-emulator` or proper desktop styling.
  Fix: For desktop development or testing, consider installing and importing `vant-touch-emulator` to simulate touch events. For production desktop apps, consider a different UI library or extensive custom styling for Vant components.

Install

• npm install vant npm
• yarn add vant yarn
• pnpm add vant pnpm

Imports

• Button
  wrong:

  import Button from 'vant/es/button'; // Older, less common, or direct import if not using tree-shaking setup
  const Button = require('vant').Button; // CommonJS is not the primary way for Vue components, especially with tree-shaking

  correct:

  import { Button } from 'vant';

  Vant supports tree-shaking, so named imports are recommended. Manual import of specific components is also possible, but `vant` exports components directly for convenience.
• CSS Styles
  wrong:

  import 'vant/es/index.css'; // Incorrect path for modern Vant 4
  import 'vant/lib/index.less'; // If using Less, requires pre-processing
  import 'vant/lib/index.scss'; // If using Sass, requires pre-processing

  correct:

  import 'vant/lib/index.css';

  The core CSS styles are crucial for Vant components to render correctly. This import should be placed globally or at the root of your application. Ensure your build tool handles CSS imports.
• Locale
  wrong:

  import { useLocale } from 'vant'; // Incorrect hook name for global locale config

  correct:

  import { Locale } from 'vant';
  Locale.use('en-US');

  For global locale configuration, import `Locale` and use its `use` method. This sets the language for all Vant components.

Quickstart

This quickstart demonstrates how to set up a basic Vue 3 application, import Vant components (Button, Toast), register them globally, and include the necessary CSS styles to render a functional Vant button and show a toast message.

import { createApp } from 'vue';
import { Button, Toast } from 'vant';
import 'vant/lib/index.css';

const app = createApp({
  template: `
    <van-button type="primary" @click="showToast">Click me</van-button>
  `,
  methods: {
    showToast() {
      Toast('Hello Vant!');
    }
  }
});

app.use(Button);
app.use(Toast);

app.mount('#app');