@glass-sdk/liquid-glass 0.0.0-stage → 0.0.1
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/LICENSE +21 -0
- package/README.md +596 -2
- package/dist/concentric-COCiG9DQ.js +179 -0
- package/dist/core.js +9 -0
- package/dist/dom-CKc8vDTR.js +2532 -0
- package/dist/dom.js +2 -0
- package/dist/gpu-Co5Y89mh.js +244 -0
- package/dist/gpu.js +2 -0
- package/dist/index.js +933 -0
- package/dist/map-encoder.worker-DO1drw0Y.js +16 -0
- package/dist/materials-DVPgteZ9.js +234 -0
- package/dist/styles.css +341 -0
- package/dist/styles.d.css.ts +2 -0
- package/dist/types/core/concentric.d.ts +32 -0
- package/dist/types/core/index.d.ts +10 -0
- package/dist/types/core/materials.d.ts +43 -0
- package/dist/types/core/morph-path.d.ts +110 -0
- package/dist/types/core/optics.d.ts +2 -0
- package/dist/types/core/progressive.d.ts +17 -0
- package/dist/types/core/shape.d.ts +16 -0
- package/dist/types/core/spring.d.ts +60 -0
- package/dist/types/core/union.d.ts +20 -0
- package/dist/types/dom/control-motion.d.ts +13 -0
- package/dist/types/dom/filter-bounds.d.ts +30 -0
- package/dist/types/dom/filter-patch.d.ts +9 -0
- package/dist/types/dom/fixed-shape.d.ts +3 -0
- package/dist/types/dom/foreground.d.ts +20 -0
- package/dist/types/dom/index.d.ts +61 -0
- package/dist/types/dom/interaction.d.ts +16 -0
- package/dist/types/dom/map-encoder.d.ts +5 -0
- package/dist/types/dom/map-encoder.worker.d.ts +1 -0
- package/dist/types/dom/map-encoding.d.ts +5 -0
- package/dist/types/dom/map-image.d.ts +14 -0
- package/dist/types/dom/map-store.d.ts +22 -0
- package/dist/types/dom/maps.d.ts +31 -0
- package/dist/types/dom/morph.d.ts +70 -0
- package/dist/types/dom/png.d.ts +7 -0
- package/dist/types/dom/progressive-maps.d.ts +6 -0
- package/dist/types/dom/progressive.d.ts +14 -0
- package/dist/types/dom/selection.d.ts +5 -0
- package/dist/types/dom/shape-layout.d.ts +29 -0
- package/dist/types/dom/ticker.d.ts +36 -0
- package/dist/types/dom/warm.d.ts +14 -0
- package/dist/types/gpu/index.d.ts +48 -0
- package/dist/types/index.d.ts +4 -0
- package/dist/types/react/control-thumb.d.ts +11 -0
- package/dist/types/react/index.d.ts +155 -0
- package/dist/types/react/merged-ref.d.ts +3 -0
- package/dist/types/react/shape.d.ts +23 -0
- package/dist/types/react/value-control-motion.d.ts +9 -0
- package/dist/types/react/value-controls.d.ts +20 -0
- package/package.json +80 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Glass HQ
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,597 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Liquid Glass
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Clear and Regular glass materials for React, the web, and Electron. Built by [Glass](https://github.com/Glass-HQ) with **vgpu and WGSL**. MIT licensed.
|
|
4
|
+
|
|
5
|
+
[Interactive examples](https://liquid-glass.glassapp.dev/#examples)
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
bun add @glass-sdk/liquid-glass@~0.0.1
|
|
11
|
+
# npm install @glass-sdk/liquid-glass@~0.0.1
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
The `~0.0.1` range accepts subsequent `0.0.x` patch releases.
|
|
15
|
+
|
|
16
|
+
## Quick start
|
|
17
|
+
|
|
18
|
+
```tsx
|
|
19
|
+
import {
|
|
20
|
+
GlassScene,
|
|
21
|
+
GlassContent,
|
|
22
|
+
GlassSurface,
|
|
23
|
+
GlassButton,
|
|
24
|
+
} from "@glass-sdk/liquid-glass";
|
|
25
|
+
import "@glass-sdk/liquid-glass/styles.css";
|
|
26
|
+
|
|
27
|
+
export function Example() {
|
|
28
|
+
return (
|
|
29
|
+
<GlassScene style={{ height: 400 }}>
|
|
30
|
+
<GlassContent>
|
|
31
|
+
<div
|
|
32
|
+
style={{
|
|
33
|
+
height: "100%",
|
|
34
|
+
background: "linear-gradient(120deg, #91b5c8, #d79872)",
|
|
35
|
+
}}
|
|
36
|
+
>
|
|
37
|
+
<h1>Your live content</h1>
|
|
38
|
+
</div>
|
|
39
|
+
</GlassContent>
|
|
40
|
+
<GlassSurface
|
|
41
|
+
material="regular"
|
|
42
|
+
radius={32}
|
|
43
|
+
style={{ position: "absolute", left: 40, top: 120, padding: 24 }}
|
|
44
|
+
>
|
|
45
|
+
<GlassButton onClick={() => console.log("Saved")}>Save</GlassButton>
|
|
46
|
+
</GlassSurface>
|
|
47
|
+
</GlassScene>
|
|
48
|
+
);
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
`GlassContent` designates the live DOM content being refracted. Glass controls remain semantic HTML above it. The renderer follows the controls' real bounds, including translation, resize, and press animations. Ordinary text, SVG, and images remain live; the library never captures or screenshots the DOM.
|
|
53
|
+
|
|
54
|
+
## Tint
|
|
55
|
+
|
|
56
|
+
Pass a six-digit hex color to any material component. Omit `tint` to restore
|
|
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.
|
|
59
|
+
|
|
60
|
+
```tsx
|
|
61
|
+
<GlassButton material="regular" tint="#007aff">Get started</GlassButton>
|
|
62
|
+
<GlassSurface material="clear" tint="#af52de">Your content</GlassSurface>
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
The same prop is available on toolbars, tab lists and indicators, and menu or
|
|
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.
|
|
97
|
+
|
|
98
|
+
```tsx
|
|
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
|
+
```
|
|
119
|
+
|
|
120
|
+
Content inside a morphing surface is revealed as the glass opens rather than
|
|
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.
|
|
126
|
+
|
|
127
|
+
The system reduced-motion setting always applies, even with `motion="full"`:
|
|
128
|
+
elasticity, stretching, and travel are removed, and presentations fade in place.
|
|
129
|
+
The light under the pointer remains as a static cue. `motion="none"` removes
|
|
130
|
+
transitions entirely.
|
|
131
|
+
|
|
132
|
+
## Components
|
|
133
|
+
|
|
134
|
+
| Export | Purpose |
|
|
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. |
|
|
143
|
+
|
|
144
|
+
Compose your existing controls:
|
|
145
|
+
|
|
146
|
+
```tsx
|
|
147
|
+
<GlassSurface material="clear" radius={28} render={<Button onClick={save} />}>
|
|
148
|
+
Save
|
|
149
|
+
</GlassSurface>
|
|
150
|
+
|
|
151
|
+
<GlassTabs material="regular" defaultValue="home"
|
|
152
|
+
items={[{ value: 'home', label: 'Home' }, { value: 'library', label: 'Library' }]}
|
|
153
|
+
aria-label="Navigation" />
|
|
154
|
+
|
|
155
|
+
<GlassMenu>
|
|
156
|
+
<GlassSurface render={<GlassMenuTrigger />}>Options</GlassSurface>
|
|
157
|
+
<GlassMenuContent material="regular">
|
|
158
|
+
<GlassMenuItem onClick={save}>Save</GlassMenuItem>
|
|
159
|
+
</GlassMenuContent>
|
|
160
|
+
</GlassMenu>
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
`GlassTabs` manages selection by default; `defaultValue` chooses the initial tab (otherwise the first enabled item). Pass `value` and `onValueChange` only when your application needs to control selection.
|
|
164
|
+
|
|
165
|
+
Ordinary DOM placed above `GlassContent` can opt into foreground refraction with
|
|
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.
|
|
169
|
+
|
|
170
|
+
```tsx
|
|
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.
|
|
178
|
+
|
|
179
|
+
Set `material` and `appearance` on `GlassScene` to share defaults across its surfaces; individual components can override them. Menu popups default to Regular.
|
|
180
|
+
|
|
181
|
+
Every glass component must be inside `GlassScene`. Menu popups portal into that scene so their material uses the same content source. `render` components must forward their DOM ref. Use one `GlassContent` per scene. In Next.js, place interactive examples in a client component.
|
|
182
|
+
|
|
183
|
+
## Composable tabs
|
|
184
|
+
|
|
185
|
+
`GlassTabs` is the convenient bar. For panels, custom triggers, disabled tabs,
|
|
186
|
+
vertical layouts, or application-controlled state, compose the same parts:
|
|
187
|
+
|
|
188
|
+
```tsx
|
|
189
|
+
// Inside a GlassScene with a GlassContent layer:
|
|
190
|
+
<GlassTabsRoot defaultValue="preview">
|
|
191
|
+
<GlassTabsList aria-label="Component view">
|
|
192
|
+
<GlassTabsIndicator />
|
|
193
|
+
<GlassTabsTrigger value="preview">Preview</GlassTabsTrigger>
|
|
194
|
+
<GlassTabsTrigger value="usage">Install & Usage</GlassTabsTrigger>
|
|
195
|
+
</GlassTabsList>
|
|
196
|
+
<GlassTabsContent value="preview">Your preview</GlassTabsContent>
|
|
197
|
+
<GlassTabsContent value="usage">Your usage code</GlassTabsContent>
|
|
198
|
+
</GlassTabsRoot>
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
All these parts are exported from `@glass-sdk/liquid-glass`. Root, trigger,
|
|
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.
|
|
206
|
+
|
|
207
|
+
## Toolbar spacing and menus
|
|
208
|
+
|
|
209
|
+
Keep related controls together and separate actions into distinct glass
|
|
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.
|
|
213
|
+
|
|
214
|
+
Compose a menu trigger through the toolbar button's `render` prop:
|
|
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
|
+
```
|
|
235
|
+
|
|
236
|
+
All parts above are public exports. The trigger renders a single button and
|
|
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:
|
|
297
|
+
|
|
298
|
+
```tsx
|
|
299
|
+
<GlassMenuContent side="top" align="center">
|
|
300
|
+
<GlassMenuItem onClick={save}>Save</GlassMenuItem>
|
|
301
|
+
<GlassMenuSubmenu>
|
|
302
|
+
<GlassMenuSubmenuTrigger>Share ›</GlassMenuSubmenuTrigger>
|
|
303
|
+
<GlassMenuSubmenuContent>
|
|
304
|
+
<GlassMenuItem onClick={copyLink}>Copy link</GlassMenuItem>
|
|
305
|
+
<GlassMenuItem onClick={email}>Email</GlassMenuItem>
|
|
306
|
+
</GlassMenuSubmenuContent>
|
|
307
|
+
</GlassMenuSubmenu>
|
|
308
|
+
</GlassMenuContent>
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
Import `GlassMenuSubmenu`, `GlassMenuSubmenuTrigger`, and
|
|
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
|
|
331
|
+
|
|
332
|
+
```tsx
|
|
333
|
+
import { GlassSlider, GlassSwitch } from "@glass-sdk/liquid-glass";
|
|
334
|
+
|
|
335
|
+
// Inside GlassScene, above GlassContent:
|
|
336
|
+
<GlassSlider aria-label="Volume" defaultValue={50}
|
|
337
|
+
onValueCommitted={(value) => console.log(value)} />
|
|
338
|
+
<GlassSlider ticks aria-label="Intensity" min={0} max={100}
|
|
339
|
+
step={25} defaultValue={50} />
|
|
340
|
+
<label>Notifications <GlassSwitch name="notifications" defaultChecked /></label>
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
`GlassSlider` accepts a single numeric `value` or `defaultValue`, `min`, `max`,
|
|
344
|
+
`step`, `onValueChange`, and `onValueCommitted`. Defaults are 0–100 with a 0.1
|
|
345
|
+
step. Set `step={25}` and `ticks` for a stepped slider; the step must
|
|
346
|
+
divide the range evenly with at most 100 intervals. Both accept Base UI slider
|
|
347
|
+
root props, including `orientation`, `name` and `form`.
|
|
348
|
+
Use `aria-label` or `aria-labelledby` to name the input. `thumbProps` exposes
|
|
349
|
+
input refs, keyboard handlers and accessible value text.
|
|
350
|
+
|
|
351
|
+
`GlassSwitch` accepts Base UI switch props, including `checked` /
|
|
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";
|
|
369
|
+
|
|
370
|
+
<GlassShape radius={14} render={<img src="/cover.jpg" alt="Album cover" />} />
|
|
371
|
+
<GlassShape radius="capsule" style={{ padding: "6px 14px" }}>Label</GlassShape>
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
Clipping follows resizing automatically. Lisse renders content borders and shadows. Keep popups outside clipped content (the supplied menus use portals), and use inset focus indicators. Shapes wait for measurement rather than displaying a CSS-rounded substitute. Use `"circle"` on square elements. Numeric radii produce continuous rectangles; coordinate nested radii with their insets.
|
|
375
|
+
|
|
376
|
+
## Props
|
|
377
|
+
|
|
378
|
+
| Prop | Default | Meaning |
|
|
379
|
+
| ------------ | ------- | ----------------------------------------------------------------------------- |
|
|
380
|
+
| `material` | `clear` | `clear` or `regular`; Regular adds frosting and a calibrated tone curve. |
|
|
381
|
+
| `appearance` | `light` | Explicit `light` or `dark` material calibration. |
|
|
382
|
+
| `radius` | `8` | Lisse continuous corner radius in CSS pixels, or `"capsule"` / `"circle"`. |
|
|
383
|
+
| `refraction` | `60` | Nonnegative displacement strength in CSS pixels. |
|
|
384
|
+
| `tint` | none | Optional six-digit hex tint, e.g. `#a8b8ff`. |
|
|
385
|
+
|
|
386
|
+
Both materials provide neutral foreground colors for their appearance. Override
|
|
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.
|
|
392
|
+
|
|
393
|
+
`GlassScene` accepts `maxSurfaces` (default 16, maximum 64) and `onDiagnostic`. Diagnostics report registered/ready maps, map render plus readback time, and GPU errors. Time is map construction time, **not** FPS or continuous GPU frame time. Separate bounded scenes are preferable to filtering an entire long page.
|
|
394
|
+
|
|
395
|
+
## Without React
|
|
396
|
+
|
|
397
|
+
```ts
|
|
398
|
+
import { createGlassScene } from "@glass-sdk/liquid-glass/dom";
|
|
399
|
+
import "@glass-sdk/liquid-glass/styles.css";
|
|
400
|
+
|
|
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,
|
|
407
|
+
});
|
|
408
|
+
// On teardown:
|
|
409
|
+
remove();
|
|
410
|
+
scene.dispose();
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
Use the same positioned scene/content/surface structure as the React example. The DOM controller wraps the original source nodes in its filter passes and restores them on disposal. `/core` exposes material definitions and numerical optics; `/gpu` exposes `MaterialRenderer`, `getMaterialRenderer`, and `disposeMaterialRenderer`. `/dom` also exposes `getMaterialMaps` and `clearMaterialMapCache` for tools and diagnostics.
|
|
414
|
+
|
|
415
|
+
`addSurface` accepts the motion options above, with `morphFrom` as a getter.
|
|
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`.
|
|
421
|
+
|
|
422
|
+
## How it works
|
|
423
|
+
|
|
424
|
+
vgpu renders WGSL material maps for displacement, coverage, highlights, and outline. Normal SVG filters apply them to the live content in `GlassContent`. Surfaces use their actual DOM bounds; content stays live without cloning or capturing it.
|
|
425
|
+
|
|
426
|
+
Maps are cached by geometry, display scale, and appearance. Moving or pressing a surface reuses its maps; resizing generates new ones. Every map requested in the same task is drawn into one atlas by a single precompiled pipeline and read back once; the pixels are encoded to PNG on a worker, never through a canvas, so the GPU process stays free for compositing. Encoded maps persist in IndexedDB, and the ones a page needed first are also kept in localStorage, so a reload composes its glass in the first frame that measures a surface, without touching the GPU. When glass changes shape in an animation, its springs are simulated ahead and the maps for the path are requested together as it starts. Content is clipped to exactly the shape being shown. A surface joined to other glass by a liquid neck draws their smooth union, traced from signed distances and rendered by the same WGSL field. Nested surfaces compose in DOM order.
|
|
427
|
+
|
|
428
|
+
Each surface's filter reads only realized images: the live source, edge tiles for the sides it samples past, its map images, and the finished layers of glass it overlaps. Glass merely near another surface takes that surface's rim and light images instead of its full layer, so no blur or displacement is ever evaluated twice. Scenes measure geometry only when something can change: input, scroll, resize, DOM mutation, CSS transitions, or a running spring. All scenes on a page share one animation frame, reading before any of them writes. Scene disposal removes filters and registrations.
|
|
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.
|
|
553
|
+
|
|
554
|
+
```tsx
|
|
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
|
+
```
|
|
561
|
+
|
|
562
|
+
Both concentric shapes and corner controls accept `container={containerRef}` for
|
|
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.
|
|
590
|
+
|
|
591
|
+
```tsx
|
|
592
|
+
<GlassSurface radius={40} style={{ padding: 4 }}>
|
|
593
|
+
<GlassSurface concentric={{ inset: 4 }} radius={8}>
|
|
594
|
+
Nested glass
|
|
595
|
+
</GlassSurface>
|
|
596
|
+
</GlassSurface>
|
|
597
|
+
```
|