Vant 4.0 was officially released last week. The release announcement reads that this is the fourth major release of Vant since it was open-sourced in 2017.

In this iteration, Vant supports the dark mode, adds five new components, improves the utility function API and refactors components such as Picker, while continuing to make improvements in terms of lightweight and usability.

Support dark mode

Vant 4.0 supports switching all components to dark mode.

just put ConfigProvider component’s theme property is set to darkto switch to dark mode, turning all Vant components on the page into a dark style.

<van-config-provider theme="dark">
  <!-- child components -->
</van-config-provider>

At the same time, the Vant 4.0 document also supports switching to dark mode:

several new components

Vant 4.0 includes the following new components:

Among them, TimePicker and DatePicker are split from the old DatetimePicker component, and the DatetimePicker component is no longer provided. You can use PickerGroup to realize the interactive effect of selecting date and time at the same time.

keep it light

The installation volume of Vant 4.0 is reduced by 30%, and the package volume remains light.

As the npm ecosystem grows, node_modules are eating up our disk space. To alleviate the node_modules black hole and speed up installation, we optimized Vant’s npm dependencies and build artifacts.

Compared with Vant 3.6.2, the installation volume of Vant 4.0.0 is reduced from 7MB to 5MB. As a comparison, the installation volume of mainstream component libraries in the community is generally between 15MB and 80MB.you can pass packagephobia to query the installation volume of the npm package.

In terms of package volume, this update still increases the volume without increasing the price, and the volume after Minified + Gzipped remains below 70KB:

unified main color

Vant 4.0 unifies the main color of all components.

In previous versions, Vant components had two main colors, with some components in blue #1989fa As the main color, the other part is red #ee0a24.

In order to maintain the consistency of the color specification, we have unified the main color in Vant 4, and all components use blue as the main color.

After the main color is unified, theme customization will become easier.For example, you can override --van-primary-color This CSS variable sets the primary color of all components to green:

:root {
  --van-primary-color: #07c160;
}

Import mode adjustment as needed

Vant 4.0 no longer uses babel-plugin-import for on-demand imports.

In the early days, component libraries mostly used babel-plugin-import Implement on-demand import, which means that the component library will strongly rely on Babel compilation.Starting with Vant 4.0, it will no longer be supported babel-plugin-importwhich mainly brings the following benefits:

• Instead of relying heavily on Babel compilation, projects can use modern compilation tools such as SWC and esbuild to improve compilation efficiency.

• no longer subject to babel-plugin-import import restrictions, you can import content other than components from Vant, such as the new one in Vant 4 showToast method, or buttonProps object:

import { showToast, buttonProps } from 'vant';

In terms of package size, remove babel-plugin-import It will not affect the JS size of the project, because Vant supports Tree Shaking to remove unnecessary JS code by default, and CSS code can be removed through unplugin-vue-components The plug-in can be imported on demand, please refer to the detailed usage “Quick start”.

Style variable type hints

Vant 4.0 provides type hints for style variables.

Vant provides more than 700 style variables, you can pass CSS code or ConfigProvider Components modify these style variables.In Vant 4.0, we have added ConfigProviderThemeVars type to provide type hints for style variables.

So when writing TypeScript code, you can use type hints to complete theme variable names:

Picker component refactoring

Vant 4.0 refactored the Picker component, as well as the Picker-based Area and DatetimePicker components.

In previous versions,Picker The API design of the component is not reasonable enough, causing you to often encounter problems when using it, such as:

• Picker’s columns data format is unreasonable, easy to cause misunderstanding.
• The data flow of Picker is not clear, exposing too many instance methods to operate on the data.
• The logic of DatetimePicker is too complex, and bugs often appear in borderline scenarios.

In order to solve the above problems, in Vant 4.0, we Picker Components were refactored, and also based on Picker Derived Area and DatetimePicker components.

If you use these three components in your project, please read “Upgrade Guide” to upgrade.

Component tool function adjustment

Vant 4.0 adjusts the usage of component utility functions to be more intuitive.

Vant 3 provides some component utility functions, such as calling Dialog() function, which can quickly evoke the global pop-up window component, and Dialog.Component is Dialog The corresponding component object.

// 函数调用
Dialog({ message: 'Hello World!' });

// 组件注册
app.use('van-dialog', Dialog.Component);

The above API design leads to differences in usage between components supporting tool functions such as Dialog and conventional components, and is easy to be misused; it also leads to unplugin-vue-components Components such as Dialog cannot be automatically introduced.

In order to be more intuitive, we have adjusted the calling method of component tool functions in Vant 4. The affected functions include Dialog(),Toast(),Notify() and ImagePreview().Using Dialog as an example, we will Dialog() The function is renamed to showDialog()and let Dialog Points directly to the component object.

// 函数调用
showDialog({ message: 'Hello World!' });

// 组件注册
app.use('van-dialog', Dialog);

In order to facilitate the migration of stock codes to Vant 4.0, we provide a compatible solution, you can use @vant/compat exported from Dialog() function to be compatible with the original code.

import { Dialog } from '@vant/compat';

Dialog({ message: 'Hello World!' });

@vant/compat exported from Dialog() with the Vant 3 Dialog() It has completely consistent API and behavior, so when upgrading, you only need to modify its reference path, and the rest of the code can remain unchanged.After the project is upgraded to Vant 4.0, it is recommended to gradually replace it with the new one in iterations showDialog() and so on, and remove @vant/compat Bag.

Event Naming Adjustment

Vant 4.0 changes event names to camel case.

Starting from Vant 4, all events are named in the camelCase format officially recommended by Vue.

// Vant 3
emit('click-input');

// Vant 4
emit('clickInput');

this changeDoes not affect the original template codeVue will automatically format the event name in the template, so you don’t have to make any changes.

<!-- 以下代码可以照常运行，无须做任何更改 -->
<van-field @click-input="onClick" />

If you use the Vant component in JSX, you need to adjust the monitored event name to camel case format, the original dash format will no longer take effect, and the new monitoring method is more in line with JSX’s own specifications:

// Vant 3
<Field onClick-input={onClick} />

// Vant 4
<Field onClickInput={onClick} />

Remove the Less variable

Vant 4.0 no longer supports theme customization via Less variables.

Currently Vant already supports theme customization based on CSS variables, which is more flexible than Less customization. Therefore, Vant 4 will no longer provide Less-based theme customization.This means that Vant’s npm package will no longer contain .less style source files, only the compiled .css style file.

If your project is using an older version of the Less theme customization, use ConfigProvider global configuration to replace.

Vant Cli 5.0

This update releases the Vant Cli 5.0 version simultaneously.

Vant Cli It is the underlying component library construction tool of Vant. The content of this update includes:

• Upgrade Vite to version 3.0, and upgrade related Vite plug-ins.
• no longer installed by default stylelint and @vant/stylelint-config Dependency, if necessary, you can install it yourself:

npm add stylelint@13 @vant/stylelint-config

• no longer installed by default gh-pages Dependency, please update package.json as follows:

- "release:site": "pnpm build:site && gh-pages -d site-dist",
+ "release:site": "pnpm build:site && npx gh-pages -d site-dist",

Version Information

Currently Vant official website and npm latest tags already point to Vant 4.0.

We have prepared a complete upgrade guide for Vant 4.0, please read Upgrade from v3 to v4 to upgrade.

At the same time, Vant 3.x will also enter the maintenance state, and the maintenance status of each subsequent version of Vant is as follows: