@glass-sdk/liquid-glass 0.0.1 → 0.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +133 -494
- package/dist/core/concentric.js +86 -0
- package/dist/core/materials.js +41 -0
- package/dist/core/morph-path.js +206 -0
- package/dist/core/optics.js +7 -0
- package/dist/core/progressive.js +35 -0
- package/dist/{concentric-COCiG9DQ.js → core/shape.js} +1 -85
- package/dist/core/spring.js +78 -0
- package/dist/core/union.js +117 -0
- package/dist/core.js +6 -9
- package/dist/dom/compose-layers.js +54 -0
- package/dist/dom/compound-field.js +23 -0
- package/dist/dom/control-motion.js +101 -0
- package/dist/dom/engine.js +7 -0
- package/dist/dom/exit-handoff.js +14 -0
- package/dist/dom/filter-bounds.js +87 -0
- package/dist/dom/filter-budget.js +45 -0
- package/dist/dom/filter-groups.js +38 -0
- package/dist/dom/filter-paint-root.js +41 -0
- package/dist/dom/filter-patch.js +129 -0
- package/dist/dom/filter-reach.js +36 -0
- package/dist/dom/filter-stages.js +7 -0
- package/dist/dom/fixed-shape.js +20 -0
- package/dist/dom/foreground.js +36 -0
- package/dist/dom/interaction.js +129 -0
- package/dist/dom/lens-layers.js +163 -0
- package/dist/dom/map-blend.js +8 -0
- package/dist/dom/map-encoder.js +47 -0
- package/dist/dom/map-encoder.worker.js +16 -0
- package/dist/dom/map-encoding.js +17 -0
- package/dist/dom/map-image.js +34 -0
- package/dist/dom/map-store.js +189 -0
- package/dist/dom/maps.js +131 -0
- package/dist/dom/material-graph.js +52 -0
- package/dist/dom/morph.js +296 -0
- package/dist/dom/page-zoom.js +46 -0
- package/dist/dom/png.js +105 -0
- package/dist/dom/progressive.js +299 -0
- package/dist/dom/renderer.js +6 -0
- package/dist/dom/sampling-bounds.js +22 -0
- package/dist/dom/selection.js +106 -0
- package/dist/dom/shape-layout.js +199 -0
- package/dist/dom/shared-backdrop.js +41 -0
- package/dist/dom/ticker.js +103 -0
- package/dist/dom/warm.js +108 -0
- package/dist/dom.js +694 -2
- package/dist/gpu/geometry.js +9 -0
- package/dist/gpu/maps.js +8 -0
- package/dist/gpu/planes.js +4 -0
- package/dist/gpu.js +213 -2
- package/dist/index.js +10 -932
- package/dist/react/button.js +23 -0
- package/dist/react/control-thumb.js +50 -0
- package/dist/react/menu.js +159 -0
- package/dist/react/merged-ref.js +18 -0
- package/dist/react/progressive.js +73 -0
- package/dist/react/scene.js +122 -0
- package/dist/react/shape.js +93 -0
- package/dist/react/surface.js +69 -0
- package/dist/react/tabs.js +94 -0
- package/dist/react/toolbar.js +145 -0
- package/dist/react/value-control-motion.js +9 -0
- package/dist/react/value-controls.js +176 -0
- package/dist/styles.css +19 -0
- package/dist/types/core/optics.d.ts +0 -1
- package/dist/types/core/spring.d.ts +1 -1
- package/dist/types/dom/compose-layers.d.ts +15 -0
- package/dist/types/dom/compound-field.d.ts +35 -0
- package/dist/types/dom/engine.d.ts +9 -0
- package/dist/types/dom/exit-handoff.d.ts +7 -0
- package/dist/types/dom/filter-bounds.d.ts +1 -1
- package/dist/types/dom/filter-budget.d.ts +20 -0
- package/dist/types/dom/filter-groups.d.ts +25 -0
- package/dist/types/dom/filter-paint-root.d.ts +9 -0
- package/dist/types/dom/filter-patch.d.ts +3 -8
- package/dist/types/dom/filter-reach.d.ts +23 -0
- package/dist/types/dom/filter-stages.d.ts +5 -0
- package/dist/types/dom/index.d.ts +3 -0
- package/dist/types/dom/lens-layers.d.ts +68 -0
- package/dist/types/dom/map-blend.d.ts +22 -0
- package/dist/types/dom/map-encoding.d.ts +1 -1
- package/dist/types/dom/map-image.d.ts +5 -2
- package/dist/types/dom/maps.d.ts +5 -5
- package/dist/types/dom/material-graph.d.ts +22 -0
- package/dist/types/dom/morph.d.ts +8 -0
- package/dist/types/dom/page-zoom.d.ts +18 -0
- package/dist/types/dom/png.d.ts +2 -0
- package/dist/types/dom/progressive.d.ts +29 -1
- package/dist/types/dom/renderer.d.ts +4 -0
- package/dist/types/dom/sampling-bounds.d.ts +10 -0
- package/dist/types/dom/shared-backdrop.d.ts +19 -0
- package/dist/types/dom/warm.d.ts +4 -1
- package/dist/types/gpu/geometry.d.ts +17 -0
- package/dist/types/gpu/index.d.ts +4 -16
- package/dist/types/gpu/planes.d.ts +2 -0
- package/dist/types/react/button.d.ts +11 -0
- package/dist/types/react/index.d.ts +14 -149
- package/dist/types/react/menu.d.ts +29 -0
- package/dist/types/react/progressive.d.ts +15 -0
- package/dist/types/react/scene.d.ts +35 -0
- package/dist/types/react/surface.d.ts +35 -0
- package/dist/types/react/tabs.d.ts +29 -0
- package/dist/types/react/toolbar.d.ts +21 -0
- package/package.json +1 -1
- package/dist/dom-CKc8vDTR.js +0 -2532
- package/dist/gpu-Co5Y89mh.js +0 -244
- package/dist/map-encoder.worker-DO1drw0Y.js +0 -16
- package/dist/materials-DVPgteZ9.js +0 -234
- package/dist/types/dom/progressive-maps.d.ts +0 -6
package/README.md
CHANGED
|
@@ -1,47 +1,30 @@
|
|
|
1
1
|
# Liquid Glass
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Glass surfaces and controls for React, the web, and Electron. Clear and Regular materials support light and dark appearances and refract live content.
|
|
4
4
|
|
|
5
|
-
[
|
|
5
|
+
[Examples and component reference](https://liquid-glass.glassapp.dev/#examples) · [GitHub](https://github.com/Glass-HQ/liquid-glass)
|
|
6
6
|
|
|
7
7
|
## Install
|
|
8
8
|
|
|
9
9
|
```sh
|
|
10
|
-
|
|
11
|
-
# npm install @glass-sdk/liquid-glass@~0.0.1
|
|
10
|
+
npm install @glass-sdk/liquid-glass@~0.0.2
|
|
12
11
|
```
|
|
13
12
|
|
|
14
|
-
The `~0.0.1` range accepts subsequent `0.0.x` patch releases.
|
|
15
|
-
|
|
16
13
|
## Quick start
|
|
17
14
|
|
|
18
15
|
```tsx
|
|
19
|
-
import {
|
|
20
|
-
GlassScene,
|
|
21
|
-
GlassContent,
|
|
22
|
-
GlassSurface,
|
|
23
|
-
GlassButton,
|
|
24
|
-
} from "@glass-sdk/liquid-glass";
|
|
16
|
+
import { GlassScene, GlassContent, GlassSurface, GlassButton } from "@glass-sdk/liquid-glass";
|
|
25
17
|
import "@glass-sdk/liquid-glass/styles.css";
|
|
26
18
|
|
|
27
19
|
export function Example() {
|
|
28
20
|
return (
|
|
29
|
-
<GlassScene style={{ height:
|
|
21
|
+
<GlassScene material="regular" appearance="light" style={{ height: 320 }}>
|
|
30
22
|
<GlassContent>
|
|
31
|
-
<
|
|
32
|
-
style={{
|
|
33
|
-
height: "100%",
|
|
34
|
-
background: "linear-gradient(120deg, #91b5c8, #d79872)",
|
|
35
|
-
}}
|
|
36
|
-
>
|
|
37
|
-
<h1>Your live content</h1>
|
|
38
|
-
</div>
|
|
23
|
+
<img src="/landscape.jpg" alt="Mountain lake"
|
|
24
|
+
style={{ width: "100%", height: "100%", objectFit: "cover" }} />
|
|
39
25
|
</GlassContent>
|
|
40
|
-
<GlassSurface
|
|
41
|
-
|
|
42
|
-
radius={32}
|
|
43
|
-
style={{ position: "absolute", left: 40, top: 120, padding: 24 }}
|
|
44
|
-
>
|
|
26
|
+
<GlassSurface radius={28}
|
|
27
|
+
style={{ position: "absolute", left: 24, top: 100, padding: 20 }}>
|
|
45
28
|
<GlassButton onClick={() => console.log("Saved")}>Save</GlassButton>
|
|
46
29
|
</GlassSurface>
|
|
47
30
|
</GlassScene>
|
|
@@ -49,348 +32,168 @@ export function Example() {
|
|
|
49
32
|
}
|
|
50
33
|
```
|
|
51
34
|
|
|
52
|
-
|
|
35
|
+
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.
|
|
53
36
|
|
|
54
|
-
|
|
37
|
+
`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.
|
|
55
38
|
|
|
56
|
-
|
|
57
|
-
untinted glass. Tint gives the optical material a saturated hue, with refracted backdrop
|
|
58
|
-
luminance providing depth and color-aware highlights preserving the rim; it does not change the content color.
|
|
39
|
+
## Components
|
|
59
40
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
41
|
+
| Component | Purpose |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| `GlassScene`, `GlassContent` | Scene and live background layer. |
|
|
44
|
+
| `GlassSurface`, `GlassButton` | Glass container and button. |
|
|
45
|
+
| `GlassToolbar`, `GlassToolbarButton`, `GlassToolbarLink`, `GlassToolbarGroup`, `GlassToolbarSpacer` | Keyboard-navigable toolbar. |
|
|
46
|
+
| `GlassTabs` | Tab bar with a moving selection indicator. |
|
|
47
|
+
| `GlassTabsRoot`, `GlassTabsList`, `GlassTabsTrigger`, `GlassTabsIndicator`, `GlassTabsContent` | Composable tabs and panels. |
|
|
48
|
+
| `GlassMenu`, `GlassMenuTrigger`, `GlassMenuContent`, `GlassMenuItem` | Menu with positioning and focus restoration. |
|
|
49
|
+
| `GlassMenuSubmenu`, `GlassMenuSubmenuTrigger`, `GlassMenuSubmenuContent` | Nested menus. |
|
|
50
|
+
| `GlassSlider`, `GlassSwitch` | Slider and switch. |
|
|
51
|
+
| `GlassForeground`, `useGlassForeground` | Foreground content that higher glass surfaces can refract. |
|
|
52
|
+
| `GlassShape`, `GlassShapeContainer`, `GlassCorner` | Continuous corners and container-relative geometry. |
|
|
53
|
+
| `GlassProgressiveBlur`, `GlassScrollEdges` | Progressive blur over background content and scroll edges. |
|
|
64
54
|
|
|
65
|
-
|
|
66
|
-
submenu content. Set it on each material surface you want to color.
|
|
67
|
-
|
|
68
|
-
## Motion
|
|
69
|
-
|
|
70
|
-
Glass responds to touch and pointer input the way the material does on iPhone.
|
|
71
|
-
Under a press it grows and lights up from beneath the pointer. Drag, and it
|
|
72
|
-
stretches toward your finger with constant volume, then settles with a gel-like
|
|
73
|
-
overshoot when you let go. Menus open as one continuous piece of glass: a
|
|
74
|
-
glass button becomes its menu, its icon withdrawing as the glass stretches
|
|
75
|
-
away from it and the items condensing out of a blur once there is room for
|
|
76
|
-
them; a button inside a toolbar lets the menu leave the toolbar as a drop,
|
|
77
|
-
joined by a liquid neck until it pinches off. Closing runs the same path back.
|
|
78
|
-
Toolbars flow when their spacers change, and the tab bar's selection lens
|
|
79
|
-
lifts so you can drag it to another tab.
|
|
80
|
-
|
|
81
|
-
Every component chooses sensible motion by default, and every glass surface
|
|
82
|
-
accepts the same props:
|
|
83
|
-
|
|
84
|
-
| Prop | Default | Meaning |
|
|
85
|
-
| ------------- | ---------------------- | ------- |
|
|
86
|
-
| `interactive` | See below | Grow under a press, stretch toward a drag, settle with overshoot, and light up beneath the pointer. |
|
|
87
|
-
| `morphFrom` | none | An element ref or getter. The surface grows out of that shape when it mounts, and shrinks back into it when a Base UI popup closes. |
|
|
88
|
-
| `morph` | by context | `"become"`: the source's glass is this surface, and its content withdraws while the surface is present. `"detach"`: the surface leaves the source's glass as a drop, joined by a liquid neck until they part. By default a glass source is become and a source inside glass, such as a toolbar button, is detached from. |
|
|
89
|
-
| `fluid` | `false` | Spring the glass outline when the surface's layout box changes. |
|
|
90
|
-
| `motion` | inherited | `"full"`, `"reduced"`, or `"none"`. Set it on `GlassScene` to apply it to every component. |
|
|
91
|
-
|
|
92
|
-
`GlassButton`, toolbars, and tab bars are interactive by default; pass
|
|
93
|
-
`interactive={false}` to keep one still. `GlassSurface` and menus are not,
|
|
94
|
-
because large surfaces usually hold content rather than act as a control. Menu
|
|
95
|
-
and submenu content always grows out of its trigger, and toolbar groups are
|
|
96
|
-
fluid.
|
|
55
|
+
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](https://liquid-glass.glassapp.dev/#examples) for usage and the [Base UI reference](https://base-ui.com/react/overview/quick-start) for inherited props.
|
|
97
56
|
|
|
98
|
-
|
|
99
|
-
// A draggable card that stretches with its own velocity.
|
|
100
|
-
<GlassSurface interactive radius={28} style={{ padding: 20 }}>…</GlassSurface>
|
|
101
|
-
|
|
102
|
-
// A custom popover that grows out of its trigger, using Base UI Popover.
|
|
103
|
-
// Portal popups into the scene so they refract the same content.
|
|
104
|
-
const scene = useRef<HTMLDivElement>(null);
|
|
105
|
-
const trigger = useRef<HTMLButtonElement>(null);
|
|
106
|
-
<GlassScene ref={scene}>
|
|
107
|
-
<GlassContent>…</GlassContent>
|
|
108
|
-
<Popover.Root>
|
|
109
|
-
<Popover.Trigger ref={trigger} render={<GlassButton />}>Share</Popover.Trigger>
|
|
110
|
-
<Popover.Portal container={scene}>
|
|
111
|
-
<Popover.Positioner sideOffset={8}>
|
|
112
|
-
<GlassSurface morphFrom={trigger} material="regular" radius={24}
|
|
113
|
-
render={<Popover.Popup />}>…</GlassSurface>
|
|
114
|
-
</Popover.Positioner>
|
|
115
|
-
</Popover.Portal>
|
|
116
|
-
</Popover.Root>
|
|
117
|
-
</GlassScene>
|
|
118
|
-
```
|
|
57
|
+
## Material and motion
|
|
119
58
|
|
|
120
|
-
|
|
121
|
-
scaled with it, condensing out of a blur once the outline has room for it, and
|
|
122
|
-
dissolving again as it closes. The glass itself never jumps between shapes:
|
|
123
|
-
the maps for the path are prepared as it is planned, and every frame blends
|
|
124
|
-
the two nearest. Exit animations work with any Base UI popup: the surface
|
|
125
|
-
keeps the popup mounted until the glass is back inside its source.
|
|
59
|
+
Set defaults on `GlassScene`; individual surfaces can override them. Menu popups default to Regular.
|
|
126
60
|
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
61
|
+
| Prop | Default | Usage |
|
|
62
|
+
| --- | --- | --- |
|
|
63
|
+
| `material` | `"clear"` | `"clear"` or `"regular"`. |
|
|
64
|
+
| `appearance` | `"light"` | `"light"` or `"dark"`. |
|
|
65
|
+
| `radius` | Component-specific | Continuous corner radius in CSS pixels, `"capsule"`, or `"circle"`. Generic surfaces default to 8px. |
|
|
66
|
+
| `refraction` | `60` | Nonnegative displacement in CSS pixels. Nested surfaces limit their default to the parent inset. |
|
|
67
|
+
| `tint` | None | Six-digit hex color. Colors the glass without changing text or icons. |
|
|
68
|
+
| `interactive` | Component-specific | Press and drag feedback; on by default for buttons, toolbars, and tab bars. |
|
|
69
|
+
| `fluid` | `false` | Animate the outline when layout dimensions change. |
|
|
70
|
+
| `morphFrom` | None | Element ref or getter for a surface's opening and closing shape. |
|
|
71
|
+
| `morph` | By context | `"become"` replaces its source; `"detach"` separates from it. |
|
|
72
|
+
| `motion` | `"full"` | `"full"`, `"reduced"`, or `"none"`; inherited from the scene. |
|
|
131
73
|
|
|
132
|
-
|
|
74
|
+
Slider and switch pressed thumbs default to Clear, with refraction of 5px and 7.75px respectively. Their `tint` sets the track color.
|
|
75
|
+
|
|
76
|
+
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.
|
|
133
77
|
|
|
134
|
-
|
|
135
|
-
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
|
|
136
|
-
| `GlassScene` | Owns content, surface registration, and filter composition. |
|
|
137
|
-
| `GlassContent` | The single live content layer to refract. |
|
|
138
|
-
| `GlassSurface` | A material surface, or a wrapper around your own component using `render`. |
|
|
139
|
-
| `GlassButton` | A semantic Base UI button with glass and focus/press behavior. |
|
|
140
|
-
| `GlassToolbar`, `GlassToolbarButton`, `GlassToolbarSpacer` | Toolbar with keyboard navigation, composable controls, and fixed or flexible spacing. |
|
|
141
|
-
| `GlassTabs` | Tabs with automatic selection, keyboard navigation, and a moving glass indicator. |
|
|
142
|
-
| `GlassMenu`, `GlassMenuTrigger`, `GlassMenuContent`, `GlassMenuItem` | Base UI menu primitives with a glass popup, keyboard navigation, and focus restoration. |
|
|
78
|
+
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.
|
|
143
79
|
|
|
144
|
-
|
|
80
|
+
## Composing controls
|
|
81
|
+
|
|
82
|
+
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.
|
|
145
83
|
|
|
146
84
|
```tsx
|
|
147
|
-
<GlassSurface material="clear"
|
|
85
|
+
<GlassSurface material="clear" render={<Button onClick={save} />}>
|
|
148
86
|
Save
|
|
149
87
|
</GlassSurface>
|
|
88
|
+
```
|
|
150
89
|
|
|
151
|
-
|
|
152
|
-
items={[{ value: 'home', label: 'Home' }, { value: 'library', label: 'Library' }]}
|
|
153
|
-
aria-label="Navigation" />
|
|
90
|
+
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.
|
|
154
91
|
|
|
92
|
+
```tsx
|
|
155
93
|
<GlassMenu>
|
|
156
|
-
<
|
|
157
|
-
<GlassMenuContent
|
|
94
|
+
<GlassMenuTrigger render={<GlassButton />}>Options</GlassMenuTrigger>
|
|
95
|
+
<GlassMenuContent>
|
|
158
96
|
<GlassMenuItem onClick={save}>Save</GlassMenuItem>
|
|
97
|
+
<GlassMenuSubmenu>
|
|
98
|
+
<GlassMenuSubmenuTrigger>Share</GlassMenuSubmenuTrigger>
|
|
99
|
+
<GlassMenuSubmenuContent>
|
|
100
|
+
<GlassMenuItem onClick={copyLink}>Copy link</GlassMenuItem>
|
|
101
|
+
</GlassMenuSubmenuContent>
|
|
102
|
+
</GlassMenuSubmenu>
|
|
159
103
|
</GlassMenuContent>
|
|
160
104
|
</GlassMenu>
|
|
161
105
|
```
|
|
162
106
|
|
|
163
|
-
`
|
|
107
|
+
`GlassMenuGroup`, `GlassMenuGroupLabel`, `GlassMenuSeparator`, `GlassMenuCheckboxItem`, `GlassMenuRadioGroup`, and `GlassMenuRadioItem` expose the corresponding Base UI parts.
|
|
164
108
|
|
|
165
|
-
|
|
166
|
-
`GlassForeground`. It adds no material or GPU maps. Slider and switch components
|
|
167
|
-
register their tracks and solid thumbs automatically; glass surfaces already
|
|
168
|
-
participate. Keep the foreground and the menus that overlap it in the same scene.
|
|
109
|
+
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.
|
|
169
110
|
|
|
170
|
-
|
|
171
|
-
<GlassForeground render={<div className="floating-content" />}>
|
|
172
|
-
Text and controls that should refract beneath a glass menu
|
|
173
|
-
</GlassForeground>
|
|
174
|
-
```
|
|
175
|
-
|
|
176
|
-
For an existing component ref, use `useGlassForeground()`; the DOM controller
|
|
177
|
-
provides `scene.addForeground(element)` and returns a cleanup function.
|
|
111
|
+
## Tabs, sliders, and switches
|
|
178
112
|
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
113
|
+
```tsx
|
|
114
|
+
<GlassTabs aria-label="Navigation" defaultValue="home"
|
|
115
|
+
items={[{ value: "home", label: "Home" }, { value: "library", label: "Library" }]} />
|
|
182
116
|
|
|
183
|
-
|
|
117
|
+
<GlassSlider aria-label="Volume" defaultValue={50}
|
|
118
|
+
onValueCommitted={(value) => console.log(value)} />
|
|
119
|
+
<GlassSlider ticks aria-label="Intensity" min={0} max={100} step={25} />
|
|
120
|
+
<label>Notifications <GlassSwitch name="notifications" defaultChecked /></label>
|
|
121
|
+
```
|
|
184
122
|
|
|
185
|
-
`
|
|
186
|
-
vertical layouts, or application-controlled state, compose the same parts:
|
|
123
|
+
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:
|
|
187
124
|
|
|
188
125
|
```tsx
|
|
189
|
-
// Inside a GlassScene with a GlassContent layer:
|
|
190
126
|
<GlassTabsRoot defaultValue="preview">
|
|
191
|
-
<GlassTabsList aria-label="
|
|
127
|
+
<GlassTabsList aria-label="View">
|
|
192
128
|
<GlassTabsIndicator />
|
|
193
129
|
<GlassTabsTrigger value="preview">Preview</GlassTabsTrigger>
|
|
194
|
-
<GlassTabsTrigger value="usage">
|
|
130
|
+
<GlassTabsTrigger value="usage">Usage</GlassTabsTrigger>
|
|
195
131
|
</GlassTabsList>
|
|
196
132
|
<GlassTabsContent value="preview">Your preview</GlassTabsContent>
|
|
197
133
|
<GlassTabsContent value="usage">Your usage code</GlassTabsContent>
|
|
198
134
|
</GlassTabsRoot>
|
|
199
135
|
```
|
|
200
136
|
|
|
201
|
-
|
|
202
|
-
indicator, and panel preserve Base UI's native props, refs, and state callbacks.
|
|
203
|
-
The list adds material props and `size="sm"` or `size="lg"`. It can also sit inside an existing
|
|
204
|
-
Base UI/shadcn `Tabs` root; keep its `TabsContent` panels. Do not nest a second
|
|
205
|
-
root around the list. Use simple text/icons as tab labels, not interactive children.
|
|
137
|
+
The list also works within an existing Base UI tabs root; do not nest another root. Keep interactive elements out of tab labels.
|
|
206
138
|
|
|
207
|
-
|
|
139
|
+
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.
|
|
208
140
|
|
|
209
|
-
|
|
210
|
-
containers inside one semantic toolbar. `GlassToolbarSpacer` accepts `sizing="fixed"` for a standard gap or
|
|
211
|
-
`sizing="flexible"` (the default) to fill available space. Give the toolbar a
|
|
212
|
-
width or height when you want a flexible spacer to push controls apart.
|
|
141
|
+
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.
|
|
213
142
|
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
```tsx
|
|
217
|
-
// Inside a GlassScene with a GlassContent layer:
|
|
218
|
-
<GlassToolbar aria-label="Playback" style={{ width: 240 }}>
|
|
219
|
-
<GlassToolbarButton aria-label="Play" onClick={play}>▶</GlassToolbarButton>
|
|
220
|
-
<GlassToolbarButton aria-label="Volume" onClick={volume}>♪</GlassToolbarButton>
|
|
221
|
-
<GlassToolbarSpacer sizing="fixed" />
|
|
222
|
-
<GlassToolbarButton aria-label="Favorite">♡</GlassToolbarButton>
|
|
223
|
-
<GlassToolbarSpacer />
|
|
224
|
-
<GlassMenu>
|
|
225
|
-
<GlassToolbarButton aria-label="Playback options" render={<GlassMenuTrigger />}>
|
|
226
|
-
⋯
|
|
227
|
-
</GlassToolbarButton>
|
|
228
|
-
<GlassMenuContent>
|
|
229
|
-
<GlassMenuItem onClick={save}>Save to library</GlassMenuItem>
|
|
230
|
-
<GlassMenuItem onClick={share}>Share</GlassMenuItem>
|
|
231
|
-
</GlassMenuContent>
|
|
232
|
-
</GlassMenu>
|
|
233
|
-
</GlassToolbar>
|
|
234
|
-
```
|
|
143
|
+
## Progressive blur
|
|
235
144
|
|
|
236
|
-
|
|
237
|
-
participates in the toolbar's arrow-key navigation. Enter, Space, or the menu
|
|
238
|
-
opening arrow opens the menu; Escape closes it and restores trigger focus.
|
|
239
|
-
Menu state and callbacks stay on `GlassMenu`; positioning and material stay on
|
|
240
|
-
`GlassMenuContent`. Trigger-specific props can go on `GlassMenuTrigger`.
|
|
241
|
-
|
|
242
|
-
Spacers are decorative, never receive keyboard focus, and follow
|
|
243
|
-
`orientation="vertical"` automatically. The standard basis is 8px, in addition
|
|
244
|
-
to the toolbar's normal item gap. Override `--lg-toolbar-space` on the toolbar
|
|
245
|
-
or a spacer to change it. Each spacer ends the preceding glass container and
|
|
246
|
-
starts another after an uncovered gap. Place spacers as toolbar children;
|
|
247
|
-
arrays and fragments are supported. The example above creates three containers:
|
|
248
|
-
Play/Volume, Favorite, and the menu trigger. They share one keyboard navigation
|
|
249
|
-
scope. Material and radius apply to every container; layout styles apply to
|
|
250
|
-
the toolbar as a whole.
|
|
251
|
-
|
|
252
|
-
## Defaults and customization
|
|
253
|
-
|
|
254
|
-
Import the SDK stylesheet once. It requires neither Tailwind nor a CSS reset.
|
|
255
|
-
Controls use compact defaults: `GlassButton` is 28px high with 8px horizontal
|
|
256
|
-
padding, 12px text, 500 weight, and a 4px gap. Button sizes `xs`, `sm`, and `lg`
|
|
257
|
-
are 20px, 24px, and 32px; the corresponding icon sizes are square. Toolbar
|
|
258
|
-
buttons default to 22px square inside a 3px inset, making the toolbar 28px high.
|
|
259
|
-
Use `size="default"` on `GlassToolbarButton` for text controls that fit their labels. Default tab bars are 32px high,
|
|
260
|
-
`sm` bars 28px, and `lg` bars 36px; tab labels retain weight 500 when selected.
|
|
261
|
-
Menus use a 4px inset, 128px minimum width, and 28px minimum-height rows.
|
|
262
|
-
Surfaces have no imposed width or height: application content sets their bounds.
|
|
263
|
-
Generic surface radius defaults to 8px. Buttons, toolbars, tab lists, and
|
|
264
|
-
indicators default to `radius="capsule"`; icon buttons use `"circle"`, and menu popups use 28px continuous corners.
|
|
265
|
-
Explicit material options can override them.
|
|
266
|
-
|
|
267
|
-
`GlassTabsIndicator` is the tab bar's selection lens, including when composed
|
|
268
|
-
with an existing Base UI tabs root. It springs between tabs, lifts and swells
|
|
269
|
-
under a press, stretches with its speed while dragged, and selects the tab it is
|
|
270
|
-
released over. Selection still belongs to the tabs: the lens activates a tab
|
|
271
|
-
exactly as a click would, so keyboard navigation and controlled state are
|
|
272
|
-
unchanged. `GlassTabs` uses the same part.
|
|
273
|
-
Material and appearance inherit from the scene; menus default to Regular.
|
|
274
|
-
|
|
275
|
-
The shipped CSS uses low-specificity `:where()` selectors. Override defaults with
|
|
276
|
-
`className`, inline styles, or your Tailwind utilities. For a custom radius, use
|
|
277
|
-
`radius` so the Lisse outline, content clip, and GPU optical field agree. Existing shadcn controls
|
|
278
|
-
keep their own styling; use a transparent background variant so their fill does
|
|
279
|
-
not hide the refracted layer.
|
|
280
|
-
|
|
281
|
-
`GlassSurface` uses Base UI `useRender`: element composition merges handlers,
|
|
282
|
-
classes, styles, and refs. Both the surface ref and rendered component ref are
|
|
283
|
-
preserved, including React 19 ref cleanup. A render function receives merged
|
|
284
|
-
props and must spread them onto its element. Custom components must forward
|
|
285
|
-
those props and the ref. `GlassButton` also accepts Base UI's `render` prop.
|
|
286
|
-
|
|
287
|
-
`GlassMenuContent` accepts `side` (`top`, `bottom`, `left`, `right`,
|
|
288
|
-
`inline-start`, or `inline-end`), `align` (`start`, `center`, or `end`),
|
|
289
|
-
`sideOffset`, `alignOffset`, and `collisionAvoidance` directly. Defaults are
|
|
290
|
-
`side="bottom"`, `align="end"`, and `sideOffset={8}`. Alignment works on all
|
|
291
|
-
sides. Base UI can flip or shift the popup to avoid viewport collisions.
|
|
292
|
-
Advanced `positionerProps` remain supported; direct positioning props take
|
|
293
|
-
precedence. `portalProps` accepts options such as `keepMounted`. The portal
|
|
294
|
-
stays inside the scene because its live optical source belongs there.
|
|
295
|
-
|
|
296
|
-
Compose submenus using Base UI behavior and the same glass content:
|
|
145
|
+
`GlassProgressiveBlur` softens `GlassContent` at an edge. Put captions and controls outside that content layer to keep them sharp.
|
|
297
146
|
|
|
298
147
|
```tsx
|
|
299
|
-
<
|
|
300
|
-
<
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
</GlassMenuSubmenuContent>
|
|
307
|
-
</GlassMenuSubmenu>
|
|
308
|
-
</GlassMenuContent>
|
|
148
|
+
<GlassScene style={{ height: 320, overflow: "hidden" }}>
|
|
149
|
+
<GlassContent>
|
|
150
|
+
<img src="/landscape.jpg" alt="Mountain lake"
|
|
151
|
+
style={{ width: "100%", height: "100%", objectFit: "cover" }} />
|
|
152
|
+
</GlassContent>
|
|
153
|
+
<GlassProgressiveBlur edge="bottom" size={80} blur={20} />
|
|
154
|
+
</GlassScene>
|
|
309
155
|
```
|
|
310
156
|
|
|
311
|
-
|
|
312
|
-
`GlassMenuSubmenuContent` from the package root. Submenu content accepts the
|
|
313
|
-
same props as root content, defaulting to `side="inline-end"` and
|
|
314
|
-
`align="start"`. Nest these parts again for additional levels. Base UI owns
|
|
315
|
-
hover timing, arrow-key navigation, disabled items, and focus restoration.
|
|
316
|
-
There is no submenu enable flag: include the submenu parts when needed.
|
|
317
|
-
The same API works for a menu composed inside `GlassToolbar`; the toolbar
|
|
318
|
-
requires no separate submenu or positioning implementation.
|
|
319
|
-
|
|
320
|
-
Group, group label, separator, checkbox item, radio group, and radio item
|
|
321
|
-
exports use Base UI; add indicators for checked items as your application
|
|
322
|
-
requires. See the [Base UI menu reference](https://base-ui.com/react/components/menu)
|
|
323
|
-
for inherited props and event details.
|
|
324
|
-
|
|
325
|
-
Use `GlassToolbarButton`, `GlassToolbarLink`, and `GlassToolbarGroup` inside
|
|
326
|
-
`GlassToolbar` to participate in Base UI keyboard navigation. Toolbar buttons
|
|
327
|
-
use the same light/dark highlight as menu items on hover, keyboard focus, and
|
|
328
|
-
press. Use `aria-pressed` for toggle controls. Their highlights use circular icon buttons and continuous capsules for text buttons. Standalone `GlassButton` styling is independent.
|
|
329
|
-
|
|
330
|
-
## Sliders and switches
|
|
157
|
+
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:
|
|
331
158
|
|
|
332
159
|
```tsx
|
|
333
|
-
|
|
160
|
+
const viewport = useRef<HTMLDivElement>(null);
|
|
334
161
|
|
|
335
|
-
|
|
336
|
-
<
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
<
|
|
162
|
+
<GlassScene style={{ height: 320, overflow: "hidden" }}>
|
|
163
|
+
<GlassContent layout="scroll" ref={viewport} tabIndex={0} role="region"
|
|
164
|
+
aria-label="Reading list" style={{ scrollPaddingBlock: 80 }}>
|
|
165
|
+
{children}
|
|
166
|
+
</GlassContent>
|
|
167
|
+
<GlassScrollEdges target={viewport} size={80} blur={20} />
|
|
168
|
+
</GlassScene>
|
|
341
169
|
```
|
|
342
170
|
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
`
|
|
352
|
-
`defaultChecked`, `onCheckedChange`, `readOnly`, `required`, `name`,
|
|
353
|
-
`value`, `uncheckedValue` and `inputRef`. Name it with a wrapping label or
|
|
354
|
-
`aria-label`. `tint` sets the active track color on both controls; the thumbs
|
|
355
|
-
are solid white at rest. Pressing grows the thumb and reveals its glass lens,
|
|
356
|
-
which stretches with its speed while dragged; the switch thumb can be dragged
|
|
357
|
-
to either side and settles on release.
|
|
358
|
-
The pressed thumb defaults to clear glass; appearance inherits from the scene.
|
|
359
|
-
Refraction defaults to 5px for sliders and 7.75px for switches. Keyboard behavior, forms
|
|
360
|
-
and RTL come from Base UI. Both accept `motion` and `interactive`; reduced motion
|
|
361
|
-
disables thumb transitions.
|
|
362
|
-
|
|
363
|
-
## Content shapes
|
|
364
|
-
|
|
365
|
-
Use `GlassShape` for images, cards, and content that needs continuous corners without a glass material. It uses Lisse and supports `radius` and `render` composition without requiring a `GlassScene`.
|
|
366
|
-
|
|
367
|
-
```tsx
|
|
368
|
-
import { GlassShape } from "@glass-sdk/liquid-glass";
|
|
171
|
+
| Prop | Default | Usage |
|
|
172
|
+
| --- | --- | --- |
|
|
173
|
+
| `edge` | `"bottom"` | Primitive edge: `top`, `bottom`, `inline-start`, or `inline-end`. |
|
|
174
|
+
| `edges` | `["top", "bottom"]` | Scroll helper edges. Logical edges follow direction. |
|
|
175
|
+
| `target` | Required on scroll helper | Ref to the scrolling viewport. |
|
|
176
|
+
| `size` | `80` | Edge depth in pixels, 0–4096; scroll edges clamp to half the viewport. |
|
|
177
|
+
| `blur` | `20` | Gaussian standard deviation in pixels, 0–64. |
|
|
178
|
+
| `refraction` | `0` | Optical displacement in pixels, 0–32. |
|
|
179
|
+
| `disabled` | `false` | Remove the effect. |
|
|
369
180
|
|
|
370
|
-
|
|
371
|
-
<GlassShape radius="capsule" style={{ padding: "6px 14px" }}>Label</GlassShape>
|
|
372
|
-
```
|
|
181
|
+
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.
|
|
373
182
|
|
|
374
|
-
|
|
183
|
+
## Content shapes and foregrounds
|
|
375
184
|
|
|
376
|
-
|
|
185
|
+
`GlassShape` clips images and content to continuous corners without needing a scene:
|
|
377
186
|
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
| `tint` | none | Optional six-digit hex tint, e.g. `#a8b8ff`. |
|
|
187
|
+
```tsx
|
|
188
|
+
<GlassShape radius={28} render={<img src="/cover.jpg" alt="Album cover" />} />
|
|
189
|
+
<GlassShape radius={40} style={{ padding: 4 }}>
|
|
190
|
+
<GlassShape concentric={{ inset: 4 }} radius={8}>Nested content</GlassShape>
|
|
191
|
+
</GlassShape>
|
|
192
|
+
```
|
|
385
193
|
|
|
386
|
-
Both
|
|
387
|
-
`--lg-foreground` to customize text and icons. Clear preserves backdrop detail
|
|
388
|
-
with a compressed tonal range; Regular adds frosting. Nested surfaces limit
|
|
389
|
-
default refraction to their inset inside the parent, preventing a second lens
|
|
390
|
-
from pulling the parent's edge into its interior. An explicit `refraction`
|
|
391
|
-
overrides that limit. Tabs keep label weight stable while the selection lens moves.
|
|
194
|
+
`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.
|
|
392
195
|
|
|
393
|
-
|
|
196
|
+
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.
|
|
394
197
|
|
|
395
198
|
## Without React
|
|
396
199
|
|
|
@@ -398,200 +201,36 @@ overrides that limit. Tabs keep label weight stable while the selection lens mov
|
|
|
398
201
|
import { createGlassScene } from "@glass-sdk/liquid-glass/dom";
|
|
399
202
|
import "@glass-sdk/liquid-glass/styles.css";
|
|
400
203
|
|
|
401
|
-
const scene = createGlassScene(document.querySelector(".lg-scene")!);
|
|
402
|
-
scene.setContent(document.querySelector(".lg-content")!);
|
|
403
|
-
const remove = scene.addSurface(document.querySelector(".lg-surface")!, {
|
|
404
|
-
material: "regular",
|
|
405
|
-
radius: 32,
|
|
406
|
-
interactive: true,
|
|
204
|
+
const scene = createGlassScene(document.querySelector<HTMLElement>(".lg-scene")!);
|
|
205
|
+
scene.setContent(document.querySelector<HTMLElement>(".lg-content")!);
|
|
206
|
+
const remove = scene.addSurface(document.querySelector<HTMLElement>(".lg-surface")!, {
|
|
207
|
+
material: "regular", radius: 28,
|
|
407
208
|
});
|
|
209
|
+
|
|
408
210
|
// On teardown:
|
|
409
211
|
remove();
|
|
410
212
|
scene.dispose();
|
|
411
213
|
```
|
|
412
214
|
|
|
413
|
-
Use the
|
|
215
|
+
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.
|
|
414
216
|
|
|
415
|
-
`
|
|
416
|
-
`scene.addAnimator(animator)` steps your own animation each frame before the
|
|
417
|
-
scene measures glass, so geometry you write is refracted in the same frame.
|
|
418
|
-
`attachInteraction`, `attachGeometryMotion`, and `attachSelectionLens` are the
|
|
419
|
-
animators the components use. `/core` exports `Spring`, the shared `springs`,
|
|
420
|
-
and `rubberBand`.
|
|
217
|
+
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.
|
|
421
218
|
|
|
422
|
-
|
|
219
|
+
The `/core`, `/gpu`, and `/dom` exports provide geometry, materials, rendering, and controller APIs for custom integrations. Type declarations describe their options.
|
|
423
220
|
|
|
424
|
-
|
|
221
|
+
## Requirements and limitations
|
|
425
222
|
|
|
426
|
-
|
|
223
|
+
- React 19+ for React components; HTTPS or localhost and an available WebGPU adapter to render glass material maps. Progressive blur needs no WebGPU.
|
|
224
|
+
- 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.
|
|
225
|
+
- For consistent refraction in Safari, give `GlassContent` an opaque background. Transparent source pixels can leave the original content visible beneath its refracted image.
|
|
226
|
+
- 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.
|
|
227
|
+
- `GlassScene.maxSurfaces` defaults to 16 and accepts at most 64. Use `onDiagnostic` for map readiness, construction timing, filter graph limits, and GPU errors.
|
|
228
|
+
- NodeNext TypeScript consumers currently need `skipLibCheck: true` for upstream vgpu declarations.
|
|
427
229
|
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
Glass scenes allow controls and menus to extend beyond their layout bounds. Refraction repeats the nearest backdrop edge when sampling outside the supplied content. Clip images or other backdrop children when needed; clipping the scene itself also clips its controls and popups.
|
|
431
|
-
|
|
432
|
-
Use bounded scenes. Pixel density is capped at 2, and each atlas plane is limited to 4096 × 2048 pixels. `maxSurfaces` defaults to 16 and accepts at most 64.
|
|
433
|
-
|
|
434
|
-
## Requirements
|
|
435
|
-
|
|
436
|
-
React 19+ is required for the React components. WebGPU requires an available adapter and HTTPS or localhost. Unsupported adapters report an error.
|
|
437
|
-
|
|
438
|
-
The content layer supports live text, SVG, and images. Arbitrary page-backdrop sampling, native video composition, transformed ancestors, and native/React Native ports are outside the supported scope. Cross-origin image/filter policies still apply. For NodeNext TypeScript projects, use `skipLibCheck: true` for the current upstream vgpu declarations.
|
|
439
|
-
|
|
440
|
-
## Contributing
|
|
441
|
-
|
|
442
|
-
See the [development guide](https://github.com/Glass-HQ/liquid-glass/blob/main/CONTRIBUTING.md) for workspace setup, build commands, and verification.
|
|
443
|
-
|
|
444
|
-
## Accessibility
|
|
445
|
-
|
|
446
|
-
Buttons, tabs, and menus use Base UI keyboard and focus behavior. Space and
|
|
447
|
-
Enter press interactive glass just as a pointer does. Motion is never the only
|
|
448
|
-
feedback: pressed, selected, and open states keep their highlight, and the
|
|
449
|
-
system reduced-motion setting removes elasticity and travel.
|
|
450
|
-
|
|
451
|
-
## License
|
|
452
|
-
|
|
453
|
-
[MIT](./LICENSE).
|
|
454
|
-
|
|
455
|
-
## Progressive blur
|
|
456
|
-
|
|
457
|
-
Soften live content progressively at an edge. Put the content to be blurred in
|
|
458
|
-
`GlassContent`; place captions and controls beside it to keep them sharp.
|
|
459
|
-
|
|
460
|
-
```tsx
|
|
461
|
-
import { GlassScene, GlassContent, GlassProgressiveBlur } from "@glass-sdk/liquid-glass";
|
|
462
|
-
import "@glass-sdk/liquid-glass/styles.css";
|
|
463
|
-
|
|
464
|
-
<GlassScene style={{ height: 360, overflow: "hidden", borderRadius: 16 }}>
|
|
465
|
-
<GlassContent>
|
|
466
|
-
<img src="/landscape.jpg" alt="Mountain lake"
|
|
467
|
-
style={{ width: "100%", height: "100%", objectFit: "cover" }} />
|
|
468
|
-
</GlassContent>
|
|
469
|
-
<GlassProgressiveBlur edge="bottom" size={140} blur={24} />
|
|
470
|
-
<p style={{ position: "absolute", bottom: 24, left: 24 }}>A quieter place.</p>
|
|
471
|
-
</GlassScene>
|
|
472
|
-
```
|
|
473
|
-
|
|
474
|
-
For a scroll container, `GlassScrollEdges` filters only the target scrollport. The blur stays anchored while its content scrolls, including during fast native scrolling. It does
|
|
475
|
-
not create scrollbars or change wheel, touch, or keyboard scrolling.
|
|
476
|
-
|
|
477
|
-
```tsx
|
|
478
|
-
import { useRef, type ReactNode } from "react";
|
|
479
|
-
import { GlassScene, GlassContent, GlassScrollEdges } from "@glass-sdk/liquid-glass";
|
|
480
|
-
|
|
481
|
-
function ReadingList({ children }: { children: ReactNode }) {
|
|
482
|
-
const viewport = useRef<HTMLDivElement>(null);
|
|
483
|
-
return (
|
|
484
|
-
<GlassScene style={{ height: 360, overflow: "hidden" }}>
|
|
485
|
-
<div ref={viewport} tabIndex={0} role="region" aria-label="Reading list"
|
|
486
|
-
style={{ height: "100%", overflow: "auto", scrollPaddingBlock: 80 }}>
|
|
487
|
-
<GlassContent layout="flow">{children}</GlassContent>
|
|
488
|
-
</div>
|
|
489
|
-
<GlassScrollEdges target={viewport} size={80} blur={20} />
|
|
490
|
-
</GlassScene>
|
|
491
|
-
);
|
|
492
|
-
}
|
|
493
|
-
```
|
|
494
|
-
|
|
495
|
-
Give the target an explicit height and `overflow: "auto"` or `"scroll"`. No extra filter wrapper is required: the SDK never applies the scroll-edge filter to the target's parent. Floating headers, footers, and navigation must be siblings outside the target to remain sharp. To refract the already-blurred content through a floating glass surface, put the scrollport inside a stationary `GlassContent` layer and the surface alongside that layer in the same `GlassScene`. Place headers and footers inside the target only when they should scroll and blur with its content. With a third-party ScrollArea,
|
|
496
|
-
pass a ref to its actual scrolling viewport. Use `edges={["inline-start",
|
|
497
|
-
"inline-end"]}` for a horizontal gallery; logical edges follow `direction` in
|
|
498
|
-
horizontal writing modes. `GlassContent layout="flow"` participates in normal
|
|
499
|
-
layout; the default `overlay` layout fills the scene for image backdrops.
|
|
500
|
-
|
|
501
|
-
| Prop | Default | Meaning |
|
|
502
|
-
| --- | --- | --- |
|
|
503
|
-
| `edge` | `"bottom"` | Primitive's strongest edge: `top`, `bottom`, `inline-start`, `inline-end`. |
|
|
504
|
-
| `edges` | `["top", "bottom"]` | Scroll helper's edges. Duplicate entries are ignored. |
|
|
505
|
-
| `target` | Required on scroll helper | An element ref to the scroll viewport. |
|
|
506
|
-
| `size` | `80` | Depth in CSS pixels, from 0 to 4096. Scroll edges clamp to half the viewport. |
|
|
507
|
-
| `blur` | `20` | Maximum Gaussian standard deviation in CSS pixels, from 0 to 64. |
|
|
508
|
-
| `refraction` | `0` | Optional optical travel in CSS pixels, from 0 to 32. |
|
|
509
|
-
| `disabled` | `false` | Remove the effect without changing the content. |
|
|
510
|
-
|
|
511
|
-
The primitive accepts standard div styling and refs, but no children. Size sets
|
|
512
|
-
its default depth; CSS can override the region's geometry. The helper renders no
|
|
513
|
-
element. A scene supports up to 64 progressive regions. Opposite scroll edges do
|
|
514
|
-
not overlap; perpendicular or custom overlapping regions compose in registration
|
|
515
|
-
order, so their blur can accumulate.
|
|
516
|
-
|
|
517
|
-
Reached scroll edges clear smoothly over the nearest 32 pixels (or the edge depth
|
|
518
|
-
when smaller). No overflow means no blur. Native content remains selectable and
|
|
519
|
-
accessible. Set scroll padding on your scroll viewport so keyboard-focused items
|
|
520
|
-
can be brought into its clear center. The effect disables itself for reduced
|
|
521
|
-
transparency and forced colors. When WebGPU cannot prepare maps, content stays
|
|
522
|
-
readable and `GlassScene.onDiagnostic` receives the error.
|
|
523
|
-
|
|
524
|
-
This is a smooth, seven-level approximation of spatially varying Gaussian blur,
|
|
525
|
-
using WGSL-generated weights and ordinary SVG filters on the explicit DOM layer.
|
|
526
|
-
It does not capture DOM into a texture. Content outside `GlassContent`, including
|
|
527
|
-
unrelated page layers, is not sampled. Keep fixed/sticky foreground controls outside
|
|
528
|
-
that filtered layer; filtering creates a containing block for positioned descendants.
|
|
529
|
-
|
|
530
|
-
### Container-relative geometry
|
|
531
|
-
|
|
532
|
-
`GlassSurface` and fixed `GlassShape` elements declare their shape to descendants.
|
|
533
|
-
`GlassShape concentric` follows an inward offset of the nearest declared container
|
|
534
|
-
at the child's actual position. When `inset` is omitted, the smallest measured
|
|
535
|
-
edge inset is used, so changing container padding updates the relationship. Its `radius` controls the child's independent
|
|
536
|
-
corners where they do not meet the container boundary. Menu items and tab interaction
|
|
537
|
-
backgrounds use this automatically; first, middle, and last menu rows do not share
|
|
538
|
-
one hard-coded corner radius. Menu content clearance is shared across rows to keep
|
|
539
|
-
icons and labels aligned.
|
|
540
|
-
|
|
541
|
-
```tsx
|
|
542
|
-
<GlassShape radius={40} style={{ padding: 4 }}>
|
|
543
|
-
<GlassShape concentric={{ inset: 4, contentPadding: 8 }} radius={8}>
|
|
544
|
-
Container-relative content
|
|
545
|
-
</GlassShape>
|
|
546
|
-
</GlassShape>
|
|
547
|
-
```
|
|
548
|
-
|
|
549
|
-
Use `GlassShapeContainer` to declare geometry without clipping a layout containing
|
|
550
|
-
both content and overlays. Use `GlassCorner` for fixed-size controls near curved
|
|
551
|
-
corners. It positions the entire control with the requested clearance; it does not
|
|
552
|
-
change a circular control into a rounded rectangle.
|
|
230
|
+
## How it works
|
|
553
231
|
|
|
554
|
-
|
|
555
|
-
<GlassShapeContainer radius={48} style={{ position: "relative", height: 320 }}>
|
|
556
|
-
<GlassCorner corner="top-right" gap={12} radius="circle">
|
|
557
|
-
<GlassShape radius="circle" render={<button aria-label="More" style={{ width: 32, height: 32 }} />}>…</GlassShape>
|
|
558
|
-
</GlassCorner>
|
|
559
|
-
</GlassShapeContainer>
|
|
560
|
-
```
|
|
232
|
+
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.
|
|
561
233
|
|
|
562
|
-
|
|
563
|
-
siblings or portals. Without that prop they use the nearest declared DOM ancestor.
|
|
564
|
-
The container must exist and have measurable dimensions. `GlassCorner` supports
|
|
565
|
-
`top-left`, `top-right`, `bottom-left`, and `bottom-right`; `enabled={false}` releases
|
|
566
|
-
its positioning. Its control must fit inside the container at the requested gap.
|
|
567
|
-
Layout tracks resizing, scrolling, and axis-aligned translation/scaling. Rotated
|
|
568
|
-
containers are not supported. Ordinary children retain their authored layout;
|
|
569
|
-
container declarations do not silently reposition unrelated content.
|
|
570
|
-
|
|
571
|
-
The `./dom` entry exports `registerShapeContainer`, `observeConcentricShape`, and
|
|
572
|
-
`observeCornerPlacement` for non-React integrations. Each returns a cleanup function.
|
|
573
|
-
Observers accept an optional container getter. The `./core` entry exports the same
|
|
574
|
-
geometry calculations (`insetShape`, `concentricOutline`, `cornerPlacement`) for
|
|
575
|
-
custom layout integrations. The inset is computed from a tessellated Lisse outline,
|
|
576
|
-
with the same corner smoothing used by the renderer; it is not radius subtraction.
|
|
577
|
-
|
|
578
|
-
Keep circular controls and intentional expanding thumb animations circular. Slider
|
|
579
|
-
and switch tracks retain their capsule layout; a pressed thumb may intentionally
|
|
580
|
-
grow outside the track. Use container-relative clipping for nested content and
|
|
581
|
-
interaction backgrounds, and corner placement for controls that must keep their
|
|
582
|
-
own shape.
|
|
583
|
-
|
|
584
|
-
`GlassSurface concentric` also resolves the glass material itself against the
|
|
585
|
-
nearest declared container. Its DOM contour, GPU coverage, refraction normals, and
|
|
586
|
-
edge lighting all use the same resolved outline. The selected tab indicator uses
|
|
587
|
-
this mode by default. Plain-DOM consumers can pass `concentric: { inset: 4 }` to
|
|
588
|
-
`controller.addSurface(element, options)`; registered surfaces declare their
|
|
589
|
-
container geometry automatically.
|
|
234
|
+
## Contributing and license
|
|
590
235
|
|
|
591
|
-
|
|
592
|
-
<GlassSurface radius={40} style={{ padding: 4 }}>
|
|
593
|
-
<GlassSurface concentric={{ inset: 4 }} radius={8}>
|
|
594
|
-
Nested glass
|
|
595
|
-
</GlassSurface>
|
|
596
|
-
</GlassSurface>
|
|
597
|
-
```
|
|
236
|
+
See [Contributing](https://github.com/Glass-HQ/liquid-glass/blob/main/CONTRIBUTING.md). Licensed under [MIT](LICENSE).
|