吸頂圖文對照 Sticky Reveal｜免費 React 元件

吸頂圖文對照揭示：左側文字隨捲動流動，右側視覺吸附固定並交叉切換。

把這個效果裝進你的專案

在專案資料夾執行指令，CLI 會加入原始碼與依賴套件，再依下方使用範例引用元件。

npx webberui@latest add sticky-reveal

Sticky Reveal 是用 React、Tailwind CSS 與 Motion 做的捲動吸頂圖文對照（sticky scroll）區塊：文字欄照常捲動，視覺框以 CSS position: sticky 固定，再由 IntersectionObserver 判斷目前段落，切換對應的圖片。

Playground

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

視覺區位置mediaSide

吸頂偏移（px）stickyTop

顯示段落進度圓點showProgress

每段文字高度stepClassName

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

編輯中的呼叫預設屬性

<StickyReveal/>

    </div>
  );
}

完整範例包含預覽的排版與資料。先安裝元件，再把範例檔貼入你的專案。

適用情境

SaaS 產品頁逐步介紹功能，每段文字對應一張產品截圖
新手導覽或「運作方式」區塊，依步驟切換示意圖
案例研究、年度回顧等長文，讓圖表跟著段落換
硬體或 App 介紹頁，依序展示不同畫面或角度
不適合：需要依捲動進度逐格播放的連續動畫，改用 Image Sequence Scrub

安裝

npx webberui@latest add https://webberui.com/r/sticky-reveal.json

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

使用

以 StickyRevealItem 宣告每一段對照，media 放右側吸頂視覺、children 放左側文字：

import { StickyReveal, StickyRevealItem } from "@/components/ui/sticky-reveal";

<StickyReveal>
  <StickyRevealItem media={<img src="/design.jpg" alt="設計" className="h-full w-full object-cover" />}>
    <h3 className="text-2xl font-semibold">設計</h3>
    <p className="mt-2 text-neutral-600">從語意化 token 出發，全站節奏一致。</p>
  </StickyRevealItem>

  <StickyRevealItem media={<img src="/ship.jpg" alt="發佈" className="h-full w-full object-cover" />}>
    <h3 className="text-2xl font-semibold">發佈</h3>
    <p className="mt-2 text-neutral-600">一鍵安裝，內建 reduced-motion。</p>
  </StickyRevealItem>
</StickyReveal>

若內容位於巢狀捲動容器中，將該容器 ref 透過 container 傳入（頁面級捲動則可省略）：

const scrollerRef = React.useRef<HTMLDivElement>(null);

<div ref={scrollerRef} className="h-[80vh] overflow-y-auto">
  <StickyReveal container={scrollerRef} stickyTop={16}>
    {/* ...StickyRevealItem */}
  </StickyReveal>
</div>

範例

左圖右文、橫式視覺框

mediaSide="left" 把視覺移到左側；mediaClassName 覆寫預設的 3:4 直式比例，stepClassName 縮短每段的捲動距離。

<StickyReveal
  mediaSide="left"
  mediaClassName="aspect-video"
  stepClassName="min-h-[50vh]"
  stickyTop={96}
>
  <StickyRevealItem media={<img src="/dashboard.png" alt="營運儀表板" className="h-full w-full object-cover" />}>
    <h3 className="text-xl font-semibold">即時儀表板</h3>
    <p className="mt-2 text-neutral-600">訂單、營收與庫存集中在同一頁。</p>
  </StickyRevealItem>
  <StickyRevealItem media={<img src="/reports.png" alt="報表匯出" className="h-full w-full object-cover" />}>
    <h3 className="text-xl font-semibold">排程報表</h3>
    <p className="mt-2 text-neutral-600">每週一早上自動寄出上週數據。</p>
  </StickyRevealItem>
</StickyReveal>

頁面有固定導覽列時，把 stickyTop 設成導覽列高度，視覺框才不會被蓋住。

受控模式：同步外部步驟標籤

傳入 activeIndex 後由你掌控目前段落；捲動時仍會透過 onActiveChange 回報，記得把值寫回 state。

const steps = ["連結帳號", "匯入資料", "邀請團隊"];
const [step, setStep] = React.useState(0);

<p className="text-sm text-neutral-500">步驟：{steps[step]}</p>
<StickyReveal activeIndex={step} onActiveChange={setStep} showProgress={false}>
  {/* ...StickyRevealItem */}
</StickyReveal>

用 useStickyReveal 做自訂進度

useStickyReveal() 在 StickyRevealItem 的內容裡可以讀到 active 與 total，適合做「02 / 04」這類段落編號。

"use client";

import { useStickyReveal } from "@/components/ui/sticky-reveal";

function StepCounter() {
  const { active, total } = useStickyReveal();
  return (
    <span className="font-mono text-xs text-neutral-500">
      {String(active + 1).padStart(2, "0")} / {String(total).padStart(2, "0")}
    </span>
  );
}

Props

StickyReveal

Prop	型別	預設值	說明
`children`	`ReactNode`	—	放入一組 `StickyRevealItem`
`mediaSide`	`"left" \| "right"`	`"right"`	視覺區位置（左文右圖或左圖右文）
`stickyTop`	`number`	`24`	吸頂視覺框距容器頂端的偏移（px）
`activeIndex`	`number`	—	受控模式：由外部指定作用段落索引
`onActiveChange`	`(index: number) => void`	—	作用段落改變時觸發
`container`	`RefObject<HTMLElement \| null>`	—	巢狀捲動容器 ref；省略則以視窗為準
`showProgress`	`boolean`	`true`	顯示可點擊的段落進度圓點
`stepClassName`	`string`	`"min-h-[70vh]"`	每段文字容器的 class（撐開捲動距離）
`mediaClassName`	`string`	—	吸頂視覺框的 class（覆寫比例、圓角等）
`className`	`string`	—	根容器的 class

StickyRevealItem

Prop	型別	預設值	說明
`media`	`ReactNode`	—	對照顯示的視覺內容（圖片或圖形）
`children`	`ReactNode`	—	隨捲動流動的文字內容
`className`	`string`	—	附加到該段文字容器的 class