LightRays

light-rays

体积光束放射 WebGL 背景 · 八向原点 + 双层正弦扰动/扩散衰减/脉动/噪点/扭曲 + 鼠标方向跟随(ogl·token 着色·reduced-motion 静态渐变兜底)

用法

基础用法

默认 top-center 自顶部中央向下放射，组件自带 absolute inset-0 z-0。

LightRays

tsx

<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.13 0.02 265)" }}>
  <LightRays raysOrigin="top-center" className="opacity-90" />
  <div className="relative z-10 flex h-full items-center justify-center text-sm font-medium text-white/80">
    LightRays
  </div>
</div>

左侧射入 · 暖色

raysOrigin 改方向，raysColor 传暖色，lightSpread 调聚拢。

tsx

<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.13 0.02 265)" }}>
  <LightRays
    raysOrigin="left"
    raysColor="oklch(0.78 0.16 70)"
    lightSpread={0.8}
    className="opacity-90"
  />
</div>

脉动 + 噪点质感

pulsating 整体亮度呼吸，noiseAmount 叠加细微噪点。

tsx

<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.13 0.02 265)" }}>
  <LightRays
    raysOrigin="top-center"
    pulsating
    noiseAmount={0.25}
    raysSpeed={1.4}
    className="opacity-90"
  />
</div>

底部上射 · 聚拢窄束

bottom-center + 小 lightSpread 聚成窄束，children 叠标题（注：组件根 aria-hidden）。

tsx

<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.13 0.02 265)" }}>
  <LightRays
    raysOrigin="bottom-center"
    lightSpread={0.4}
    rayLength={2.6}
    distortion={0.3}
    followMouse={false}
    className="opacity-90"
  >
    <div className="flex h-full flex-col items-center justify-center gap-1">
      <p className="text-lg font-semibold text-white">瑚琏组件库</p>
      <p className="text-xs text-white/60">体积光束 · WebGL · token 着色</p>
    </div>
  </LightRays>
</div>

何时用

需要自某个原点（八向可选）放射的体积光束做 hero 背景、且可跟随鼠标偏转时用。要单根体积光柱用 LightPillar；要坠落光束用 Lightfall；要随机闪烁电弧用 Lightning。

导入

import { LightRays } from "@hulianui/ui"

Props

名称	类型	默认	说明
raysOrigin	`"top-center" \| "top-left" \| "top-right" \| "left" \| "right" \| "bottom-left" \| "bottom-center" \| "bottom-right"`	`"top-center"`	光束发射原点，决定锚点与传播方向（四角 / 四边中点）
raysColor	`string`	`var(--color-chart-1)`	光束颜色，任意 CSS 颜色，离屏 canvas 解析为 RGB
raysSpeed	`number`	`1`	闪烁/律动速度倍率，0 近乎静止（仍渲染一帧）
lightSpread	`number`	`1`	光束扩散角度，越大越散、越小越聚拢，建议 0.3–3
rayLength	`number`	`2`	光束长度（相对视口宽倍数）
pulsating	`boolean`	`false`	整体亮度随时间正弦呼吸
fadeDistance	`number`	`1`	沿程渐隐距离（相对视口宽倍数），越小越快淡出
saturation	`number`	`1`	饱和度，<1 去色趋灰，0=纯灰阶
followMouse	`boolean`	`true`	光束方向跟随鼠标（需 mouseInfluence>0 才有可见偏转）
mouseInfluence	`number`	`0.1`	鼠标对方向的影响权重(0–1)，0=不偏转
noiseAmount	`number`	`0`	颗粒噪声强度(0–1)
distortion	`number`	`0`	角度扭曲强度，让光束摇曳而非笔直，建议 0–1
className	`string`	—	透传根容器（自带 pointer-events-none absolute inset-0 z-0）
style	`CSSProperties`	—	透传根容器内联样式

Slots

插槽	类型	说明
children	`ReactNode`	叠在光束层之上的内容，WebGL 与降级两路径均渲染
fallback	`ReactNode`	reduced-motion / 无 WebGL 时叠在静态渐变上的兜底内容

禁忌 / 坑

组件自带 pointer-events-none absolute inset-0 z-0，叠加内容须 relative z-10 才在它之上。
followMouse 默认 true，但需 mouseInfluence>0（默认 0.1）才有可见偏转；想完全静止设 mouseInfluence={0}。
ogl/WebGL 仅客户端；SSR / 无 WebGL 出静态渐变兜底，reduced-motion 下降级。children 两路径都渲染以保 DOM 一致。
raysColor 传 CSS 变量须用 --color- 前缀 token，见 [[hulian-token-color-var-needs-color-prefix]]。
全屏背景层在 opaque 背景的非层叠上下文父级里可能被父背景盖住，见 [[webgl-canvas-rendered-but-invisible-negative-zindex-covered]]。

Playground

光束原点速度倍率扩散角度光束长度脉动跟随鼠标

LightRays

<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.13 0.02 265)" }}>
  <LightRays
    raysOrigin="top-center"
    raysSpeed={1}
    lightSpread={1}
    rayLength={2}
    pulsating={false}
    followMouse={true}
    className="opacity-90"
  />
