@glass-sdk/liquid-glass

中文文档
0.0.2发布于 2026/10/10MITTypeScriptES Module近 30 天下载 7897

Liquid Glass materials and accessible React components for the web and Electron, built with vgpu and WGSL.

原始使用文档
文档目录12 节
  1. Install
  2. Quick start
  3. Components
  4. Material and motion
  5. Composing controls
  6. Tabs, sliders, and switches
  7. Progressive blur
  8. Content shapes and foregrounds
  9. Without React
  10. Requirements and limitations
  11. How it works
  12. Contributing and license

Liquid Glass

Glass surfaces and controls for React, the web, and Electron. Clear and Regular materials support light and dark appearances and refract live content.

Examples and component reference · GitHub

Install

npm install @glass-sdk/liquid-glass@~0.0.2

Quick start

import { GlassScene, GlassContent, GlassSurface, GlassButton } from "@glass-sdk/liquid-glass";
import "@glass-sdk/liquid-glass/styles.css";

export function Example() {
  return (
    <GlassScene material="regular" appearance="light" style={{ height: 320 }}>
      <GlassContent>
        <img src="/landscape.jpg" alt="Mountain lake"
          style={{ width: "100%", height: "100%", objectFit: "cover" }} />
      </GlassContent>
      <GlassSurface radius={28}
        style={{ position: "absolute", left: 24, top: 100, padding: 20 }}>
        <GlassButton onClick={() => console.log("Saved")}>Save</GlassButton>
      </GlassSurface>
    </GlassScene>
  );
}

Import the stylesheet once. It requires neither Tailwind nor a CSS reset. Put glass components inside GlassScene, with one GlassContent layer for the background. Text, SVG, and images in that layer stay live. In Next.js, use a client component.

GlassContent keeps your props, ref, and children on its source element inside stable transparent wrappers. Target its class rather than relying on it being a direct child of the scene. Put opacity and clipping intended for the finished composition on GlassScene or a shared ancestor; GlassContent styles describe the input behind the glass.

Components

ComponentPurpose
GlassScene, GlassContentScene and live background layer.
GlassSurface, GlassButtonGlass container and button.
GlassToolbar, GlassToolbarButton, GlassToolbarLink, GlassToolbarGroup, GlassToolbarSpacerKeyboard-navigable toolbar.
GlassTabsTab bar with a moving selection indicator.
GlassTabsRoot, GlassTabsList, GlassTabsTrigger, GlassTabsIndicator, GlassTabsContentComposable tabs and panels.
GlassMenu, GlassMenuTrigger, GlassMenuContent, GlassMenuItemMenu with positioning and focus restoration.
GlassMenuSubmenu, GlassMenuSubmenuTrigger, GlassMenuSubmenuContentNested menus.
GlassSlider, GlassSwitchSlider and switch.
GlassForeground, useGlassForegroundForeground content that higher glass surfaces can refract.
GlassShape, GlassShapeContainer, GlassCornerContinuous corners and container-relative geometry.
GlassProgressiveBlur, GlassScrollEdgesProgressive blur over background content and scroll edges.

Buttons, toolbars, tabs, menus, sliders, and switches use Base UI behavior. Standard props, refs, accessible names, and state callbacks remain available. See the component examples for usage and the Base UI reference for inherited props.

Material and motion

Set defaults on GlassScene; individual surfaces can override them. Menu popups default to Regular.

PropDefaultUsage
material"clear""clear" or "regular".
appearance"light""light" or "dark".
radiusComponent-specificContinuous corner radius in CSS pixels, "capsule", or "circle". Generic surfaces default to 8px.
refraction60Nonnegative displacement in CSS pixels. Nested surfaces limit their default to the parent inset.
tintNoneSix-digit hex color. Colors the glass without changing text or icons.
interactiveComponent-specificPress and drag feedback; on by default for buttons, toolbars, and tab bars.
fluidfalseAnimate the outline when layout dimensions change.
morphFromNoneElement ref or getter for a surface's opening and closing shape.
morphBy context"become" replaces its source; "detach" separates from it.
motion"full""full", "reduced", or "none"; inherited from the scene.

Slider and switch pressed thumbs default to Clear, with refraction of 5px and 7.75px respectively. Their tint sets the track color.

System reduced-motion preferences always apply, including with motion="full". Reduced motion removes stretching and travel; "none" removes transitions. Safari uses the same motion settings as other browsers.

Override styles with className, inline styles, or CSS utilities. The stylesheet uses low-specificity :where() selectors. Use radius to change corners so the material and content clip agree. Override --lg-foreground for text and icon colors.

Composing controls

The render prop merges props, handlers, styles, and refs with your component. Custom components must forward them to their DOM element. Use transparent backgrounds to keep the glass visible.

<GlassSurface material="clear" render={<Button onClick={save} />}>
  Save
