漸進模糊遮罩 Progressive Blur｜免費 React 元件

捲動內容邊緣的漸進模糊遮罩，越靠邊越模糊，讓內容平滑淡入淡出。

疊層 backdrop-filter 遮罩：把多個模糊層各切成一段窗口、逐層加倍並往邊緣位移，累積出「越靠邊越模糊」的漸進效果。把它丟進任何 relative 容器的邊緣即可。

把這個效果裝進你的專案

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

npx webberui@latest add progressive-blur

Progressive Blur 是用 React 與 Tailwind CSS 做的漸進模糊（progressive blur）遮罩元件，效果完全由 CSS backdrop-filter 與 mask-image 疊層產生，不需要動畫函式庫，也不用 canvas。常用在捲動清單、跑馬燈或圖片牆的邊緣，讓內容在離開可視區前逐漸糊掉。

Playground

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

貼齊邊side

遮罩厚度 (px)size

疊層數layers

起始模糊半徑 (px)blur

0.5

import * as React from "react";

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

編輯中的呼叫預設屬性

<ProgressiveBlur/>

    </div>
  );
}

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

適用情境

長清單或聊天訊息區的上下緣，提示使用者還有內容可以捲動
橫向捲動的卡片列、客戶 logo 跑馬燈左右兩端的淡出
固定式頂部導覽列底下，讓捲過去的內容在導覽列下方糊化
圖片牆或作品集底部，搭配「載入更多」按鈕收尾
不適合：想讓整段內容隨捲動逐漸清晰，請改用 Blur Reveal Text 這類進場元件

安裝

npx webberui@latest add https://webberui.com/r/progressive-blur.json

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

使用

把 ProgressiveBlur 放進要遮罩的 relative 容器裡，指定貼齊的邊即可。它是 pointer-events-none 的純視覺覆蓋層，不會擋住底下的捲動或點擊。

import { ProgressiveBlur } from "@/components/ui/progressive-blur";

<div className="relative h-80 overflow-auto">
  {/* 你的捲動內容 */}
  <ProgressiveBlur side="top" size={80} />
  <ProgressiveBlur side="bottom" size={80} />
</div>

side 可為 "top"、"bottom"、"left"、"right"；同一容器可同時放多個邊。

範例

橫向卡片列的左右淡出

把 side 設成 "left" 與 "right"，此時 size 控制的是寬度。

import { ProgressiveBlur } from "@/components/ui/progressive-blur";

<div className="relative">
  <div className="flex gap-4 overflow-x-auto px-6 py-4">
    {["方案比較", "使用者回饋", "整合清單", "更新日誌", "安全性說明"].map((label) => (
      <div key={label} className="w-56 shrink-0 rounded-xl border p-4 text-sm">
        {label}
      </div>
    ))}
  </div>
  <ProgressiveBlur side="left" size={48} />
  <ProgressiveBlur side="right" size={48} />
</div>

用 `tint` 接續背景色

在不支援 backdrop-filter 的環境，或希望邊緣直接融進背景時，傳入 tint。它接受任何 CSS 色彩字串，通常設成與容器相同的背景色。

<div className="relative h-96 overflow-auto bg-white">
  <ul className="space-y-2 p-4">{/* 訂單列表 */}</ul>
  <ProgressiveBlur
    side="bottom"
    size={120}
    tint="#ffffff"
  />
</div>

加重模糊與使用百分比厚度

size 也可以是字串，例如 "30%" 讓遮罩跟著容器高度走；提高 blur 或 layers 讓最外層更糊。

<div className="relative aspect-video overflow-hidden rounded-2xl">
  <img src="/screenshots/dashboard.png" alt="儀表板截圖" className="size-full object-cover" />
  <ProgressiveBlur side="bottom" size="30%" layers={8} blur={0.75} />
</div>

Props

Prop	型別	預設值	說明
`side`	`"top" \| "bottom" \| "left" \| "right"`	`"bottom"`	模糊貼齊、加深的邊
`size`	`number \| string`	`96`	遮罩沿該邊的厚度（數字為 px）
`layers`	`number`	`6`	疊層數，越多層漸變越滑順
`blur`	`number`	`0.5`	第一層的模糊半徑（px），之後每層加倍
`tint`	`string`	—	沿邊緣由透明淡入到此色，可接續背景蓋住內容
`className`	`string`	—	透傳到覆蓋層容器

說明

每層佔 100 / layers 的窗口寬度，相鄰窗口刻意重疊以消除硬邊色帶；模糊半徑逐層加倍，最靠邊的一層最模糊。
blur 為 0.5、layers 為 6 時，最外層模糊約為 16px；想要更濃可調高 blur 或 layers。
覆蓋層為 pointer-events-none，底下內容維持可捲動、可點擊。
若瀏覽器不支援 backdrop-filter，此層會靜默失效而不影響底下內容；需要在該情況下仍蓋住內容時，搭配 tint 提供漸層底色。

常見問題

可以在 Next.js App Router 使用嗎？

可以。檔案開頭已經有 "use client"，在 Server Component 的頁面裡照一般方式 import 即可。元件本身沒有用到 window，SSR 輸出與用戶端一致。

為什麼我放了之後沒有效果？

ProgressiveBlur 是 absolute 定位，父層需要是 relative（或其他非 static 的定位）。另外模糊的是它「後面」的內容，如果底下是單色背景，看起來就不會有變化。

會影響效能嗎？

每一層都是一個帶 backdrop-filter 的元素，layers 預設 6 層。元件沒有任何動畫或 JavaScript 迴圈，但在低階裝置上若畫面很大，可以把 layers 調低、size 縮小。

需要額外安裝什麼套件？

只需要 cn 工具函式用到的 clsx 與 tailwind-merge。不想用 CLI 的話，切到安裝區塊的「手動」分頁，複製原始碼即可。

Progressive Blur

把這個效果裝進你的專案

本頁目錄