LiquidEther

liquid-ether

鼠标驱动的液态色域 WebGL 背景 · 域扭曲+metaball 翻涌 + 指针搅动/自动巡游(ogl·token·reduced-motion 降级)

用法

基础用法

放进 relative 容器即可，组件自带 absolute inset-0；默认自动巡游搅动液面，颜色吃 chart token 明暗自适应。

LiquidEther

tsx

<div className="relative h-64 overflow-hidden rounded-xl bg-neutral-950">
  <LiquidEther />
  <div className="relative z-10 flex h-full items-center justify-center text-white/85">
    LiquidEther
  </div>
</div>

自定义调色板 · 大团块

colors 接任意 CSS 颜色（hex / oklch / var token）；scale 越大色团越融合宏观，speed 控制翻涌速度。

tsx

<LiquidEther
  colors={[
    "var(--color-chart-3)",
    "oklch(0.72 0.22 30)",
    "var(--color-chart-1)",
  ]}
  scale={1.6}
  speed={0.7}
/>

静止待交互

autoDemo={false} 关掉自动巡游，画面静止等待真实指针；mouseForce 调大让搅动更跟手。

tsx

<LiquidEther autoDemo={false} mouseForce={1.5} />

壁纸级叠底

慢速 + 半透明（opacity）压低视觉重量，作为标题区背景叠在文字下方。

瑚琏组件库

液态色域 · 鼠标驱动

tsx

<div className="relative h-64 overflow-hidden rounded-xl bg-neutral-950">
  <LiquidEther speed={0.3} scale={1.2} opacity={0.7} />
  <div className="relative z-10 flex h-full flex-col items-center justify-center gap-2">
    <p className="text-lg font-semibold text-white">瑚琏组件库</p>
    <p className="text-xs text-white/60">液态色域 · 鼠标驱动</p>
  </div>
</div>

何时用

需要一层「跟手翻涌的液态色团」氛围背景（创意官网、产品 Hero、登录页）时用它，指针交互感最强。要规则点阵/网格选 DotPattern / GridPattern，要扫光聚焦选 Spotlight；本组件是有机色域流体，色彩重量大，常配 opacity 压低做壁纸底。

导入

import { LiquidEther } from "@hulianui/ui"

Props

名称	类型	默认	说明
colors	`string[]`	`["var(--color-chart-1)","var(--color-chart-2)","var(--color-chart-4)"]`	调色板，至少 1 色（少于 2 会自动复制两端）；任意 CSS 颜色串，随明暗主题切换
speed	`number`	`0.5`	流动速度因子；建议 0.2–1.5
scale	`number`	`1`	液态团块尺度；越小越细碎越多团，越大越融合。建议 0.6–2
mouseForce	`number`	`1`	指针扰动强度；0=无视指针纯漂流。建议 0–2
autoDemo	`boolean`	`true`	无人交互时虚拟光标自动巡游搅动；关闭则静止待真实指针
opacity	`number`	`1`	整体不透明度 0–1；叠内容上常用 0.6–0.85 降视觉重量
className	`string`	—	透传到根容器（canvas 包裹层或 reduced fallback）
style	`CSSProperties`	—	透传到根容器的内联样式

Slots

插槽	类型	说明
fallback	`ReactNode`	reduced-motion / 无 WebGL 时的静态替代内容；默认多点 chart token radial-gradient 静态液面

禁忌 / 坑

父容器须 relative + overflow-hidden，内容用 relative z-10 叠在上层；canvas 会满铺，叠加的文本建议加 pointer-events-none 避免吃掉指针搅动 [[webgl-canvas-rendered-but-invisible-negative-zindex-covered]]。
WebGL 客户端组件（"use client"）；SSR 阶段只渲染 fallback，不会有 canvas。
colors 传 var(--color-…) 时运行时经离屏 canvas 解析，必须带 `--color-` 前缀，裸 var(--primary) 解析不出 [[oklch-css-var-color-must-parse-via-offscreen-canvas]]。
headless 截图常拍到静止/空白帧（rAF 动画被饿死），真机或 Playwright 实测才能看到流动 [[recharts-headless-screenshot-blank-clippath-animation-starved]]。

Playground

流动速度团块尺度指针扰动自动演示不透明度

LiquidEther

