MetaBalls
meta-balls让一组黏液球游走，靠近时融合、离开时分开
用法
基础用法
深色容器内铺满 absolute inset-0，一组黏液球游走并随指针融合。
tsx
<div className="relative h-64 overflow-hidden rounded-xl"
style={{ background: "oklch(0.14 0.02 255)" }}>
<MetaBalls className="absolute inset-0" />
</div>密集抱团
增多 ballCount、收紧 clumpFactor，让小球更密更聚拢。
tsx
<MetaBalls
className="absolute inset-0"
ballCount={28}
clumpFactor={0.7}
speed={0.5}
/>自定义配色
color 与 cursorBallColor 喂带 --color- 前缀的 chart token 做混调。
tsx
<MetaBalls
className="absolute inset-0"
color="var(--color-chart-3)"
cursorBallColor="var(--color-chart-5)"
animationSize={40}
/>关闭鼠标交互
enableMouseInteraction=false 时光标球自动做椭圆巡游。
tsx
<MetaBalls
className="absolute inset-0"
enableMouseInteraction={false}
speed={0.25}
/>何时用
需要一块「有机液态」的发光装饰背景（hero、卡片底、加载页），球体会融合分裂、跟随鼠标。要的是边缘擦亮/折射光感选 ShapeBlur、Lens；要的是规整环绕的图标轨道选 OrbitingCircles；MetaBalls 是其中最「流体黏连」的一档，放在深色底上发光最佳。
导入
ts
import { MetaBalls } from "@hulianui/ui"Props
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| color | string | "var(--color-chart-1)" | 主体小球聚合时的填充色。喂 token 必须带 --color- 前缀 |
| cursorBallColor | string | "var(--color-chart-4)" | 光标球颜色，与 color 在交界处混合 |
| speed | number | 0.3 | 公转速度倍率，越大游走越快 |
| enableMouseInteraction | boolean | true | 启用鼠标交互；关闭后光标球自动椭圆巡游 |
| hoverSmoothness | number | 0.05 | 光标球插值平滑系数（0-1），越小越拖尾、越大越跟手 |
| animationSize | number | 30 | 观察尺度，越大视野越广、小球越小越散 |
| ballCount | number | 15 | 主体小球数量（1-50，超出夹取到 50） |
| clumpFactor | number | 1 | 聚拢因子，越大轨道越外扩松散，越小越抱团 |
| cursorBallSize | number | 3 | 光标球半径（着色器单位） |
| enableTransparency | boolean | true | 透明背景；false 时填黑底 |
| className | string | - | 透传到 canvas / fallback 容器 |
Slots
| 插槽 | 类型 | 说明 |
|---|---|---|
| fallback | ReactNode | reduced-motion / 无 WebGL 时的自定义静态备用内容 |
禁忌 / 坑
- 喂 token 色给
color/cursorBallColor必须带--color-前缀（var(--color-chart-1)）：本 Tailwind v4 体系下裸var(--primary)不是已定义的变量，组件会回中性灰兜底色（不是你配的色，也不是黑）。见 [[hulian-token-color-var-needs-color-prefix]]。 - 颜色只在挂载时解析一次并写进 shader uniform。运行时切主题（
[data-theme]）不会重算——需要跟随主题就给组件一个随主题变的key强制重挂。 - WebGL/ogl 组件，仅客户端渲染；放在 RSC 页面里注意它是
"use client"。StrictMode 双挂载下 canvas context 复用可能毒化，参考 [[webgl-canvas-loseContext-poisons-strictmode-remount]]。 - 父容器需
relative+overflow-hidden，组件用absolute inset-0铺满；底色建议深色才看得清发光黏球。
相关
BorderBeam · ShineBorder · GlareHover · Lens · AnimatedBeam · OrbitingCircles
Playground
<div className="relative h-64 overflow-hidden rounded-xl"
style={{ background: "oklch(0.14 0.02 255)" }}>
<MetaBalls
className="absolute inset-0"
speed={0.3}
ballCount={15}
animationSize={30}
clumpFactor={1}
enableMouseInteraction={true}
/>
</div>