</GlassSurface>

Menus stay inside their scene. Content accepts side, align, sideOffset, alignOffset, and collisionAvoidance; defaults are bottom/end with an 8px offset. Use positionerProps and portalProps for additional Base UI options.

<GlassMenu>
  <GlassMenuTrigger render={<GlassButton />}>Options</GlassMenuTrigger>
  <GlassMenuContent>
    <GlassMenuItem onClick={save}>Save</GlassMenuItem>
    <GlassMenuSubmenu>
      <GlassMenuSubmenuTrigger>Share</GlassMenuSubmenuTrigger>
      <GlassMenuSubmenuContent>
        <GlassMenuItem onClick={copyLink}>Copy link</GlassMenuItem>
      </GlassMenuSubmenuContent>
    </GlassMenuSubmenu>
  </GlassMenuContent>
</GlassMenu>

GlassMenuGroup, GlassMenuGroupLabel, GlassMenuSeparator, GlassMenuCheckboxItem, GlassMenuRadioGroup, and GlassMenuRadioItem expose the corresponding Base UI parts.

In a toolbar, compose the trigger with GlassToolbarButton render={<GlassMenuTrigger />}. Use toolbar buttons and links for arrow-key navigation. GlassToolbarSpacer separates glass groups: sizing="fixed" gives an 8px gap; "flexible" fills available space. Give the toolbar a width or height for flexible spacing.

Tabs, sliders, and switches

<GlassTabs aria-label="Navigation" defaultValue="home"
  items={[{ value: "home", label: "Home" }, { value: "library", label: "Library" }]} />

<GlassSlider aria-label="Volume" defaultValue={50}
  onValueCommitted={(value) => console.log(value)} />
<GlassSlider ticks aria-label="Intensity" min={0} max={100} step={25} />
<label>Notifications <GlassSwitch name="notifications" defaultChecked /></label>

Tabs select the first enabled item unless defaultValue is set. Use value and onValueChange for controlled selection. For panels or custom triggers, compose the tab parts:

<GlassTabsRoot defaultValue="preview">
  <GlassTabsList aria-label="View">
    <GlassTabsIndicator />
    <GlassTabsTrigger value="preview">Preview</GlassTabsTrigger>
    <GlassTabsTrigger value="usage">Usage</GlassTabsTrigger>
  </GlassTabsList>
  <GlassTabsContent value="preview">Your preview</GlassTabsContent>
  <GlassTabsContent value="usage">Your usage code</GlassTabsContent>
</GlassTabsRoot>

The list also works within an existing Base UI tabs root; do not nest another root. Keep interactive elements out of tab labels.

Sliders accept a numeric value or defaultValue, min, max, step, onValueChange, and onValueCommitted. Defaults are 0–100 with a 0.1 step. With ticks, the step must divide the range evenly, with at most 100 intervals. thumbProps exposes input refs and accessible value text.

Switches accept Base UI switch props, including checked, defaultChecked, onCheckedChange, name, and inputRef. Name inputs with a label or aria-label. Both controls support forms, RTL, tint, and reduced motion.

Progressive blur

GlassProgressiveBlur softens GlassContent at an edge. Put captions and controls outside that content layer to keep them sharp.

<GlassScene style={{ height: 320, overflow: "hidden" }}>
  <GlassContent>
    <img src="/landscape.jpg" alt="Mountain lake"
      style={{ width: "100%", height: "100%", objectFit: "cover" }} />
  </GlassContent>
  <GlassProgressiveBlur edge="bottom" size={80} blur={20} />
</GlassScene>

For scrolling content, use GlassContent layout="scroll" as the viewport and pass its ref to GlassScrollEdges. This keeps the glass and blur stationary during Safari scrolling. Give the scene a bounded height, and place floating controls beside the content:

const viewport = useRef<HTMLDivElement>(null);

<GlassScene style={{ height: 320, overflow: "hidden" }}>
  <GlassContent layout="scroll" ref={viewport} tabIndex={0} role="region"
    aria-label="Reading list" style={{ scrollPaddingBlock: 80 }}>
    {children}
  </GlassContent>
  <GlassScrollEdges target={viewport} size={80} blur={20} />
</GlassScene>
PropDefaultUsage
edge"bottom"Primitive edge: top, bottom, inline-start, or inline-end.
edges["top", "bottom"]Scroll helper edges. Logical edges follow direction.
targetRequired on scroll helperRef to the scrolling viewport.
size80Edge depth in pixels, 0–4096; scroll edges clamp to half the viewport.
blur20Gaussian standard deviation in pixels, 0–64.
refraction0Optical displacement in pixels, 0–32.
disabledfalseRemove the effect.

The viewport needs an explicit height and scrolling overflow. Keep fixed headers and controls outside it, and use scroll padding so focused content can enter the clear area. Blur clears at reached edges and when there is no overflow. Reduced transparency and forced colors disable the effect. If map preparation fails, content remains readable and onDiagnostic reports the error.

