Liquid Glass Design開發閱讀約 7 分鐘
Liquid Glass React 元件:用 shadcn 安裝
Liquid Glass React 元件:38 個開源 Base UI 元件,在各大現代瀏覽器都能折射,用 shadcn CLI 安裝。

本文目錄
要把 Liquid Glass(液態玻璃)元件放進 React 應用程式,最快的方法是一行 shadcn 指令:npx shadcn@latest add https://liqui.design/r/button.json。這行會從 Liqui 安裝一個按鈕。Liqui 是一套以 Base UI 為基礎的玻璃元件,共 38 個,不用 WebGL 就能在 Chromium、Safari 和 Firefox 裡彎折背後的頁面。
Liqui 是我們自己的專案。它從這個作品集發展出來,採用 MIT 授權,原始碼放在 GitHub。它的限制寫在最後一節,可以先看看有沒有讓你用不了的地方。
你會拿到什麼
這個函式庫有 38 個元件:按鈕、選單、下拉選單、對話框、抽屜式面板、滑桿、切換開關、分頁標籤、toast 通知、iOS 風格的浮動標籤頁列,以及搭配它們的表單控制項。每個元件都是一個 Base UI primitive,底下墊著一層玻璃表面,所以焦點處理、鍵盤操作和 ARIA 都由 Base UI 負責。
安裝方式和 shadcn/ui 元件一樣。CLI 會把元件檔以一般 TSX 的形式寫進你的 repo,之後就和其他檔案一樣自己修改。唯一保留為相依套件的是折射核心,也就是 npm 套件 @liqui-design/glass。位移貼圖的數學運算、一個共用的 SVG 濾鏡登錄表(registry)和各瀏覽器的備援都在裡面,這些程式碼你大概不會想自己維護。

用 shadcn 安裝 Liquid Glass 元件
你需要 React 18 或 19,以及 Tailwind CSS v4。Liqui 和 shadcn/ui 用的是同一個 Base UI 基底(shadcn init -b base),所以現有的 components.json、cn() 輔助函式和 token 設定都能沿用。
用網址加入單一元件:
npx shadcn@latest add https://liqui.design/r/button.json這會寫入 components/ui/button.tsx,把玻璃 token 加進 globals.css,並安裝 @liqui-design/glass。如果打算加好幾個,先在 components.json 裡註冊一次命名空間:
{
"registries": {
"@liqui-design": "https://liqui.design/r/{name}.json"
}
}npx shadcn@latest add @liqui-design/button @liqui-design/select@liqui-design/button 是由 shadcn CLI 解析的 registry 項目。執行 npm i @liqui-design/button 會失敗,因為發布到 npm 的套件只有 @liqui-design/glass,而 CLI 會替你安裝它。
用起來和任何 shadcn 元件一樣:
import { Button } from '@/components/ui/button';
export default function Page() {
return (
<main className="min-h-dvh bg-[url(/wallpaper.jpg)] bg-cover p-10">
<Button>Skip</Button>
<Button variant="accent">Continue</Button>
</main>
);
}讓玻璃有東西可以折射
注意那些按鈕背後的背景圖片。透鏡放在單色填色上,看到的就只是那片單色,所以純白頁面上的玻璃按鈕看起來像個略帶灰色的方塊,很容易被誤認成 bug。請把玻璃放在攝影照片、影片、邊緣分明的漸層,或會在底下捲動的內容上。如果設計真的是放在純色上,就設定 material="clear",靠色調來呈現。

sanoj sunny 的滑桿概念設計,正好示範了這種材質需要的搭配:控制項後方是一張形狀鮮明、對比強烈的照片,玻璃才有邊緣可以彎折。為什麼彎折發生在邊緣,我們的 Liquid Glass 是什麼說明文章有解釋。
哪些 Liquid Glass UI 元件是玻璃
Liqui 依照 Apple 劃的界線:玻璃用在讓你透過它來操作的表面,實心填色則用在承載數值的控制項。
- 按鈕、彈出式面板、選單、工具列、sheet 和對話框是玻璃。它們浮在內容上方,讓底下的內容透出來,本來就是這種材質的用意。
- Checkbox、Radio、Toggle 和 Switch 是平面的。平常是
--lq-control加一圈極細邊框,開啟時改用--lq-accent。 - Button 兩種都有。預設 variant 是玻璃。
accent和danger是實心填色,因為帶色調的透鏡會隨背後的東西變色,品牌色如果在夜景照片和明亮照片上看起來不一樣,就發揮不了品牌色的作用。
同樣的判斷也適用於你自己的設計:想把 checkbox 做成玻璃時,先問使用者要從它讀出什麼。如果答案是「開或關」,就做成實心的。
iOS 浮動標籤頁列
Tab Bar 元件仿照 iOS 26 的浮動標籤頁列。它浮在頁面上,折射在底下捲動的列表,按下分頁時還會在手指下方再放一片透鏡。
npx shadcn@latest add https://liqui.design/r/tab-bar.json'use client';
import { useState } from 'react';
import { Heart, House } from 'lucide-react';
import { TabBar, TabBarItem } from '@/components/ui/tab-bar';
export function BottomBar() {
const [tab, setTab] = useState('home');
return (
<TabBar value={tab} onValueChange={setTab}>
<TabBarItem value="home" icon={<House fill="currentColor" strokeWidth={0} />}>Home</TabBarItem>
<TabBarItem value="saved" icon={<Heart fill="currentColor" strokeWidth={0} />} badge={3}>Saved</TabBarItem>
</TabBar>
);
}外觀由 frost 決定。它會同時加上模糊和色調,而模糊會讓疊在另一片透鏡裡的透鏡失效,因為內層膠囊還來不及彎折,邊緣就先被模糊抹掉了。文件裡說明了這個取捨:frost 0.35 時標籤清楚好讀,但選取膠囊糊成一團;frost 為 0 時膠囊正常,頁面內容卻直接穿過標籤;元件最後採用的值是 0.16。

