@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.
Files changed (109) hide show
  1. package/README.md +133 -494
  2. package/dist/core/concentric.js +86 -0
  3. package/dist/core/materials.js +41 -0
  4. package/dist/core/morph-path.js +206 -0
  5. package/dist/core/optics.js +7 -0
  6. package/dist/core/progressive.js +35 -0
  7. package/dist/{concentric-COCiG9DQ.js → core/shape.js} +1 -85
  8. package/dist/core/spring.js +78 -0
  9. package/dist/core/union.js +117 -0
  10. package/dist/core.js +6 -9
  11. package/dist/dom/compose-layers.js +54 -0
  12. package/dist/dom/compound-field.js +23 -0
  13. package/dist/dom/control-motion.js +101 -0
  14. package/dist/dom/engine.js +7 -0
  15. package/dist/dom/exit-handoff.js +14 -0
  16. package/dist/dom/filter-bounds.js +87 -0
  17. package/dist/dom/filter-budget.js +45 -0
  18. package/dist/dom/filter-groups.js +38 -0
  19. package/dist/dom/filter-paint-root.js +41 -0
  20. package/dist/dom/filter-patch.js +129 -0
  21. package/dist/dom/filter-reach.js +36 -0
  22. package/dist/dom/filter-stages.js +7 -0
  23. package/dist/dom/fixed-shape.js +20 -0
  24. package/dist/dom/foreground.js +36 -0
  25. package/dist/dom/interaction.js +129 -0
  26. package/dist/dom/lens-layers.js +163 -0
  27. package/dist/dom/map-blend.js +8 -0
  28. package/dist/dom/map-encoder.js +47 -0
  29. package/dist/dom/map-encoder.worker.js +16 -0
  30. package/dist/dom/map-encoding.js +17 -0
  31. package/dist/dom/map-image.js +34 -0
  32. package/dist/dom/map-store.js +189 -0
  33. package/dist/dom/maps.js +131 -0
  34. package/dist/dom/material-graph.js +52 -0
  35. package/dist/dom/morph.js +296 -0
  36. package/dist/dom/page-zoom.js +46 -0
  37. package/dist/dom/png.js +105 -0
  38. package/dist/dom/progressive.js +299 -0
  39. package/dist/dom/renderer.js +6 -0
  40. package/dist/dom/sampling-bounds.js +22 -0
  41. package/dist/dom/selection.js +106 -0
  42. package/dist/dom/shape-layout.js +199 -0
  43. package/dist/dom/shared-backdrop.js +41 -0
  44. package/dist/dom/ticker.js +103 -0
  45. package/dist/dom/warm.js +108 -0
  46. package/dist/dom.js +694 -2
  47. package/dist/gpu/geometry.js +9 -0
  48. package/dist/gpu/maps.js +8 -0
  49. package/dist/gpu/planes.js +4 -0
  50. package/dist/gpu.js +213 -2
  51. package/dist/index.js +10 -932
  52. package/dist/react/button.js +23 -0
  53. package/dist/react/control-thumb.js +50 -0
  54. package/dist/react/menu.js +159 -0
  55. package/dist/react/merged-ref.js +18 -0
  56. package/dist/react/progressive.js +73 -0
  57. package/dist/react/scene.js +122 -0
  58. package/dist/react/shape.js +93 -0
  59. package/dist/react/surface.js +69 -0
  60. package/dist/react/tabs.js +94 -0
  61. package/dist/react/toolbar.js +145 -0
  62. package/dist/react/value-control-motion.js +9 -0
  63. package/dist/react/value-controls.js +176 -0
  64. package/dist/styles.css +19 -0
  65. package/dist/types/core/optics.d.ts +0 -1
  66. package/dist/types/core/spring.d.ts +1 -1
  67. package/dist/types/dom/compose-layers.d.ts +15 -0
  68. package/dist/types/dom/compound-field.d.ts +35 -0
  69. package/dist/types/dom/engine.d.ts +9 -0
  70. package/dist/types/dom/exit-handoff.d.ts +7 -0
  71. package/dist/types/dom/filter-bounds.d.ts +1 -1
  72. package/dist/types/dom/filter-budget.d.ts +20 -0
  73. package/dist/types/dom/filter-groups.d.ts +25 -0
  74. package/dist/types/dom/filter-paint-root.d.ts +9 -0
  75. package/dist/types/dom/filter-patch.d.ts +3 -8
  76. package/dist/types/dom/filter-reach.d.ts +23 -0
  77. package/dist/types/dom/filter-stages.d.ts +5 -0
  78. package/dist/types/dom/index.d.ts +3 -0
  79. package/dist/types/dom/lens-layers.d.ts +68 -0
  80. package/dist/types/dom/map-blend.d.ts +22 -0
  81. package/dist/types/dom/map-encoding.d.ts +1 -1
  82. package/dist/types/dom/map-image.d.ts +5 -2
  83. package/dist/types/dom/maps.d.ts +5 -5
  84. package/dist/types/dom/material-graph.d.ts +22 -0
  85. package/dist/types/dom/morph.d.ts +8 -0
  86. package/dist/types/dom/page-zoom.d.ts +18 -0
  87. package/dist/types/dom/png.d.ts +2 -0
  88. package/dist/types/dom/progressive.d.ts +29 -1
  89. package/dist/types/dom/renderer.d.ts +4 -0
  90. package/dist/types/dom/sampling-bounds.d.ts +10 -0
  91. package/dist/types/dom/shared-backdrop.d.ts +19 -0
  92. package/dist/types/dom/warm.d.ts +4 -1
  93. package/dist/types/gpu/geometry.d.ts +17 -0
  94. package/dist/types/gpu/index.d.ts +4 -16
  95. package/dist/types/gpu/planes.d.ts +2 -0
  96. package/dist/types/react/button.d.ts +11 -0
  97. package/dist/types/react/index.d.ts +14 -149
  98. package/dist/types/react/menu.d.ts +29 -0
  99. package/dist/types/react/progressive.d.ts +15 -0
  100. package/dist/types/react/scene.d.ts +35 -0
  101. package/dist/types/react/surface.d.ts +35 -0
  102. package/dist/types/react/tabs.d.ts +29 -0
  103. package/dist/types/react/toolbar.d.ts +21 -0
  104. package/package.json +1 -1
  105. package/dist/dom-CKc8vDTR.js +0 -2532
  106. package/dist/gpu-Co5Y89mh.js +0 -244
  107. package/dist/map-encoder.worker-DO1drw0Y.js +0 -16
  108. package/dist/materials-DVPgteZ9.js +0 -234
  109. 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
