完全迁移

第 1 步：更新依赖项

更新反应

v3 需要 React 19+。更新你的 React 版本：

npm install react@^19.0.0 react-dom@^19.0.0

pnpm add react@^19.0.0 react-dom@^19.0.0

yarn add react@^19.0.0 react-dom@^19.0.0

bun add react@^19.0.0 react-dom@^19.0.0

注意：这些依赖项更新可以在切换 HeroUI 之前完成（不会破坏项目）。但是，HeroUI 包切换只能在所有组件代码迁移之后进行。

更新 HeroUI 包

重要：在迁移所有组件代码后执行此操作。删除 v2 软件包并安装 v3：

npm uninstall @heroui/react @heroui/theme
npm install @heroui/styles @heroui/react

pnpm remove @heroui/react @heroui/theme
pnpm add @heroui/styles @heroui/react

yarn remove @heroui/react @heroui/theme
yarn add @heroui/styles @heroui/react

bun remove @heroui/react @heroui/theme
bun add @heroui/styles @heroui/react

删除Framer Motion

v3 不再需要 Framer Motion：

npm uninstall framer-motion

pnpm remove framer-motion

yarn remove framer-motion

bun remove framer-motion

更新 Tailwind CSS

确保您使用的是 Tailwind CSS v4：

npm install tailwindcss@^4.0.0

pnpm add tailwindcss@^4.0.0

yarn add tailwindcss@^4.0.0

bun add tailwindcss@^4.0.0

第 2 步：更新主题配置

删除 Tailwind 插件配置

v2 配置：

// tailwind.config.js
const {heroui} = require("@heroui/react");

module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}",
  ],
  plugins: [heroui()],
  // ... other config
};

v3 配置：

删除heroui()来自 Tailwind 配置的插件。如果您仅将 Tailwind 用于 HeroUI 并且没有其他自定义，则可以删除tailwind.config.js完全。否则，保留该文件但删除 HeroUI 插件配置。

更新 CSS 导入

v2 CSS：

/* globals.css or main.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

v3 CSS：

/* globals.css or main.css */
@import "tailwindcss";
@import "@heroui/styles"; 

删除主题插件文件

如果您创建了一个hero.tsv2 文件，您可以将其删除：

rm hero.ts

第3步：删除HeroUIProvider

v3 不需要 Provider 组件。从应用程序根目录中删除它。

v2 代码：

// app.tsx or App.tsx
import {HeroUIProvider} from "@heroui/react";

function App() {
  return (
    <HeroUIProvider>
      <YourApplication />
    </HeroUIProvider>
  );
}

v3 代码：

// app.tsx or App.tsx
function App() {
  return <YourApplication />;
}

如果您使用 Provider 道具：

如果您使用 Provider 道具，例如navigate, useHref, locale, disableAnimation等等，您需要以不同的方式处理这些：

• 路由器集成：直接使用 React Router 或您的路由库
• 区域设置：使用 React Aria 的I18nProvider如果需要直接
• 动画：请参阅下面的动画更改部分

动画变化

v3 删除了 Framer Motion 依赖性并以不同方式处理动画：

• 基于 CSS 的动画：v3 使用原生 CSS 动画和过渡，而不是基于 JavaScript 的动画
• 更好的性能：CSS 动画提供更好的性能和更流畅的动画
• 无全局禁用：与 v2 的 Provider 不同disableAnimation道具，v3 中没有全局动画切换
• 每个组件控制：通过 CSS 或特定于组件的 props（如果可用）控制动画
• 自定义动画：使用标准 CSS@keyframes和自定义动画的过渡属性

第 4 步：更换拆下的挂钩

HeroUI v2 提供了组件挂钩（例如useSwitch, useInput, useCheckbox等）和实用程序挂钩，例如useDisclosure。 HeroUI v3 删除了大多数组件挂钩，转而使用复合组件，并替换了useDisclosure和useOverlayState.

查看综合Hooks 迁移指南为了：

• 组件挂钩移除并迁移到复合组件
• useDisclosure → useOverlayState迁移
• 迁移策略和示例

第 5 步：更新组件导入

所有组件现在都从单个包导入：

v2 导入：

// Individual packages (if used)
import {Button} from "@heroui/button";
import {Card} from "@heroui/card";

