Liquid Glass

What is Liquid Glass?

Liquid Glass is a lightweight JavaScript/TypeScript library that applies realistic glass refraction, blur, chromatic aberration, and lighting effects to any HTML element using WebGL shaders. It captures the DOM content behind each glass element, processes it through a multi-pass rendering pipeline, and composites the result in real time.

The library handles layered compositing (glass-on-glass), dynamic content updates, draggable floating panels, responsive resizing, and works with any background — images, videos, canvases, or plain HTML.

Getting Started

Install via npm:

npm install liquid-glass

Basic usage:

import { LiquidGlass } from 'liquid-glass';

const instance = await LiquidGlass.init({
    root: document.querySelector('#my-root'),
    glassElements: document.querySelectorAll('.glass'),
});

// Later:
instance.destroy();

The root element must be a positioned container (position: relative) and each glass element must be a direct child of the root. Each glass element gets a child <canvas> injected automatically for the shader output.

Interactive Playground

Adjust the sliders to see how each parameter affects the glass effect in real time. Drag the glass panel to move it around.

Glass

Configuration Options

Each glass element can be configured individually via data-config (JSON) or globally via the defaults option:

Frosted Panel

element.dataset.config = JSON.stringify({
    blurAmount: 0.25,
    cornerRadius: 30,
});

Frosted Glass

Dark Glass

element.dataset.config = JSON.stringify({
    brightness: -0.3,
    blurAmount: 0.25,
    cornerRadius: 50,
});

Dark Glass

Button Mode

Set button: true to make a glass element react to hover and press: hovering brightens it, pressing flattens the bevel and deepens the shadow. Try the button below:

element.dataset.config = JSON.stringify({
    button: true,
    cornerRadius: 24,
});

Click Me

Dome Bevel (Magnifier)

Set bevelMode: 1 with equal cornerRadius and zRadius for a half-sphere lens effect. Try dragging the dome below:

element.dataset.config = JSON.stringify({
    bevelMode: 1,
    cornerRadius: 50,
    zRadius: 50,
    floating: true,
    blurAmount: 0,
    refraction: 1.2,
});

Limitations & Gotchas

The library leans on real-time DOM rasterisation and a multi-pass WebGL pipeline. That comes with a handful of constraints worth knowing before you wire it into a production page.

Structural

• Glass elements must be direct children of the root. Nested glass is rejected at init with a console warning. If you need glass inside a wrapper, give the wrapper its own LiquidGlass.init() call.
• The root itself is never captured. The shader samples the root's children, so any background image, padding, or border on the root is invisible to the glass effect. Put backgrounds in a sibling element inside the root (e.g. an absolutely positioned <img>).
• A <canvas> is injected as the glass element's first child for shader output. Avoid :first-child selectors on glass elements.
• Multiple LiquidGlass roots cannot share refraction. A glass element in one root cannot see what another root's glass elements are rendering — they each have their own compositing canvas.

Performance

• Capturing DOM into a canvas is expensive. Every non-glass wrapper is rasterised via html-to-image (style inlining + SVG-foreignObject decode). Keep wrappers small and shallow.
• data-dynamic elements are treated as always dirty by definition. Use it only for content that genuinely changes every frame — animations, counters, charts. For one-shot updates that don't happen every frame, prefer instance.markChanged() (see below) — it costs nothing on idle frames.
• Each LiquidGlass instance opens its own WebGL context. Browsers cap concurrent contexts (typically 16 system-wide); don't spawn dozens.
• Window resize re-captures everything. Don't drive layout in a tight resize loop.

Text alignment

• Use integer-pixel font-size values for any text that may sit under glass. Sub-pixel sizes (e.g. 0.92em, clamp(...)) cause sub-pixel rounding differences between live HTML rendering and the SVG-foreignObject path used for capture, which shifts glyph positions inside the refraction.
• Webfonts must be loaded before init() and served with CORS-friendly headers. Google Fonts, jsdelivr, and unpkg work out of the box. Self-hosted fonts on a same-origin server need no special config. Webfonts loaded after init will fall back to system fonts inside captured rasters.
• Cross-origin <img> elements need crossorigin="anonymous". Tainted canvases break texture upload and disable the glass effect for the entire root.

API

• LiquidGlass.init() is async — it resolves only after font CSS prefetch, glass content pre-capture, and static-content pre-warm have all completed. On a slow connection that can be 100–500 ms.
• data-dynamic only catches direct children of the root. A live element nested inside a wrapper that lacks data-dynamic will not trigger re-captures.
• The library auto-detects <video> elements as dynamic — you don't need to add data-dynamic to them.
• html-to-image cannot rasterise <video> or <canvas>. The library handles them via a fast drawImage path instead.

instance.markChanged()

Call markChanged(element) after you update something the library can't observe on its own — a <canvas> you just painted, an <img> you just swapped, a CSS property you just toggled. Only glasses overlapping that element will re-render. Call with no argument to invalidate everything.

instance.markChanged(myCanvasElement); // targeted
instance.markChanged();                // everything