</div>

用法

基础用法

默认 top-center 自顶部中央向下放射，组件自带 absolute inset-0 z-0。

LightRays

tsx

<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.13 0.02 265)" }}>
  <LightRays raysOrigin="top-center" className="opacity-90" />
  <div className="relative z-10 flex h-full items-center justify-center text-sm font-medium text-white/80">
    LightRays
  </div>
</div>

左侧射入 · 暖色

raysOrigin 改方向，raysColor 传暖色，lightSpread 调聚拢。

tsx

<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.13 0.02 265)" }}>
  <LightRays
    raysOrigin="left"
    raysColor="oklch(0.78 0.16 70)"
    lightSpread={0.8}
    className="opacity-90"
  />
</div>

脉动 + 噪点质感

pulsating 整体亮度呼吸，noiseAmount 叠加细微噪点。

tsx

<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.13 0.02 265)" }}>
  <LightRays
    raysOrigin="top-center"
    pulsating
    noiseAmount={0.25}
    raysSpeed={1.4}
    className="opacity-90"
  />
</div>

底部上射 · 聚拢窄束

bottom-center + 小 lightSpread 聚成窄束，children 叠标题（注：组件根 aria-hidden）。

tsx

<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.13 0.02 265)" }}>
  <LightRays
    raysOrigin="bottom-center"
    lightSpread={0.4}
    rayLength={2.6}
    distortion={0.3}
    followMouse={false}
    className="opacity-90"
  >
    <div className="flex h-full flex-col items-center justify-center gap-1">
      <p className="text-lg font-semibold text-white">瑚琏组件库</p>
      <p className="text-xs text-white/60">体积光束 · WebGL · token 着色</p>
    </div>
  </LightRays>
</div>

Props

名称	类型	默认	说明
raysOrigin	`"top-center" \| "top-left" \| "top-right" \| "left" \| "right" \| "bottom-left" \| "bottom-center" \| "bottom-right"`	`"top-center"`	光束发射原点，决定锚点与传播方向（四角 / 四边中点）
raysColor	`string`	`var(--color-chart-1)`	光束颜色，任意 CSS 颜色，离屏 canvas 解析为 RGB
raysSpeed	`number`	`1`	闪烁/律动速度倍率，0 近乎静止（仍渲染一帧）
lightSpread	`number`	`1`	光束扩散角度，越大越散、越小越聚拢，建议 0.3–3
rayLength	`number`	`2`	光束长度（相对视口宽倍数）
pulsating	`boolean`	`false`	整体亮度随时间正弦呼吸
fadeDistance	`number`	`1`	沿程渐隐距离（相对视口宽倍数），越小越快淡出
saturation	`number`	`1`	饱和度，<1 去色趋灰，0=纯灰阶
followMouse	`boolean`	`true`	光束方向跟随鼠标（需 mouseInfluence>0 才有可见偏转）
mouseInfluence	`number`	`0.1`	鼠标对方向的影响权重(0–1)，0=不偏转
noiseAmount	`number`	`0`	颗粒噪声强度(0–1)
distortion	`number`	`0`	角度扭曲强度，让光束摇曳而非笔直，建议 0–1
className	`string`	—	透传根容器（自带 pointer-events-none absolute inset-0 z-0）
style	`CSSProperties`	—	透传根容器内联样式

插槽

类型

说明

children

ReactNode

叠在光束层之上的内容，WebGL 与降级两路径均渲染

fallback

ReactNode

reduced-motion / 无 WebGL 时叠在静态渐变上的兜底内容

禁忌 / 坑

组件自带 pointer-events-none absolute inset-0 z-0，叠加内容须 relative z-10 才在它之上。

followMouse 默认 true，但需 mouseInfluence>0（默认 0.1）才有可见偏转；想完全静止设 mouseInfluence={0}。

ogl/WebGL 仅客户端；SSR / 无 WebGL 出静态渐变兜底，reduced-motion 下降级。children 两路径都渲染以保 DOM 一致。

raysColor 传 CSS 变量须用 --color- 前缀 token，见 [[hulian-token-color-var-needs-color-prefix]]。

全屏背景层在 opaque 背景的非层叠上下文父级里可能被父背景盖住，见 [[webgl-canvas-rendered-but-invisible-negative-zindex-covered]]。

Playground

光束原点速度倍率扩散角度光束长度脉动跟随鼠标

LightRays

<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.13 0.02 265)" }}>
  <LightRays
    raysOrigin="top-center"
    raysSpeed={1}
    lightSpread={1}
    rayLength={2}
    pulsating={false}
    followMouse={true}
    className="opacity-90"
  />
</div>

LightRays

用法

基础用法

左侧射入 · 暖色

脉动 + 噪点质感

底部上射 · 聚拢窄束

何时用

导入

Props

Slots

禁忌 / 坑

相关

Playground

LightRays

用法

基础用法

左侧射入 · 暖色

脉动 + 噪点质感

底部上射 · 聚拢窄束

何时用

导入

Props

Slots

禁忌 / 坑

相关

Playground