Mahdi Sourabh 的導覽列概念設計從設計端呈現了同樣的平衡:淺色面板疊在捲動的列表上,列表項目從底下經過時,標籤依然清楚可讀。
Safari 與 Firefox
網頁上的折射靠的是 backdrop-filter: url(#filter),到 2026 年 11 月為止只有 Chromium 畫得出來。backdrop-filter 的值只要引用了 SVG 濾鏡,Safari 就會把整個值丟掉,Firefox 則會忽略它。WebKit bug 245510 已經有 patch 在審查中,但仍未關閉。各瀏覽器的細節請看我們的 CSS 與 SVG 教學。
不過這兩個引擎都會在元素自己的內容上繪製 SVG 濾鏡。Liqui 利用的就是這點:用 LiquiBackdrop 包住一塊區域,在頁面本身無法折射時,裡面的每個玻璃表面都會改為折射那塊背景的副本。
import { LiquiBackdrop, LiquiGlass } from '@liqui-design/glass';
<LiquiBackdrop
backdrop={<img src="/wallpaper.jpg" className="absolute inset-0 size-full object-cover" />}
>
<LiquiGlass radius={20}>…</LiquiGlass>
</LiquiBackdrop>每個表面在掛載時會自己選擇算繪層級,不需要任何設定:
- 背景折射:把表面背後的即時頁面加上位移。只有 Chromium。
- 副本折射:把已知背景的副本加上位移。Safari 和 Firefox,在
LiquiBackdrop裡面。 - 霧面:模糊、色調,加上預先烘焙好的邊緣光。其他所有情況。
- 透明:只有色調和邊緣,不套 backdrop filter,在你指定
material="clear"時使用。
副本只對直接放在背景上的表面有效。巢狀在其他表面裡的表面,或是被 portal 到區塊外的彈出式面板,會退回霧面,邊緣光則保留。所以請在 Safari 裡檢查你的 UI:調成 frost: 0 的表面落到霧面層級時可能不好讀,因為原本由透鏡負責的工作,現在只剩色調獨自承擔。這時可以用 Liquid Glass 無障礙指南裡的對比檢查跑一遍。
主題設定
顏色由 CLI 寫進 globals.css 的十四個 --lq-* 自訂屬性控制。在那裡修改 --lq-accent 或 --lq-tint,所有元件都會跟著變,包括被 portal 到 document.body 的彈出式面板。深色模式同時依據 .dark 和 [data-theme='dark'] 判斷,所以覆寫樣式兩邊都要寫。
光學參數沒辦法做成 CSS 變數,因為它們要餵給 canvas 產生的貼圖和 SVG 濾鏡,所以改由 LiquiThemeProvider 傳入。大部分參數(frost、finish、dispersion)是元件可以覆寫的預設值;radiusScale、refractionScale、bezelScale 和 blurScale 則會乘上每個元件自己的數值。這樣把玻璃調厚時,捲軸滑塊和抽屜式面板會按比例一起變厚;如果全域只用一個折射值,捲軸滑塊會糊成一片。
<LiquiThemeProvider theme={{ glass: { frost: 0.2, refractionScale: 1.25 } }}>
{children}
</LiquiThemeProvider>主題編輯器用滑桿調整這兩部分,並匯出 CSS 和 provider 程式碼。主題會保存在你的瀏覽器裡,匯出時只包含你改過的部分。
效能
成本高的是位移貼圖和 backdrop-filter 這條濾鏡鏈。貼圖只在 canvas 上產生一次,並依尺寸和光學參數快取,所以十個同尺寸的按鈕共用一張貼圖。濾鏡全都放在一個隱藏的 SVG 登錄表裡,因此選單重新打開時,第一個影格就有折射。仍然會掉影格的情況有兩種:dispersion 大於 0 時,濾鏡的運算量大約變成三倍;同一個畫面上有十來個套了 backdrop filter 的大面積表面,也會比只有一個大表面更吃效能。
什麼時候該用別的方案
Liqui 只支援 React,而且需要 Tailwind v4,所以沒辦法直接放進 Vue 應用程式或 Tailwind 3 專案。在 WebKit 推出修正之前,任何函式庫都無法在 Safari 裡折射任意的即時內容。如果你只要一塊玻璃面板,不需要整套元件系統,用純 CSS 和 SVG 的做法負擔比較小。我們的 Liquid Glass React 函式庫比較介紹了其他選擇,以及各自的算繪方式。
想先看看元件,文件把每個元件都放在真實的背景上展示;Media Player 範本則能用 npx shadcn@latest add https://liqui.design/r/media-player.json 安裝一整個畫面。如果需要設計上的參考,作品集的 UI 分類收錄了 Dribbble 等平台上設計師做的 Liquid Glass 介面。
版本、設定與數據核對於 2026 年 11 月 20 日(@liqui-design/glass 0.8.0)。
參考資料
- https://liqui.design/docs
- https://liqui.design/docs/handbook/glass
- https://liqui.design/docs/handbook/theming
- https://liqui.design/docs/components/tab-bar
- https://liqui.design/docs/components/button
- https://liqui.design/llms-full.txt
- https://github.com/leefanv/liqui-design
- https://www.npmjs.com/package/@liqui-design/glass
- https://base-ui.com
- https://ui.shadcn.com/docs/cli
- https://bugs.webkit.org/show_bug.cgi?id=245510