// Or from main package
import {Button, Card} from "@heroui/react";

v3 导入：

// All components from single package
import {Button, Card} from "@heroui/react";

TypeScript 注意事项

如果您使用 TypeScript，请注意 v3 中的类型更改：

// Import types alongside components
import {Button, type ButtonProps} from "@heroui/react";

// Compound component types are properly exported
import {Checkbox, type CheckboxProps} from "@heroui/react";

// Type names may have changed - check component documentation
type MyButtonProps = ButtonProps & {
  customProp?: string;
};

常见类型变化：

• 组件 prop 接口可能有不同的名称或属性
• 复合零部件有自己的类型导出
• 更新了 Ref 类型以匹配 React 19 模式

第6步：组件迁移

使用组件迁移参考表查找每个组件的迁移指南。根据组件的特定指南迁移组件。

要点：

• 根据需要查看各个组件迁移指南
• 迁移组件 API、props 和结构
• 更新复合组件模式（复选框、单选、开关、卡片、模态等）
• 更新组组件（ButtonGroup、CheckboxGroup、RadioGroup）
• 处理已移除组件（Code、Image、Navbar、Ripple、Snippet、Spacer、User）——替换为原生 HTML 或自定义实现
• 处理进行中/计划中的组件 - 替换为 HTML 元素，直到 v3 组件可用

第 7 步：更新自定义主题覆盖

如果您在 v2 中有自定义主题覆盖，则需要针对 v3 的基于 CSS 的主题系统更新它们。

v2 主题定制：

// tailwind.config.js
const {heroui} = require("@heroui/react");

module.exports = {
  plugins: [
    heroui({
      themes: {
        light: {
          colors: {
            primary: {
              // custom colors
            },
          },
        },
      },
    }),
  ],
};

v3 主题定制：

v3 使用 CSS 变量。在 CSS 中覆盖它们：

/* globals.css */
@import "tailwindcss";
@import "@heroui/styles";

:root {
  --color-primary: /* your color */;
  /* other CSS variables */
}

检查主题文档获取可用的 CSS 变量。

这是在继续样式迁移之前暂停并验证组件功能的好时机。

第8步：Hooks迁移

组件迁移完成后，确保所有钩子都已迁移：

1. 替换组件钩子：将 useSwitch、useInput、useCheckbox 等替换为复合组件用法
2. 迁移 useDisclosure：将 useDisclosure 替换为 useOverlayState 以管理浮层状态
3. 参考 Hooks 指南：参阅 Hooks 迁移指南 获取详细步骤与示例

第 9 步：样式迁移

挂钩迁移完成后，继续进行样式更改。这是一个单独的步骤，以确保在解决视觉更改之前验证组件功能。

样式迁移指南：

查看综合样式迁移指南为了：

• 实用程序类更改（text-tiny → text-xs, rounded-small → rounded-sm， ETC。）
• 颜色标记更新（bg-primary → bg-accent, bg-content1 → bg-surface， ETC。）
• 组件样式差异（大小、间距、边框半径）
• CSS 变量更改
• 视觉差异和对齐变化

主要样式变化：

• 实用程序类：自定义实用程序替换为标准 Tailwind 类
• 颜色标记：primary → accent, secondary删除,content1-4 → surface/overlay
• 编号比例：颜色比例如primary-50, primary-100已删除
• 边框半径：默认值已更改（v3 中更小）
• 组件样式：更新了默认大小、填充和间距

迁移清单：

• 审查样式迁移指南
• 更新实用程序类（text-tiny → text-xs， ETC。）
• 更新颜色标记（bg-primary → bg-accent， ETC。）
• 更新内容颜色（bg-content1 → bg-surface或者bg-overlay)
• 更新编号色阶（bg-primary-50 → bg-accent-soft)
• 检查组件样式更改（大小、间距、边框半径）
• 测试视觉外观并根据需要进行调整

第10步：测试

迁移后，彻底测试您的应用程序：

1. 视觉测试：检查所有组件正确渲染
2. 功能：测试所有交互和行为
3. 辅助功能：验证键盘导航和屏幕阅读器支持
4. 响应式设计：在不同的屏幕尺寸上进行测试
5. 性能：检查包大小和运行时性能