What’s New in NutUI 4.0? A Deep Dive into Features, Performance Gains, and Migration Tips

Overview

NutUI 4.0 released after three months of development and internal testing. It continues the evolution from v1‑v3, addressing compatibility and adding new capabilities.

New Features

CSS‑variables Dynamic Theme

Supports runtime theme switching by overriding CSS variables on the :root node. The ConfigProvider component accepts a :theme-vars prop. Example:

<script setup lang="ts">
  const themeVars = reactive({ buttonBorderRadius: '10px' });
</script>
<template>
  <nut-config-provider :theme-vars="themeVars">
    <nut-button type="primary">Primary Button</nut-button>
  </nut-config-provider>
</template>

Dedicated Icon Library

Separate packages @nutui/icons-vue (Vue) and @nutui/icons-vue-taro (Taro) replace the monolithic icon component, reducing the main package size by ~464 kB. Icons can be imported on demand or via IconFont:

import { Add } from '@nutui/icons-vue';
<Add color="red" />

import { IconFont } from '@nutui/icons-vue';
<IconFont name="dongdong" />

Automatic On‑Demand Import

Integrates unplugin-vue-components to automatically import components and their styles. This removes the need for babel-plugin-import and vite-plugin-style-import and works with Vite, Webpack, Vue CLI, SWC, esbuild, etc. Component name changes include nut-fixednav → nut-fixed-nav, nut-checkBoxgroup → nut-checkBox-group.

New Components

Tour – step‑by‑step user guide.

PullRefresh – pull‑to‑refresh interaction.

Component Enhancements

More than 20 components received breaking‑change updates for flexibility and reusability. Highlights:

ShortPassword now uses NumberKeyboard instead of the native keyboard.

Input props streamlined for seamless Form integration.

InfiniteLoading removed its pull‑to‑refresh feature.

Picker no longer embeds a Popup, enabling flat display.

Lightweight Optimizations

Installation size reduced from 14 MB (v3.3.1) to 8 MB (≈42 % reduction).

Package size on packagephobia decreased from 3.81 MB to 2.3 MB (≈39 % reduction).

Component‑level code shaving over 50 kB by removing unused code and third‑party dependencies (e.g., Popover now has zero external deps).

Icon Library Size Reduction

The dedicated icon library cuts ~595 kB from the total bundle and removes 125 font files, saving an additional ~464 kB. On‑demand icon imports typically reduce project bundle size by ~50 kB.

Build Tool and Type Declaration Upgrades

Vite upgraded from version 2 to version 4, shaving ~10 seconds from build time. Type declarations are now generated with vue-tsc instead of vite-plugin-dts, providing better integration with the Volar extension.

Resources

GitHub repository: https://github.com/jdf2e/nutui