- 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.
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
- [Interactive examples](https://liquid-glass.glassapp.dev/#examples)
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
- bun add @glass-sdk/liquid-glass@~0.0.1
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: 400 }}>
21
+ <GlassScene material="regular" appearance="light" style={{ height: 320 }}>
30
22
  <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>
23
+ <img src="/landscape.jpg" alt="Mountain lake"
24
+ style={{ width: "100%", height: "100%", objectFit: "cover" }} />
39
25
  </GlassContent>
40
- <GlassSurface
41
- material="regular"
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
- `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.
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
- ## Tint
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
- 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.
39
+ ## Components
59
40
 
60
- ```tsx
61
- <GlassButton material="regular" tint="#007aff">Get started</GlassButton>
62
- <GlassSurface material="clear" tint="#af52de">Your content</GlassSurface>
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
- 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.
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
- ```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
- ```
57
+ ## Material and motion
119
58
 
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.
59
+ Set defaults on `GlassScene`; individual surfaces can override them. Menu popups default to Regular.
126
60
 
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.
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
- ## Components
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
- | 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. |
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
- Compose your existing controls:
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" radius={28} render={<Button onClick={save} />}>
85
+ <GlassSurface material="clear" render={<Button onClick={save} />}>
148
86
  Save
149
87
  </GlassSurface>
88
+ ```
150
89
 
151
- <GlassTabs material="regular" defaultValue="home"
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
- <GlassSurface render={<GlassMenuTrigger />}>Options</GlassSurface>
157
- <GlassMenuContent material="regular">
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
- `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.
107
+ `GlassMenuGroup`, `GlassMenuGroupLabel`, `GlassMenuSeparator`, `GlassMenuCheckboxItem`, `GlassMenuRadioGroup`, and `GlassMenuRadioItem` expose the corresponding Base UI parts.
164
108
 
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.
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
- ```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.
111
+ ## Tabs, sliders, and switches
178
112
 
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.
113
+ ```tsx
114
+ <GlassTabs aria-label="Navigation" defaultValue="home"
115
+ items={[{ value: "home", label: "Home" }, { value: "library", label: "Library" }]} />
182
116
 
183
- ## Composable tabs
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
- `GlassTabs` is the convenient bar. For panels, custom triggers, disabled tabs,
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="Component view">
127
+ <GlassTabsList aria-label="View">
192
128
  <GlassTabsIndicator />
193
129
  <GlassTabsTrigger value="preview">Preview</GlassTabsTrigger>
194
- <GlassTabsTrigger value="usage">Install & Usage</GlassTabsTrigger>
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
- 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.
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
- ## Toolbar spacing and menus
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
- 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.
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
- 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
- ```
143
+ ## Progressive blur
235
144
 
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:
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
- <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>
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
- 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
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
- import { GlassSlider, GlassSwitch } from "@glass-sdk/liquid-glass";
160
+ const viewport = useRef<HTMLDivElement>(null);
334
161
 
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>
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
- `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";
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
- <GlassShape radius={14} render={<img src="/cover.jpg" alt="Album cover" />} />
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
- 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.
183
+ ## Content shapes and foregrounds
375
184
 
376
- ## Props
185
+ `GlassShape` clips images and content to continuous corners without needing a scene:
377
186
 
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`. |
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 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.
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
- `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.
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 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.
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
- `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`.
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
- ## How it works
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
- 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.
221
+ ## Requirements and limitations
425
222
 
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.
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
- 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.
230
+ ## How it works
553
231
 
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
- ```
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
- 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.
234
+ ## Contributing and license
590
235
 
591
- ```tsx
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).