liquid-gl 1.0.0 → 1.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +207 -18
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,47 +1,236 @@
|
|
|
1
|
-
# liquidGL
|
|
1
|
+
# liquidGL – Ultra-light glassmorphism for the web
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<a href="https://liquidgl.naughtyduk.com"><img src="https://raw.githubusercontent.com/naughtyduk/liquidGL/main/assets/liquidGlass-promo.gif" alt="liquidGL" style="width: 100%"/></a>
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**Prodution Release** - `now with real-time support`\*
|
|
6
|
+
|
|
7
|
+
> [!NOTE]
|
|
8
|
+
> `liquidGL` is free to use for both non-commercial and commercial purposes. _BETA_ has now ended and the library is now ready for production use.
|
|
9
|
+
|
|
10
|
+
`liquidGL` turns any fixed-position element into a perfectly refracted, glossy "glass pane" rendered in WebGL.
|
|
11
|
+
|
|
12
|
+
<a href="https://liquidgl.naughtyduk.com" target="_blank" rel="noopener noreferrer"><strong>TRY IT OUT</strong></a>
|
|
13
|
+
|
|
14
|
+
<a href="https://liquidgl.naughtyduk.com/demos/demo-1.html" target="_blank" rel="noopener noreferrer"><strong>DEMO 1</strong></a> | <a href="https://liquidgl.naughtyduk.com/demos/demo-2.html" target="_blank" rel="noopener noreferrer"><strong>DEMO 2</strong></a> | <a href="https://liquidgl.naughtyduk.com/demos/demo-3.html" target="_blank" rel="noopener noreferrer"><strong>DEMO 3</strong></a> | <a href="https://liquidgl.naughtyduk.com/demos/demo-4.html" target="_blank" rel="noopener noreferrer"><strong>DEMO 4</strong></a> | <a href="https://liquidgl.naughtyduk.com/demos/demo-5.html" target="_blank" rel="noopener noreferrer"><strong>DEMO 5</strong></a>
|
|
15
|
+
|
|
16
|
+
## Install from npm
|
|
6
17
|
|
|
7
18
|
```sh
|
|
8
19
|
npm install liquid-gl
|
|
9
20
|
```
|
|
10
21
|
|
|
11
|
-
## Usage
|
|
12
|
-
|
|
13
22
|
```js
|
|
14
23
|
import liquidGL from "liquid-gl";
|
|
15
24
|
|
|
16
|
-
const
|
|
25
|
+
const glassEffect = liquidGL({
|
|
17
26
|
target: ".liquidGL",
|
|
18
27
|
snapshot: "body",
|
|
19
28
|
});
|
|
20
29
|
```
|
|
21
30
|
|
|
22
|
-
|
|
31
|
+
> `html2canvas` is installed automatically as a package dependency. `three` is optional and only required when using `liquidGL` with 3D model workflows.
|
|
23
32
|
|
|
24
|
-
|
|
33
|
+
---
|
|
25
34
|
|
|
26
|
-
##
|
|
35
|
+
## Overview
|
|
27
36
|
|
|
28
|
-
`
|
|
37
|
+
`liquidGL` recreates Apple's "Liquid Glass" aesthetic in the browser with an ultra-light WebGL shader. It turns any DOM element into a beautiful, refracting glass pane. To overcome WebGL's security limitations on reading live screen pixels, `liquidGL` uses an innovative offscreen rendering technique. This allows it to refract dynamic content like videos, text animations, and more in real-time, delivering a smooth and interactive experience.
|
|
29
38
|
|
|
30
|
-
|
|
31
|
-
|
|
39
|
+
### Key Features
|
|
40
|
+
|
|
41
|
+
| Feature | Supported | Feature | Supported |
|
|
42
|
+
| :------------------------------------- | :-------: | :----------------------- | :-------: |
|
|
43
|
+
| Real-time Refraction (static content) | ✅ | Magnification Control | ✅ |
|
|
44
|
+
| Real-time Refraction (video) | ✅ | Dynamic Element Support | ✅ |
|
|
45
|
+
| Real-time Refraction (text animations) | ✅ | GSAP-Ready Animations | ✅ |
|
|
46
|
+
| Real-time Refraction (CSS animations) | ❌ | Lightweight & Performant | ✅ |
|
|
47
|
+
| Adjustable Bevel | ✅ | Seamless Scroll Sync | ✅ |
|
|
48
|
+
| Frosted Glass Effect | ✅ | Auto-Resize Handling | ✅ |
|
|
49
|
+
| Dynamic Shadows | ✅ | Auto Video Refraction | ✅ |
|
|
50
|
+
| Specular Highlights | ✅ | Animate Lenses | ✅ |
|
|
51
|
+
| Interactive Tilt Effect | ✅ | `on.init` Callback | ✅ |
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## Quick start
|
|
56
|
+
|
|
57
|
+
Set up your HTML structure first. You will have a `target` element that will receive the glass effect, and a child element for your content (excluded from glass effect).
|
|
58
|
+
|
|
59
|
+
```html
|
|
60
|
+
<body>
|
|
61
|
+
<div class="liquidGL">
|
|
62
|
+
<div class="content">
|
|
63
|
+
<img src="example.svg" alt="Alt Text" />
|
|
64
|
+
<p>This example text content will appear on top of the glass.</p>
|
|
65
|
+
</div>
|
|
66
|
+
</div>
|
|
67
|
+
</body>
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
> Make sure that your `target` element has a high z-index so that it sits over your page content. Any content with a higher z-index than the `target` will be excluded from the lens, i.e a modal video player that you don't want to stain the lens.
|
|
71
|
+
|
|
72
|
+
Next, initialise the library with the selector for your target element.
|
|
73
|
+
|
|
74
|
+
```js
|
|
75
|
+
import liquidGL from "liquid-gl";
|
|
76
|
+
|
|
77
|
+
const glassEffect = liquidGL({
|
|
78
|
+
snapshot: "body",
|
|
79
|
+
target: ".liquidGL",
|
|
80
|
+
resolution: 2.0,
|
|
81
|
+
refraction: 0.01,
|
|
82
|
+
bevelDepth: 0.08,
|
|
83
|
+
bevelWidth: 0.15,
|
|
84
|
+
frost: 0,
|
|
85
|
+
shadow: true,
|
|
86
|
+
specular: true,
|
|
87
|
+
reveal: "fade",
|
|
88
|
+
tilt: false,
|
|
89
|
+
tiltFactor: 5,
|
|
90
|
+
magnify: 1,
|
|
91
|
+
on: {
|
|
92
|
+
init(instance) {
|
|
93
|
+
console.log("liquidGL ready!", instance);
|
|
94
|
+
},
|
|
95
|
+
},
|
|
96
|
+
});
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## Dynamic Rendering
|
|
102
|
+
|
|
103
|
+
`liquidGL` can refract dynamic content like animations in real-time. To make this work, you must "register" any dynamic elements that will intersect with your glass pane. This tells `liquidGL` to monitor them and update the texture when they change.
|
|
104
|
+
|
|
105
|
+
> **Note:** Videos are automatically detected and do not need to be registered.
|
|
106
|
+
|
|
107
|
+
Register dynamic elements _after_ initialising `liquidGL()` but _before_ calling `liquidGL.syncWith()` (if used). You can register elements using a CSS selector string or by passing an array of DOM elements.
|
|
108
|
+
|
|
109
|
+
```js
|
|
110
|
+
const glassEffect = liquidGL({
|
|
111
|
+
target: ".liquidGL",
|
|
112
|
+
});
|
|
113
|
+
|
|
114
|
+
liquidGL.registerDynamic(".my-animated-element");
|
|
115
|
+
|
|
116
|
+
const mySplitText = SplitText.create(".my-text", { type: "lines" });
|
|
117
|
+
liquidGL.registerDynamic(mySplitText.lines);
|
|
32
118
|
```
|
|
33
119
|
|
|
34
|
-
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## Optionally sync with Smooth Scrolling Libraries
|
|
123
|
+
|
|
124
|
+
`liquidGL` includes a `syncWith()` helper to automatically integrate with popular smooth-scrolling libraries like Lenis and Locomotive Scroll. It handles the render loop synchronization for you.
|
|
125
|
+
|
|
126
|
+
> Simply call `liquidGL.syncWith()` after initialising `liquidGL`.
|
|
35
127
|
|
|
36
128
|
```js
|
|
37
|
-
liquidGL
|
|
38
|
-
liquidGL
|
|
129
|
+
const glassEffect = liquidGL({
|
|
130
|
+
target: ".liquidGL",
|
|
131
|
+
});
|
|
132
|
+
|
|
133
|
+
const { lenis, locomotiveScroll } = liquidGL.syncWith();
|
|
39
134
|
```
|
|
40
135
|
|
|
41
|
-
|
|
136
|
+
> Make sure to include the scroll library scripts before your main script. The `syncWith()` helper must be called **after** `liquidGL()` has been called.
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## Parameters
|
|
141
|
+
|
|
142
|
+
| Option | Type | Default | Description |
|
|
143
|
+
| ------------ | -------- | ------------- | ------------------------------------------------------------------------------------------------ |
|
|
144
|
+
| `target` | string | `'.liquidGL'` | **Required.** CSS selector for the element(s) to glassify. |
|
|
145
|
+
| `snapshot` | string | `'body'` | CSS selector for the element to snapshot. |
|
|
146
|
+
| `resolution` | number | `2.0` | Resolution of the background snapshot (clamped 0.1–3.0). Higher is sharper but uses more memory. |
|
|
147
|
+
| `refraction` | number | `0.01` | Base refraction offset applied across the pane (0–1). |
|
|
148
|
+
| `bevelDepth` | number | `0.08` | Additional refraction on the edge to simulate depth (0–1). |
|
|
149
|
+
| `bevelWidth` | number | `0.15` | Width of the bevel zone as a fraction of the shortest side (0–1). |
|
|
150
|
+
| `frost` | number | `0` | Blur radius in pixels for a frosted look. `0` is clear. |
|
|
151
|
+
| `shadow` | boolean | `true` | Toggles a subtle drop-shadow under the pane. |
|
|
152
|
+
| `specular` | boolean | `true` | Enables animated specular highlights that move with time. |
|
|
153
|
+
| `reveal` | string | `'fade'` | Reveal animation.<br>- `'none'`: Renders immediately.<br>- `'fade'`: Smoothly fades in. |
|
|
154
|
+
| `tilt` | boolean | `false` | Enables 3D tilt interaction on cursor movement. |
|
|
155
|
+
| `tiltFactor` | number | `5` | Depth of the tilt in degrees (0–25 recommended). |
|
|
156
|
+
| `magnify` | number | `1` | Magnification factor of the lens (clamped 0.001–3.0). `1` is no magnification. |
|
|
157
|
+
| `on.init` | function | `—` | Callback that runs once the first render completes. Receives the lens instance. |
|
|
158
|
+
|
|
159
|
+
> The `target` parameter is required; all others are optional.
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## Presets
|
|
164
|
+
|
|
165
|
+
| Name | Settings | Purpose |
|
|
166
|
+
| ----------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
|
|
167
|
+
| **Default** | `{ refraction: 0, bevelDepth: 0.052, bevelWidth: 0.211, frost: 2, shadow: true, specular: true }` | Balanced default used in the demo. |
|
|
168
|
+
| **Alien** | `{ refraction: 0.073, bevelDepth: 0.2, bevelWidth: 0.156, frost: 2, shadow: true, specular: false }` | Strong refraction & deep bevel for a sci-fi look. |
|
|
169
|
+
| **Pulse** | `{ refraction: 0.03, bevelDepth: 0, bevelWidth: 0.273, frost: 0, shadow: false, specular: false }` | Flat pane with wide bevel—great for pulsing UI effects. |
|
|
170
|
+
| **Frost** | `{ refraction: 0, bevelDepth: 0.035, bevelWidth: 0.119, frost: 0.9, shadow: true, specular: true }` | Softly diffused, privacy-glass style. |
|
|
171
|
+
| **Edge** | `{ refraction: 0.047, bevelDepth: 0.136, bevelWidth: 0.076, frost: 2, shadow: true, specular: false }` | Thin bevel and bright rim highlights. |
|
|
172
|
+
|
|
173
|
+
---
|
|
174
|
+
|
|
175
|
+
## FAQ
|
|
176
|
+
|
|
177
|
+
| Question | Answer |
|
|
178
|
+
| :----------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
179
|
+
| Is there a resize handler? | Yes resize is handled in the library and debounced to 250ms for performance. |
|
|
180
|
+
| Does the effect work on mobile? | Yes the library handles all 3 versions of WebGL and provides a frosted CSS `backdrop-filter` as a backup for older devices. |
|
|
181
|
+
| I have a preloader, how should I initialise `liquidGL()`? | Add the `data-liquid-ignore` attribute to your preloader's top-level container to exclude it from the snapshot. You can then call `liquidGL()` inside a `DOMContentLoaded` listener as you normally would. |
|
|
182
|
+
| What is the correct way to use `liquidGL` with page animations? | Lets say you have a preloader, above the fold intro animations and scroll animations on your page. You would:<br><br>1) set the `data-liquid-ignore` attribute on your preloader<br>2) animate your preloader and set up your initial animation states<br>3) then call `liquidGL();`<br>4) optionally, in the `on.init();` callback, you can run post snapshot scripts, such as animating the `target` element |
|
|
183
|
+
| Can I use `liquidGL` on multiple elements? | Yes, any element which has the class declared as your `target` will be glassified. Note **all elements must use the same `z-index`** due to shared canvas optimisations, if you use different `z-index` values for multiple targets, the highest value will be used by `liquidGL`. |
|
|
184
|
+
| Will the library exceed WebGL contexts or have other performance issues? | No, the library uses a shared canvas for all instances, we have tested up to 30 elements on one page and we were not able to cause performance problems or crashes. |
|
|
185
|
+
| Are there any animation limitations? | It depends on what you're trying to do, rotation and scale are expensive CPU/GPU processes, additionally `shadow` `specular` and `tilt` should be used with care when you have lots of instances or complex animations as they can clog the render pipeline. |
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
## Important Notes
|
|
190
|
+
|
|
191
|
+
- For dynamic content to be refracted in real-time, you must register the element(s) with `liquidGL.registerDynamic()`. It is crucial to set the initial state of your animations **before** calling `liquidGL()` to ensure they are captured correctly.
|
|
192
|
+
- The library ignores `fixed` position elements, this is to prevent a known bug between html2canvas and mobile browsers from surfacing which can prevent the snapshot from running. This is a safety net that shouldn't interfere with your use of the library.
|
|
193
|
+
- You can have multiple instances on one page **but they must share the same `z-index` value**. If you specify different `z-index` values, `liquidGL` will use the highest `z-index` for all elements with the `target` selector. This is because the effect uses a shared canvas to prevent WebGL context issues, there is no work around to this unfortunately.
|
|
194
|
+
- To improve performance on complex pages, you can snapshot a smaller, specific element like a background container instead of the whole page. Use the `snapshot` option with a CSS selector (e.g., `snapshot: '.my-background'`). This reduces texture memory and improves performance.
|
|
195
|
+
- The initial capture is asynchronous. Call `liquidGL()` inside a `DOMContentLoaded` or `load` handler to ensure content is available to the snapshot.
|
|
196
|
+
- Extremely long documents can exceed GPU texture limits, causing memory or performance issues. Consider segmenting very long pages (see source) or reducing the `resolution` parameter.
|
|
197
|
+
- The `shadow` and `tilt` effects create new stacking layers behind the `target` element. The `shadow` is placed at `z-index - 2` and the `tilt` helper canvas is placed at `z-index - 1`. Ensure your `z-index` values leave room for these layers to prevent clipping or overflow issues.
|
|
198
|
+
- As with all WebGL effects, any **image** content inside the `target` element must have permissive `Access-Control-Allow-Origin` headers set to prevent CORS issues.
|
|
199
|
+
|
|
200
|
+
---
|
|
201
|
+
|
|
202
|
+
## Browser Support
|
|
203
|
+
|
|
204
|
+
The `liquidGL` library is compatible with all WebGL enabled browsers on desktop, tablet and mobile devices.
|
|
205
|
+
|
|
206
|
+
> [!NOTE]
|
|
207
|
+
> Performance varies between browsers, specifically Safari can be unstable when the liquid element(s) are more than 50% of the viewport width or height. Practical use issues are rare, but make sure to test on your target devices thoroughly.
|
|
208
|
+
|
|
209
|
+
| Browser | Supported |
|
|
210
|
+
| :------------- | :-------: |
|
|
211
|
+
| Google Chrome | Yes |
|
|
212
|
+
| Safari | Yes |
|
|
213
|
+
| Firefox | Yes |
|
|
214
|
+
| Microsoft Edge | Yes |
|
|
215
|
+
|
|
216
|
+
---
|
|
217
|
+
|
|
218
|
+
## Other
|
|
219
|
+
|
|
220
|
+
**Exclude elements**
|
|
221
|
+
|
|
222
|
+
> You can set elements to be ignored by the refraction using `data-liquid-ignore`. Add this attribute on the parent container of the element you wish to exclude.
|
|
223
|
+
|
|
224
|
+
**Content Visibility**
|
|
225
|
+
|
|
226
|
+
> It is recommended to use `z-index: 3;` on the content inside your target element to make it sit on top of the lens. You can also combine this with `mix-blend-mode: difference;` for better legibility.
|
|
227
|
+
|
|
228
|
+
**Border-radius**
|
|
229
|
+
|
|
230
|
+
> `liquidGL` automatically inherits the `border-radius` of the `target` element, ensuring the refraction respects rounded corners without any extra configuration. If you animate the `border-radius` of your `target` element i.e on scroll, the bevel will animate in real time to remain in sync.
|
|
42
231
|
|
|
43
|
-
|
|
232
|
+
---
|
|
44
233
|
|
|
45
234
|
## License
|
|
46
235
|
|
|
47
|
-
MIT
|
|
236
|
+
MIT © NaughtyDuk
|