博客

Liquid Glass Design开发阅读约 7 分钟

React 版 Liquid Glass 组件,用 shadcn 安装

React 版 Liquid Glass 组件:38 个开源的 Base UI 组件,在所有现代浏览器里都能折射,用 shadcn CLI 安装。

React 版 Liquid Glass 组件,用 shadcn 安装
本文目录
  1. 包含哪些组件
  2. 用 shadcn 安装 Liquid Glass 组件
  3. 让玻璃后面有东西可折射
  4. 哪些 Liquid Glass UI 组件做成玻璃
  5. iOS 浮动标签栏
  6. Safari 和 Firefox
  7. 主题
  8. 性能
  9. 什么时候该用别的方案
  10. 参考来源

想在 React 应用里用上 Liquid Glass 组件,最快的办法是一条 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 基础组件,下面垫了一层玻璃表面,所以焦点管理、键盘操作和 ARIA 都由 Base UI 负责。

它们的交付方式和 shadcn/ui 组件一样。CLI 把组件文件以普通 TSX 的形式写进你的仓库,你像改其他文件一样改它。唯一留作依赖的是折射内核,也就是 npm 包 @liqui-design/glass。里面有位移贴图的计算、一个共享的 SVG 滤镜注册表和各浏览器的回退方案,这部分代码你大概不会想自己维护。

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 配置都能沿用。

按 URL 添加单个组件:

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 两种都有。默认变体是玻璃,accent 和 danger 是实心填充。带色的透镜会随背后的内容变色,品牌色放在夜景照片上和亮色照片上看起来不一样,就起不到品牌色的作用了。

你自己的设计也可以这样检验:想把复选框做成玻璃时,先问问用户从它身上读到的是什么。如果答案是「开或关」,就做成实心的。

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 会同时加模糊和染色,而模糊会让嵌在另一块透镜里的透镜失效:内层胶囊还没来得及弯折边缘,边缘就先被模糊抹掉了。文档里讲了其中的取舍:frost 为 0.35 时,标签文字很清楚,但选中的胶囊糊成一团;为 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 已经有补丁在审,但仍未关闭。各浏览器的细节见我们的 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. 背景折射(Backdrop refraction):对表面后面的实时页面做位移。仅限 Chromium。
  2. 副本折射(Copy refraction):对已知背景的一份副本做位移。用于 Safari 和 Firefox,限 LiquiBackdrop 内部。
  3. 磨砂(Frost):模糊、染色,加上预先烘焙好的边缘高光。其他情况都用这一级。
  4. 透明(Clear):只有染色和边缘高光,不用 backdrop 滤镜,在你指定 material="clear" 时使用。

副本只对直接放在背景上的表面有效。嵌在另一个表面里的表面,或者 portal 到盒子外面的弹出层,会退回到磨砂,边缘高光保留。所以记得在 Safari 里检查你的 UI:一个调成 frost: 0 的表面到了磨砂层级可能很难看清,因为原来靠透镜完成的事,现在只能交给染色。这时可以跑一遍无障碍指南里的对比度检查。

主题

颜色由十四个 --lq-* 自定义属性控制,CLI 会把它们写进 globals.css。在那里改 --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 作品,每一个都附上实现方式。

一周一封,英文内容,一键退订。