Animated Beam

在任意兩個節點之間繪製一條會流動的光束，路徑隨容器尺寸自動重算，最適合畫整合示意圖、資料管線與架構圖。

載入預覽⋯

Playground

即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。

曲率curvature

流動時長（秒）duration

反向流動reverse

線寬（px）pathWidth

漸層起點色gradientStartColor

漸層終點色gradientStopColor

<AnimatedBeam />

安裝

npx shadcn@latest add https://webberui.com/r/animated-beam.json

或在 components.json 設定 registries 後，改用 @webberui/animated-beam 安裝。

安裝依賴後，從 registry JSON（/r/animated-beam.json 的 files[0].content）複製 animated-beam.tsx 原始碼到你的 components/ui/ 目錄：

npm install motion clsx tailwind-merge

使用

光束是一個絕對定位的疊層，透過三個 ref 量測座標：containerRef 是量測原點，fromRef / toRef 是兩端節點。把節點與光束都放進同一個 relative 容器即可。

"use client";

import * as React from "react";
import { AnimatedBeam } from "@/components/ui/animated-beam";

export function Diagram() {
  const containerRef = React.useRef<HTMLDivElement>(null);
  const fromRef = React.useRef<HTMLDivElement>(null);
  const toRef = React.useRef<HTMLDivElement>(null);

  return (
    <div ref={containerRef} className="relative flex justify-between p-10">
      <div ref={fromRef} className="size-11 rounded-full bg-white" />
      <div ref={toRef} className="size-11 rounded-full bg-white" />
      <AnimatedBeam
        containerRef={containerRef}
        fromRef={fromRef}
        toRef={toRef}
      />
    </div>
  );
}

節點需要有實際尺寸與定位；光束以 -z-10 疊在節點之下，請確保容器帶 relative。多條光束用不同的 delay 錯開流動時序，用 curvature 讓匯聚到同一樞紐的線條散開。

Props

Prop	型別	預設值	說明
`containerRef`	`RefObject<HTMLElement \| null>`	—	量測座標用的外層容器
`fromRef`	`RefObject<HTMLElement \| null>`	—	光束起點節點
`toRef`	`RefObject<HTMLElement \| null>`	—	光束終點節點
`curvature`	`number`	`0`	曲率（px）：正值上拱、負值下沉
`reverse`	`boolean`	`false`	反向流動（終點朝起點）
`duration`	`number`	`3`	單次流動時長（秒）
`delay`	`number`	`0`	進場前延遲（秒）
`pathColor`	`string`	`"currentColor"`	靜態底線顏色
`pathWidth`	`number`	`2`	線寬（px）
`pathOpacity`	`number`	`0.15`	底線透明度
`gradientStartColor`	`string`	`"#818cf8"`	流動漸層起點色
`gradientStopColor`	`string`	`"#22d3ee"`	流動漸層終點色
`startXOffset`	`number`	`0`	起點 X 微調（px）
`startYOffset`	`number`	`0`	起點 Y 微調（px）
`endXOffset`	`number`	`0`	終點 X 微調（px）
`endYOffset`	`number`	`0`	終點 Y 微調（px）

可及性

使用者系統開啟「減少動態效果」時，只保留靜態底線、不播放流動亮點
光束層帶 aria-hidden，純裝飾不干擾輔助科技
路徑透過 ResizeObserver 監聽容器尺寸變化，RWD 下自動重算，離開時清理

Playground

安裝

使用

Props

可及性

On this page