Vant 4: the Vue mobile UI library you install with npm i vant

The problem Vant solves for Vue mobile teams

A mobile H5 product in Vue needs a lot of small widgets that a desktop component library does not ship: a numeric keypad, a pull-to-refresh list, a picker, a popup that respects safe areas. Building those in-house is a month of work that has nothing to do with your product. Vant is a Vue component library aimed exactly at that gap. The README describes it as "A lightweight, customizable Vue UI library for mobile web apps" and lists 80+ components with an average size of 1KB per component (min+gzip).

The audience is narrow and specific. You are writing a Vue application that runs in a mobile browser, or inside a WebView, and you want the component layer handled. It is not a desktop admin library and it is not a cross-framework abstraction. The repository is a pnpm workspace under packages/, and the published package is vant. If you are not in Vue, the README's own answer is a community port: react-vant for React, Taroify for Taro, @antmjs/vantui for Taro and React. Those are separate projects with separate maintainers, which is worth knowing before you pick Vant for a React codebase.

How Vant is packaged: per-component registration and tree shaking

The mechanism that matters is that Vant does not force a global install of everything. The Quickstart imports one component and registers it on the app instance, then imports a single stylesheet. Tree shaking is listed as a feature, so bundlers that support it drop the components you never import. This is why the 1KB average size figure is meaningful: you pay for the components you actually use, not for the 80+ total.

Styling is a separate axis. The README lists Custom Theme and Dark Mode as supported, and ships Sketch and Axure design resources, which suggests the intended workflow is that a designer works from the same component vocabulary the developer implements. The library has zero third-party dependencies, so it does not drag a date library or a utility belt into your bundle. It is written in TypeScript, and the README claims 90%+ unit test coverage. Vant also supports SSR and i18n with 30+ built-in languages, and the Nuxt integration is handled by a separate vant-nuxt module rather than being baked into the core package.

Version support is split by major. Vant 2 targets Vue 2, Vant 3 and 4 target Vue 3, and browser floors differ accordingly: Vant 2 covers Android >= 4.0 and iOS >= 8.0, while Vant 3/4 follow Vue 3 with Chrome >= 51 and iOS >= 10.0. That split is the first decision you make, before any component choice.

Installing Vant and registering your first component

The README gives the install command directly. Pick the line that matches your Vue version; installing the wrong major is the most common first mistake.

# install latest Vant for Vue 3 project
npm i vant

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

Yarn, pnpm and Bun are also documented, with yarn add vant, pnpm add vant and bun add vant respectively.

For the scaffold, the README recommends Rsbuild rather than listing a Vant-specific starter. It notes that Rsbuild is built on Rspack and developed by the author of Vant, and that it provides first-priority support for Vant. The command is:

npm create rsbuild@latest

Once the project exists, the Quickstart shows the smallest working integration: import the component, import the stylesheet, register the component on the app. Note that the stylesheet path is the full bundle, not a per-component style file.

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

After this runs, the Button component is available in your templates. If you are checking the result in a desktop browser rather than a phone or a device emulator, the README lists a separate package, vant-touch-emulator, described as "Using vant in desktop browsers". That is the piece people miss when touch interactions appear dead on a laptop.

Where Vant is the wrong choice

The clearest failure mode is framework mismatch. Vant is a Vue library. If your application is React, the README's own ecosystem table points you to react-vant, described as "React mobile UI Components based on Vant", or to @antmjs/vantui for Taro and React. Those are not the same package and not the same maintainers, so adopting Vant in a React project means adopting a downstream port with its own release cadence.

The second boundary is the version split. Vant 2 and Vant 3/4 are different lines with different browser floors. A team on Vue 2 that installs the default vant package gets Vant 4, which is built for Vue 3. The README handles this with the vant@latest-v2 tag, but the tag is easy to overlook when copying the first command you see.

Accessibility is the other honest caveat. The README lists it as a feature with the parenthetical "still improving". That phrasing comes from the project itself, and it tells you not to treat Vant as a finished accessibility story. If your product has a formal accessibility requirement, the component library will be part of the audit, not a way to skip it. The README does not document a rollback path for a component upgrade, so version pinning is on you.

Vant compared with a port or a cross-platform layer

The real alternative depends on where your code has to run. If it runs in a browser and you write Vue, Vant is the direct answer and the alternatives are other Vue mobile libraries with their own component sets and theming models. The difference is not just component count; it is whether the library ships a theme system, a design resource set, and a scaffold its own author supports. Vant does all three, and the README states the Rsbuild connection explicitly.

If your code has to run in a WeChat MiniProgram, Vant itself is not the tool. The README's ecosystem table lists vant-weapp as "WeChat MiniProgram UI", a sibling project rather than a build target of the main library. A team that assumes one Vant install covers both the H5 app and the MiniProgram will find two codebases.

If your code has to run in Taro or React, the difference is bigger than a wrapper. Taroify is described as "the Taro version of Vant", and @antmjs/vantui as mobile UI components based on Vant supporting Taro and React. These projects carry the API shape forward into a different rendering target. The trade-off is that you inherit their release schedule instead of Vant's, and the changelog you read is theirs, not youzan/vant's.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-18. The release history shows v4.10.2 on 2026-08-31, 4.10.1 on 2026-08-30 and v4.10.0 on 2026-06-28, so the 4.x line is receiving patch releases within the last few weeks. That is the whole of what the available facts support; there is no published support window or end-of-life policy in the README.

The licence is MIT, which is permissive and places few obligations on how you redistribute the library. That is a statement about the licence identifier in the repository, not legal advice; if you vendor or fork the code, read the LICENSE file at the repository root yourself.

Upgrade cost is dominated by the major version split rather than by patch releases. Moving from Vant 2 to Vant 3/4 is a Vue 2 to Vue 3 migration first and a component migration second, and the browser floor moves with it. The repository is a pnpm workspace with a pinned packageManager of [email protected] and an engines requirement of pnpm >= 10.33.2, so anyone building Vant from source rather than consuming the npm package needs that pnpm version. The root scripts route through pnpm --dir ./packages/vant for dev, test and build, which tells you the published package lives in packages/vant and the rest of packages/ holds tooling such as vant-cli, vant-icons and vant-touch-emulator.

Editorial conclusion

Adopt Vant if you are building a Vue 3 or Vue 2 H5 product and want a component set that registers per component and tree-shakes. Do not adopt it if your app is React or Taro, where the README points to community ports instead. Before committing, verify three things in the documentation: which major version matches your Vue version, whether the components you need are covered, and whether you need the vant-touch-emulator package because you are developing in a desktop browser.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. youzan/vant on GitHub