Kubai Icons React详解:3行代码让2800+悬停动态图标跑起来,SSR也能用

原创2026-11-13 20:56:271,363 阅读

Kubai Icons React详解:3行代码让2800+悬停动态图标跑起来,SSR也能用

Kubai Icons 是一套 2800+ 开源动画图标库,配套的 kubai-icons-react 包让图标以 React 组件形式运行:悬停时文件夹会打开、信封会拆封、日历会翻页。它的标记(markup)在服务端就能渲染,动画在浏览器挂载后才附加,因此 Next.js 的 SSR / Server Components 开箱即用,无需任何额外配置。

Kubai Icons React 动态图标库图标网格展示

一分钟上手:安装与 3 行调用

只需一条命令:

npm i kubai-icons-react

然后 3 行代码就能让图标跑起来(需要 React 18+):

import { Folder, CalendarCheck } from "kubai-icons-react";

<Folder />
<CalendarCheck size={32} color="#22C55E" variant="soft" badgeColor="semantic" />

就这么简单:

  • <Folder /> —— 默认 24px,颜色跟随文字(currentColor)
  • size={32} —— 任意尺寸
  • color —— 只需一个强调色,渐变、描边、高光全部由它通过 CSS 推导
  • variant="soft" —— 更浅的填充 + 更深的描边
  • badgeColor="semantic" —— 徽章自动按语义配色(加号绿色、删除红色、警告琥珀色)

💡 图标按名字导入(PascalCase),每个图标是独立的无副作用 ES 模块,打包器会自动 tree-shaking,只引入你用到的图标。

常用 Props 一览:从悬停到点击状态

Prop 默认值 说明
size 24 宽高(px)
color currentColor 强调色,整图由它推导
variant "color" "soft" 为柔和浅色风格
badgeColor 深灰 任意 CSS 颜色或 "semantic"
trigger "hover" "hover" / "parent" / "none"
hover 无 true 播放、false 复位,配合 trigger="none" 完全手动控制
active / defaultActive / onActiveChange 无 切换类图标(如 Bookmark)的开/关状态
title 无 无障碍名称;不传则图标为 aria-hidden

其余 className、style、事件处理器、ref 等 SVG 属性会透传到底层 <svg>。完整实现见 packages/react/src/create.js。

Kubai Icons 悬停动画演示:文件夹、信封、日历等图标依次动起来

整颗按钮悬停才播放:trigger="parent" 技巧

想让按钮整体被悬停(或键盘聚焦)时才触发动画,给按钮加 data-kubai-trigger,图标设置 trigger="parent":

<button data-kubai-trigger>
  <Folder size={18} trigger="parent" /> Open
</button>

这样鼠标落到按钮任何位置(包括文字)都会播放动画,交互体验更自然。

图标名来自后端?用 DynamicIcon 按需加载

图标名在运行时才确定(比如来自接口字段)时,用 DynamicIcon:

import { DynamicIcon } from "kubai-icons-react/dynamic";

export function ItemIcon({ name }: { name: string }) {
  return <DynamicIcon name={name} size={20} />;
}

类型声明见 packages/react/src/dynamic.d.ts。每个图标仍是独立 chunk,不会把整库打进你的 bundle。

SSR 也能用:Next.js 零配置

这是很多动态图标库做不到的点:

  • 标记在服务端渲染,首次绘制不等待任何脚本,SEO 爬虫和首屏都能拿到完整 SVG;
  • 动画在 hydration 之后才附加,服务端不会执行任何动效逻辑,见 create.js 中的注释与 create.js 的 useEffect 挂载逻辑;
  • Server Components 与 Client Components 都能直接用,无需 dynamic import 或额外包装;
  • 唯一例外是 DynamicIcon:它在服务端渲染空占位符,图标在浏览器端再加载。

性能进阶:Deep Import

在 dev server 下避免加载整个包索引,可以直接从单个图标模块导入:

import Folder from "kubai-icons-react/icons/folder";

图标源文件都放在 icons/ 目录(每个图标一个模块),格式说明见 docs/authoring.md。

Kubai Icons 动态图标库:React、Vue、Web、SVG 多端支持

不止 React:同一套图标的其他姿势

包 适用场景
kubai-icons-react React 18+ / Next.js,支持 SSR
kubai-icons-vue Vue 3 / Nuxt
kubai-icons 任意页面:无框架 API + <kubai-icon> Web Component
kubai-icons-static 独立 SVG 文件,供 <img>、设计工具、CDN 使用

没有构建工具?一行 <script type="module"> 从 CDN 引入 <kubai-icon> 元素即可(用法见 packages/core/README.md)。

常见问题(FAQ)

Q:商用可以免费用吗? A:可以。图标与四个包均为 MIT 许可,任意项目(含商业)自由使用、修改、再分发。许可详情见 LICENSING.md。

Q:为什么动画不打架、不掉帧? A:每个部件只有 rest / hover 两个关键帧,运行时(runtime)只在图标运动时才执行,静止时零开销。

Q:能换成深色风格吗? A:variant="soft" 即柔和风格;颜色由单一 color 值推导,改一个值即可整体换肤,无需改脚本。

小结

Kubai Icons 的 React 集成把“动态图标”做成了最朴素的事情:npm i 一行、<Folder /> 三行代码,SSR 零配置,2800+ 图标任你挑。如果你在找悬停动画图标 + React + SSR 的组合,它就是目前开箱体验最顺滑的方案之一。

登录后查看全文
kubai-icons