<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.14 0.02 270)" }}>
  <LiquidEther
    speed={0.5}
    scale={1}
    mouseForce={1}
    autoDemo={true}
    opacity={1}
  />
</div>

用法

基础用法

放进 relative 容器即可，组件自带 absolute inset-0；默认自动巡游搅动液面，颜色吃 chart token 明暗自适应。

LiquidEther

tsx

<div className="relative h-64 overflow-hidden rounded-xl bg-neutral-950">
  <LiquidEther />
  <div className="relative z-10 flex h-full items-center justify-center text-white/85">
    LiquidEther
  </div>
</div>

自定义调色板 · 大团块

colors 接任意 CSS 颜色（hex / oklch / var token）；scale 越大色团越融合宏观，speed 控制翻涌速度。

tsx

<LiquidEther
  colors={[
    "var(--color-chart-3)",
    "oklch(0.72 0.22 30)",
    "var(--color-chart-1)",
  ]}
  scale={1.6}
  speed={0.7}
/>

静止待交互

autoDemo={false} 关掉自动巡游，画面静止等待真实指针；mouseForce 调大让搅动更跟手。

tsx

<LiquidEther autoDemo={false} mouseForce={1.5} />

壁纸级叠底

慢速 + 半透明（opacity）压低视觉重量，作为标题区背景叠在文字下方。

瑚琏组件库

液态色域 · 鼠标驱动

tsx

<div className="relative h-64 overflow-hidden rounded-xl bg-neutral-950">
  <LiquidEther speed={0.3} scale={1.2} opacity={0.7} />
  <div className="relative z-10 flex h-full flex-col items-center justify-center gap-2">
    <p className="text-lg font-semibold text-white">瑚琏组件库</p>
    <p className="text-xs text-white/60">液态色域 · 鼠标驱动</p>
  </div>
</div>

何时用

Props

名称	类型	默认	说明
colors	`string[]`	`["var(--color-chart-1)","var(--color-chart-2)","var(--color-chart-4)"]`	调色板，至少 1 色（少于 2 会自动复制两端）；任意 CSS 颜色串，随明暗主题切换
speed	`number`	`0.5`	流动速度因子；建议 0.2–1.5
scale	`number`	`1`	液态团块尺度；越小越细碎越多团，越大越融合。建议 0.6–2
mouseForce	`number`	`1`	指针扰动强度；0=无视指针纯漂流。建议 0–2
autoDemo	`boolean`	`true`	无人交互时虚拟光标自动巡游搅动；关闭则静止待真实指针
opacity	`number`	`1`	整体不透明度 0–1；叠内容上常用 0.6–0.85 降视觉重量
className	`string`	—	透传到根容器（canvas 包裹层或 reduced fallback）
style	`CSSProperties`	—	透传到根容器的内联样式

插槽

类型

说明

fallback

ReactNode

reduced-motion / 无 WebGL 时的静态替代内容；默认多点 chart token radial-gradient 静态液面

禁忌 / 坑

父容器须 relative + overflow-hidden，内容用 relative z-10 叠在上层；canvas 会满铺，叠加的文本建议加 pointer-events-none 避免吃掉指针搅动 [[webgl-canvas-rendered-but-invisible-negative-zindex-covered]]。

WebGL 客户端组件（"use client"）；SSR 阶段只渲染 fallback，不会有 canvas。

colors 传 var(--color-…) 时运行时经离屏 canvas 解析，必须带 `--color-` 前缀，裸 var(--primary) 解析不出 [[oklch-css-var-color-must-parse-via-offscreen-canvas]]。

headless 截图常拍到静止/空白帧（rAF 动画被饿死），真机或 Playwright 实测才能看到流动 [[recharts-headless-screenshot-blank-clippath-animation-starved]]。

<div className="relative h-64 overflow-hidden rounded-xl" style={{ background: "oklch(0.14 0.02 270)" }}> <LiquidEther speed={0.5} scale={1} mouseForce={1} autoDemo={true} opacity={1} /> </div>

LiquidEther

用法

基础用法

自定义调色板 · 大团块

静止待交互

壁纸级叠底

何时用

导入

Props

Slots

禁忌 / 坑

相关

Playground

LiquidEther

用法

基础用法

自定义调色板 · 大团块

静止待交互

壁纸级叠底

何时用

导入

Props

Slots

禁忌 / 坑

相关

Playground