Kubai Icons React详解:3行代码让2800+悬停动态图标跑起来,SSR也能用
Kubai Icons React详解:3行代码让2800+悬停动态图标跑起来,SSR也能用
Kubai Icons 是一套 2800+ 开源动画图标库,配套的 kubai-icons-react 包让图标以 React 组件形式运行:悬停时文件夹会打开、信封会拆封、日历会翻页。它的标记(markup)在服务端就能渲染,动画在浏览器挂载后才附加,因此 Next.js 的 SSR / Server Components 开箱即用,无需任何额外配置。
一分钟上手:安装与 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。
整颗按钮悬停才播放: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。
不止 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 的组合,它就是目前开箱体验最顺滑的方案之一。