Content shapes and foregrounds

GlassShape clips images and content to continuous corners without needing a scene:

<GlassShape radius={28} render={<img src="/cover.jpg" alt="Album cover" />} />
<GlassShape radius={40} style={{ padding: 4 }}>
  <GlassShape concentric={{ inset: 4 }} radius={8}>Nested content</GlassShape>
</GlassShape>

concentric follows the nearest declared container's outline. GlassSurface supports it too. Use GlassShapeContainer to declare geometry without clipping; GlassCorner positions a control near a curved corner. Both concentric shapes and corner controls accept container={containerRef} for siblings or portals. The container must be measurable; rotation is unsupported. Keep popups outside clipped content.

Use GlassForeground for ordinary DOM above the background that should refract beneath a higher glass surface. For an existing element ref, use useGlassForeground(). Keep overlapping content and menus in the same scene.

Without React

import { createGlassScene } from "@glass-sdk/liquid-glass/dom";
import "@glass-sdk/liquid-glass/styles.css";

const scene = createGlassScene(document.querySelector<HTMLElement>(".lg-scene")!);
scene.setContent(document.querySelector<HTMLElement>(".lg-content")!);
const remove = scene.addSurface(document.querySelector<HTMLElement>(".lg-surface")!, {
  material: "regular", radius: 28,
});

// On teardown:
remove();
scene.dispose();

Use the positioned scene/content/surface structure from the React example. scene.addForeground(element) registers foreground content and returns a cleanup function. scene.addAnimator(animator) updates custom animation before scene measurements.

In Firefox, each surface draws its own glass: the scene adds an aria-hidden layer as the surface's last child, beneath its other children, which paints a live -moz-element() view of the content and refracts it. The content layer itself is not filtered there. Firefox otherwise repaints a filtered content layer in software on every frame anything on the page animates. If the content element has no id, the scene gives it one while it is attached. Surfaces should not rely on :last-child styling of their own children.

The /core, /gpu, and /dom exports provide geometry, materials, rendering, and controller APIs for custom integrations. Type declarations describe their options.

Requirements and limitations

  • React 19+ for React components; HTTPS or localhost and an available WebGPU adapter to render glass material maps. Progressive blur needs no WebGPU.
  • SVG filter performance varies between browser engines. Safari can spend substantially longer filtering large content layers than Chromium, even when material maps are cached. Keep scenes close to the content they need to refract, and test animated menus on the devices you support. Chromium, Firefox, Safari, and Electron are acceptance targets; they do not have identical performance.
  • For consistent refraction in Safari, give GlassContent an opaque background. Transparent source pixels can leave the original content visible beneath its refracted image.
  • Use bounded scenes with explicit content layers. Arbitrary page-backdrop sampling, native video composition, rotated/transformed ancestors, and native ports are outside the supported scope. Cross-origin image policies apply.
  • GlassScene.maxSurfaces defaults to 16 and accepts at most 64. Use onDiagnostic for map readiness, construction timing, filter graph limits, and GPU errors.
  • NodeNext TypeScript consumers currently need skipLibCheck: true for upstream vgpu declarations.

How it works

vgpu renders WGSL material maps; SVG filters apply them to live DOM content. Maps are cached and reused as surfaces move. Geometry changes prepare new maps. The library does not capture DOM screenshots.

Contributing and license

See Contributing. Licensed under MIT.

版本与发布记录

@glass-sdk/liquid-glass 共发布 3 个版本,首次发布于 2026/10/08;过去 12 个月发布了 3 个版本。

版本发布日期距今
0.0.2latest2026/10/101 个月前
0.0.12026/10/081 个月前
0.0.0-stage2026/10/081 个月前

关于 @glass-sdk/liquid-glass 的常见问题

@glass-sdk/liquid-glass 是什么?

Liquid Glass materials and accessible React components for the web and Electron, built with vgpu and WGSL.

如何安装 @glass-sdk/liquid-glass?

在项目目录运行 npm install @glass-sdk/liquid-glass,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(>=19.0.0)、react-dom(>=19.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@glass-sdk/liquid-glass 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@glass-sdk/liquid-glass 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@glass-sdk/liquid-glass 可以商用吗?

@glass-sdk/liquid-glass 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@glass-sdk/liquid-glass 的下载量有多少?

根据 npm 官方下载统计,@glass-sdk/liquid-glass 在 2026/10/17 – 2026/11/15 这 30 天内被下载 7,897 次,日均约 263 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@glass-sdk/liquid-glass 还在维护吗?

最新版本 0.0.2 发布于 2026/10/10(1 个月前);至今共发布 3 个版本,其中过去 12 个月发布了 3 个;首次发布于 2026/10/08。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。