---
title: "Liquid Glass React 元件：用 shadcn 安裝"
description: "Liquid Glass React 元件：38 個開源 Base UI 元件，在各大現代瀏覽器都能折射，用 shadcn CLI 安裝。"
url: https://liquidglassdesign.com/zh-TW/blog/liquid-glass-react-components
language: zh-Hant
published: 2026-11-20
updated: 2026-11-20
author: "Liquid Glass Design"
tags: ["Web 前端","程式碼","元件"]
translations:
  en: https://liquidglassdesign.com/blog/liquid-glass-react-components.md
  zh-Hans: https://liquidglassdesign.com/zh/blog/liquid-glass-react-components.md
  ja: https://liquidglassdesign.com/ja/blog/liquid-glass-react-components.md
  hi: https://liquidglassdesign.com/hi/blog/liquid-glass-react-components.md
---

# 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](https://liqui.design/?utm_source=liquidglassdesign.com&utm_medium=referral&utm_campaign=blog_components) 安裝一個按鈕。Liqui 是一套以 Base UI 為基礎的玻璃元件，共 38 個，不用 WebGL 就能在 Chromium、Safari 和 Firefox 裡彎折背後的頁面。

Liqui 是我們自己的專案。它從這個作品集發展出來，採用 MIT 授權，原始碼放在 [GitHub](https://github.com/leefanv/liqui-design)。它的限制寫在最後一節，可以先看看有沒有讓你用不了的地方。

## 你會拿到什麼

這個函式庫有 38 個元件：按鈕、選單、下拉選單、對話框、抽屜式面板、滑桿、切換開關、分頁標籤、toast 通知、iOS 風格的浮動標籤頁列，以及搭配它們的表單控制項。每個元件都是一個 [Base UI](https://base-ui.com) primitive，底下墊著一層玻璃表面，所以焦點處理、鍵盤操作和 ARIA 都由 Base UI 負責。

安裝方式和 shadcn/ui 元件一樣。CLI 會把元件檔以一般 TSX 的形式寫進你的 repo，之後就和其他檔案一樣自己修改。唯一保留為相依套件的是折射核心，也就是 npm 套件 `@liqui-design/glass`。位移貼圖的數學運算、一個共用的 SVG 濾鏡登錄表（registry）和各瀏覽器的備援都在裡面，這些程式碼你大概不會想自己維護。

![Liqui 首頁的展示區：沙漠照片上一組仿 macOS 控制中心的玻璃面板，旁邊是有折射、邊框寬度和霧面滑桿的 Optics 面板](https://cdn.liquidglassdesign.com/blog/2beccd42-12aa-4a13-861c-083c6c041f0a.jpg)

*Liqui 首頁的展示區，於 Chromium 中截圖。* [開啟 liqui.design](https://liqui.design/?utm_source=liquidglassdesign.com&utm_medium=referral&utm_campaign=blog_components)

## 用 shadcn 安裝 Liquid Glass 元件

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

用網址加入單一元件：

```bash
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"
  }
}
```

```bash
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 按鈕，浮在一張手握黑色喇叭的特寫照片上](https://cdn.liquidglassdesign.com/gallery/296cd13d-8a84-8095-9a94-c13755eef388.webp)

*Liquid Glass - Slider Concept(Volume) by sanoj sunny。* [在作品集中查看](https://liquidglassdesign.com/gallery/liquid-glass-slider-concept%28volume%29)

sanoj sunny 的滑桿概念設計，正好示範了這種材質需要的搭配：控制項後方是一張形狀鮮明、對比強烈的照片，玻璃才有邊緣可以彎折。為什麼彎折發生在邊緣，我們的 [Liquid Glass 是什麼](https://liquidglassdesign.com/zh-TW/what-is-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 的浮動標籤頁列。它浮在頁面上，折射在底下捲動的列表，按下分頁時還會在手指下方再放一片透鏡。

```bash
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](https://cdn.liquidglassdesign.com/gallery/545590e9-61cb-48b2-9a28-66b12941f222.webp)

*Liquid Glass Mobile app Navbar by Mahdi Sourabh。* [在作品集中查看](https://liquidglassdesign.com/gallery/liquid-glass-mobile-app-navbar)

Mahdi Sourabh 的導覽列概念設計從設計端呈現了同樣的平衡：淺色面板疊在捲動的列表上，列表項目從底下經過時，標籤依然清楚可讀。

## Safari 與 Firefox

網頁上的折射靠的是 `backdrop-filter: url(#filter)`，到 2026 年 11 月為止只有 Chromium 畫得出來。`backdrop-filter` 的值只要引用了 SVG 濾鏡，Safari 就會把整個值丟掉，Firefox 則會忽略它。WebKit bug 245510 已經有 patch 在審查中，但仍未關閉。各瀏覽器的細節請看我們的 [CSS 與 SVG 教學](https://liquidglassdesign.com/zh-TW/blog/liquid-glass-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 無障礙指南](https://liquidglassdesign.com/zh-TW/blog/liquid-glass-accessibility)裡的對比檢查跑一遍。

## 主題設定

顏色由 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>
```

[主題編輯器](https://liqui.design/theme?utm_source=liquidglassdesign.com&utm_medium=referral&utm_campaign=blog_components)用滑桿調整這兩部分，並匯出 CSS 和 provider 程式碼。主題會保存在你的瀏覽器裡，匯出時只包含你改過的部分。

## 效能

成本高的是位移貼圖和 `backdrop-filter` 這條濾鏡鏈。貼圖只在 canvas 上產生一次，並依尺寸和光學參數快取，所以十個同尺寸的按鈕共用一張貼圖。濾鏡全都放在一個隱藏的 SVG 登錄表裡，因此選單重新打開時，第一個影格就有折射。仍然會掉影格的情況有兩種：`dispersion` 大於 0 時，濾鏡的運算量大約變成三倍；同一個畫面上有十來個套了 backdrop filter 的大面積表面，也會比只有一個大表面更吃效能。

## 什麼時候該用別的方案

Liqui 只支援 React，而且需要 Tailwind v4，所以沒辦法直接放進 Vue 應用程式或 Tailwind 3 專案。在 WebKit 推出修正之前，任何函式庫都無法在 Safari 裡折射任意的即時內容。如果你只要一塊玻璃面板，不需要整套元件系統，用純 CSS 和 SVG 的做法負擔比較小。我們的 [Liquid Glass React 函式庫比較](https://liquidglassdesign.com/zh-TW/blog/liquid-glass-react-libraries)介紹了其他選擇，以及各自的算繪方式。

想先看看元件，[文件](https://liqui.design/docs/components?utm_source=liquidglassdesign.com&utm_medium=referral&utm_campaign=blog_components)把每個元件都放在真實的背景上展示；Media Player 範本則能用 `npx shadcn@latest add https://liqui.design/r/media-player.json` 安裝一整個畫面。如果需要設計上的參考，[作品集的 UI 分類](https://liquidglassdesign.com/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
