{"id":15258,"library":"vant","title":"Vant: Mobile UI Components for Vue","description":"Vant is a lightweight and highly customizable UI component library designed for mobile web applications built with Vue.js. The current stable version series is 4.x, specifically 4.9.24 for Vue 3 projects, while Vant 2.x (e.g., 2.13.9) continues to support Vue 2. The library maintains an active release cadence, frequently adding new features, bug fixes, and improvements within its major versions. Key differentiators include its small bundle size (1KB average per component min+gzip), over 80 high-quality components, zero third-party dependencies, strong TypeScript support, extensive documentation, and comprehensive feature set including tree-shaking, custom themes, accessibility, dark mode, SSR, and i18n with 30+ built-in languages. It also provides dedicated modules for Nuxt 2 and Nuxt 3.","status":"active","version":"4.9.24","language":"javascript","source_language":"en","source_url":"https://github.com/vant-ui/vant","tags":["javascript","ui","vue","vue3","mobile","frontend","component","components","typescript"],"install":[{"cmd":"npm install vant","lang":"bash","label":"npm"},{"cmd":"yarn add vant","lang":"bash","label":"yarn"},{"cmd":"pnpm add vant","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Vant components are built on Vue and require Vue 3.x for Vant 4.x, or Vue 2.x for Vant 2.x.","package":"vue","optional":false}],"imports":[{"note":"Vant supports tree-shaking, so named imports are recommended. Manual import of specific components is also possible, but `vant` exports components directly for convenience.","wrong":"import Button from 'vant/es/button'; // Older, less common, or direct import if not using tree-shaking setup\nconst Button = require('vant').Button; // CommonJS is not the primary way for Vue components, especially with tree-shaking","symbol":"Button","correct":"import { Button } from 'vant';"},{"note":"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.","wrong":"import 'vant/es/index.css'; // Incorrect path for modern Vant 4\nimport 'vant/lib/index.less'; // If using Less, requires pre-processing\nimport 'vant/lib/index.scss'; // If using Sass, requires pre-processing","symbol":"CSS Styles","correct":"import 'vant/lib/index.css';"},{"note":"For global locale configuration, import `Locale` and use its `use` method. This sets the language for all Vant components.","wrong":"import { useLocale } from 'vant'; // Incorrect hook name for global locale config","symbol":"Locale","correct":"import { Locale } from 'vant';\nLocale.use('en-US');"}],"quickstart":{"code":"import { createApp } from 'vue';\nimport { Button, Toast } from 'vant';\nimport 'vant/lib/index.css';\n\nconst app = createApp({\n  template: `\n    <van-button type=\"primary\" @click=\"showToast\">Click me</van-button>\n  `,\n  methods: {\n    showToast() {\n      Toast('Hello Vant!');\n    }\n  }\n});\n\napp.use(Button);\napp.use(Toast);\n\napp.mount('#app');","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Vant component was used in a Vue template but not registered with the Vue app.","error":"Error: Failed to resolve component: van-button"},{"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).","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.","error":"TypeError: Cannot read properties of undefined (reading 'use')"},{"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.","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).","error":"Uncaught SyntaxError: Cannot use import statement outside a module"}],"ecosystem":"npm"}