部落格

Liquid Glass Design開發閱讀約 7 分鐘

Liquid Glass React 元件:用 shadcn 安裝

Liquid Glass React 元件:38 個開源 Base UI 元件,在各大現代瀏覽器都能折射,用 shadcn CLI 安裝。

Liquid Glass React 元件:用 shadcn 安裝
本文目錄
  1. 你會拿到什麼
  2. 用 shadcn 安裝 Liquid Glass 元件
  3. 讓玻璃有東西可以折射
  4. 哪些 Liquid Glass UI 元件是玻璃
  5. iOS 浮動標籤頁列
  6. Safari 與 Firefox
  7. 主題設定
  8. 效能
  9. 什麼時候該用別的方案
  10. 參考資料

要把 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)和各瀏覽器的備援都在裡面,這些程式碼你大概不會想自己維護。

Liqui 首頁的展示區:沙漠照片上一組仿 macOS 控制中心的玻璃面板,旁邊是有折射、邊框寬度和霧面滑桿的 Optics 面板
Liqui 首頁的展示區,於 Chromium 中截圖。 開啟 liqui.design

用 shadcn 安裝 Liquid Glass 元件

你需要 React 18 或 19,以及 Tailwind CSS v4。Liqui 和 shadcn/ui 用的是同一個 Base UI 基底(shadcn init -b base),所以現有的 components.json、cn() 輔助函式和 token 設定都能沿用。

用網址加入單一元件:

Terminal
npx shadcn@latest add https://liqui.design/r/button.json

這會寫入 components/ui/button.tsx,把玻璃 token 加進 globals.css,並安裝 @liqui-design/glass。如果打算加好幾個,先在 components.json 裡註冊一次命名空間:

JSON
{
  "registries": {
    "@liqui-design": "https://liqui.design/r/{name}.json"
  }
}
Terminal
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 元件一樣:

TSX
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",靠色調來呈現。

停在 52 的玻璃音量滑桿和一個圓形 AirPlay 按鈕,浮在一張手握黑色喇叭的特寫照片上
Liquid Glass - Slider Concept(Volume) by sanoj sunny。 在作品集中查看

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 的浮動標籤頁列。它浮在頁面上,折射在底下捲動的列表,按下分頁時還會在手指下方再放一片透鏡。

Terminal
npx shadcn@latest add https://liqui.design/r/tab-bar.json
TSX
'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。

iPhone 螢幕底部,訊息列表上浮著一條半透明的標籤頁列,項目有 Dashboard、Inbox、Scan、Customer 和 More
Liquid Glass Mobile app Navbar by Mahdi Sourabh。 在作品集中查看

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 包住一塊區域,在頁面本身無法折射時,裡面的每個玻璃表面都會改為折射那塊背景的副本。

TSX
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>

每個表面在掛載時會自己選擇算繪層級,不需要任何設定:

  1. 背景折射:把表面背後的即時頁面加上位移。只有 Chromium。
  2. 副本折射:把已知背景的副本加上位移。Safari 和 Firefox,在 LiquiBackdrop 裡面。
  3. 霧面:模糊、色調,加上預先烘焙好的邊緣光。其他所有情況。
  4. 透明:只有色調和邊緣,不套 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 則會乘上每個元件自己的數值。這樣把玻璃調厚時,捲軸滑塊和抽屜式面板會按比例一起變厚;如果全域只用一個折射值,捲軸滑塊會糊成一片。

TSX
<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)。

參考資料

分享這篇文章

每週更新,精選新參考

精選 Liquid Glass 作品,每一個都附上實作方式。

一週一封,英文內容,一鍵取消訂閱。