Rolling Text
hover 時字元上下滾動翻轉的文字動畫，支援逐字/逐詞、方向與受控模式。
載入預覽⋯
Playground
即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。
0.025
0.4
<RollingText />
安裝
npx shadcn@latest add https://webberui.com/r/rolling-text.json或在 components.json 設定 registries 後，改用 @webberui/rolling-text 安裝。
安裝依賴後，從 registry JSON（/r/rolling-text.json 的 files[0].content）複製 rolling-text.tsx 原始碼到你的 components/ui/ 目錄：
npm install motion clsx tailwind-merge使用
import { RollingText } from "@/components/ui/rolling-text";
<RollingText text="HOVER TO ROLL" className="text-4xl font-bold" />受控模式（父層觸發）
放進連結或按鈕時，把 active 綁到父層的 hover/focus，鍵盤使用者也能觸發滾動：
const [active, setActive] = React.useState(false);
<a
href="/products"
onMouseEnter={() => setActive(true)}
onMouseLeave={() => setActive(false)}
onFocus={() => setActive(true)}
onBlur={() => setActive(false)}
>
<RollingText text="Products" active={active} />
</a>Props
| Prop | 型別 | 預設值 | 說明 |
|---|---|---|---|
text | string | — | 要滾動翻轉的文字 |
by | "char" | "word" | "char" | 拆分單位：逐字或逐詞 |
direction | "up" | "down" | "up" | 滾動方向：原字捲出、複本補進的方向 |
stagger | number | 0.025 | 相鄰單位的延遲間隔（秒），形成由左至右的波浪 |
duration | number | 0.4 | 單一單位滾動時長（秒） |
active | boolean | — | 受控模式：由外部決定翻轉狀態；未提供時元件自身以 hover 觸發 |
as | React.ElementType | "span" | 渲染的元素標籤 |
className | string | — | 附加到根元素的 class |
細節
- 每個單位由兩層文字組成：原字層與複本層在
clip-path: inset(0)的裁切盒內交換位置，字面外的部分不可見 - 使用
clip-path而非overflow: hidden裁切：後者會把 inline-block 的基線改成盒底緣，與相鄰行內文字產生垂直錯位 - 以字素（grapheme）切割，emoji、旗幟、組合字不會被拆壞；空白字元不參與滾動，行寬與斷行保持穩定
- 裁切盒高度等於行高，行高過小（如
leading-none）時字母下伸部可能被裁到，建議 line-height 至少 1.2
可及性
- 使用者系統開啟「減少動態效果」時，直接渲染靜態文字
- 完整文字以
sr-only提供給輔助科技，滾動層整體aria-hidden，朗讀時是完整句子而非逐字 - 非受控模式只回應滑鼠 hover；要讓鍵盤 focus 也觸發，改用受控模式把
active綁到父層可聚焦元素的 focus/blur