GhostCursor

ghost-cursor

跟随指针的幽灵烟雾拖尾 · fbm 噪声烟团 + 环形帧缓冲历史尾迹 + 惯性滑行渐隐（ogl WebGL·去 three.js·reduced-motion 降级）

用法

基础用法

GhostCursor 是 absolute inset-0 的装饰覆盖层，放进一个 relative + overflow-hidden 的深色容器即可。

在此区域内移动指针

tsx

<div
  className="relative h-64 overflow-hidden rounded-xl"
  style={{ background: "oklch(0.14 0.02 285)" }}
>
  <GhostCursor />
</div>

自定义颜色与长拖尾

color 改主色调，trailLength 拉长尾迹，inertia 越大停手后越飘。

拖尾更长更飘

tsx

<GhostCursor
  color="oklch(0.72 0.2 50)"
  trailLength={48}
  inertia={0.78}
/>

聚拢小烟团

scale 越大烟团越聚拢，brightness 提亮，关闭颗粒更干净。

烟团更聚拢

tsx

<GhostCursor
  scale={1.6}
  grainIntensity={0}
  brightness={1.5}
  trailLength={20}
/>

弥散柔光

scale 越小烟团越弥散，配青绿主色得柔和氛围光。

弥散柔光

tsx

<GhostCursor
  color="oklch(0.78 0.16 175)"
  scale={0.7}
  inertia={0.6}
  brightness={1.3}
/>

何时用

作为覆盖整块区域的 WebGL 烟雾拖尾层，让指针在 hero/卡片/落地页上拖出发光烟团。要甩出具体图片做拖尾用 ImageTrail；本组件是抽象烟雾光效，更适合纯氛围装饰。它是 absolute inset-0 覆盖层，父容器须 relative + 深色底才出效果。

导入

import { GhostCursor } from "@hulianui/ui"

Props

名称	类型	默认	说明
trailLength	`number`	`32`	拖尾保留的历史帧数，越大尾迹越长，片元开销线性增长，建议 16–64
inertia	`number`	`0.5`	惯性系数 0–1，越接近 1 越「飘」（拖远），越接近 0 越跟手
grainIntensity	`number`	`0.05`	胶片颗粒强度 0–0.3，叠加噪点；0 = 关闭
brightness	`number`	`1.2`	整体亮度增益，补偿去掉 Bloom 后的亮度损失，建议 0.8–2.0
color	`string`	`var(--color-chart-1)`	烟雾主色，吃明暗主题；任意 CSS 颜色串均可
scale	`number`	`1`	噪声活动半径系数 >0，越大烟团越弥散，越小越聚拢
mixBlendMode	`CSSProperties["mixBlendMode"]`	`"screen"`	canvas 混合模式，深色底用 screen 叠加发光；浅色底可改 multiply/normal
className	`string`	—	透传根容器（absolute inset-0）额外 className
style	`CSSProperties`	—	透传根容器内联样式（如 zIndex）

禁忌 / 坑

WebGL（ogl）组件，React StrictMode 双挂载下若 cleanup 调 loseContext 会永久毒化 canvas 复用导致空白崩溃，本组件内部应每次挂载新建 canvas 规避，见 [[webgl-canvas-loseContext-poisons-strictmode-remount]]。
父容器必须 relative + overflow-hidden + 深色底（默认 screen 混合模式在浅色底几乎不可见）。
SSR 下 WebGL 仅客户端可用，组件已带 reduced-motion 降级。

Playground

拖尾长度惯性系数 0-1亮度增益颗粒强度烟团尺度

在此区域内移动指针

<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.14 0.02 285)" }}>
  <GhostCursor
    trailLength={32}
    inertia={0.5}
    brightness={1.2}
    grainIntensity={0.05}
    scale={1}
  />
</div>

用法

基础用法

GhostCursor 是 absolute inset-0 的装饰覆盖层，放进一个 relative + overflow-hidden 的深色容器即可。

在此区域内移动指针

tsx

<div
  className="relative h-64 overflow-hidden rounded-xl"
  style={{ background: "oklch(0.14 0.02 285)" }}
>
  <GhostCursor />
</div>

自定义颜色与长拖尾

color 改主色调，trailLength 拉长尾迹，inertia 越大停手后越飘。

拖尾更长更飘

tsx

<GhostCursor
  color="oklch(0.72 0.2 50)"
  trailLength={48}
  inertia={0.78}
/>

聚拢小烟团

scale 越大烟团越聚拢，brightness 提亮，关闭颗粒更干净。

烟团更聚拢

tsx

<GhostCursor
  scale={1.6}
  grainIntensity={0}
  brightness={1.5}
  trailLength={20}
/>

弥散柔光

scale 越小烟团越弥散，配青绿主色得柔和氛围光。

弥散柔光

tsx

<GhostCursor
  color="oklch(0.78 0.16 175)"
  scale={0.7}
  inertia={0.6}
  brightness={1.3}
/>

何时用

Props

名称	类型	默认	说明
trailLength	`number`	`32`	拖尾保留的历史帧数，越大尾迹越长，片元开销线性增长，建议 16–64
inertia	`number`	`0.5`	惯性系数 0–1，越接近 1 越「飘」（拖远），越接近 0 越跟手
grainIntensity	`number`	`0.05`	胶片颗粒强度 0–0.3，叠加噪点；0 = 关闭
brightness	`number`	`1.2`	整体亮度增益，补偿去掉 Bloom 后的亮度损失，建议 0.8–2.0
color	`string`	`var(--color-chart-1)`	烟雾主色，吃明暗主题；任意 CSS 颜色串均可
scale	`number`	`1`	噪声活动半径系数 >0，越大烟团越弥散，越小越聚拢
mixBlendMode	`CSSProperties["mixBlendMode"]`	`"screen"`	canvas 混合模式，深色底用 screen 叠加发光；浅色底可改 multiply/normal
className	`string`	—	透传根容器（absolute inset-0）额外 className
style	`CSSProperties`	—	透传根容器内联样式（如 zIndex）

禁忌 / 坑

WebGL（ogl）组件，React StrictMode 双挂载下若 cleanup 调 loseContext 会永久毒化 canvas 复用导致空白崩溃，本组件内部应每次挂载新建 canvas 规避，见 [[webgl-canvas-loseContext-poisons-strictmode-remount]]。

父容器必须 relative + overflow-hidden + 深色底（默认 screen 混合模式在浅色底几乎不可见）。

SSR 下 WebGL 仅客户端可用，组件已带 reduced-motion 降级。

Playground

拖尾长度惯性系数 0-1亮度增益颗粒强度烟团尺度

在此区域内移动指针

<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.14 0.02 285)" }}>
  <GhostCursor
    trailLength={32}
    inertia={0.5}
    brightness={1.2}
    grainIntensity={0.05}
    scale={1}
  />
</div>

GhostCursor

用法

基础用法

自定义颜色与长拖尾

聚拢小烟团

弥散柔光

何时用

导入

Props

禁忌 / 坑

相关

Playground

GhostCursor

用法

基础用法

自定义颜色与长拖尾

聚拢小烟团

弥散柔光

何时用

导入

Props

禁忌 / 坑

相关

Playground