# LiquidGlass

By **ybouane** · Software & Tools

WebGL glass-effect library for the web, apply realistic refraction, blur, and lighting to any HTML element with a single async init call.

- Source: https://liquid-glass.ybouane.com/
- Repository: https://github.com/ybouane/liquidglass
- Install: `npm i @ybouane/liquidglass`
- Tags: webgl, animation, ui, open-source, typescript, javascript, glass-morphism, frontend
- Pricing: free
- Upvotes: 0

## Features

- Real-time WebGL refraction, chromatic aberration, Fresnel reflection, and specular highlights
- Layered glass-on-glass compositing (lower panels visible in upper panel's refraction)
- Draggable floating panels via Pointer Events (floating: true)
- Button mode with hover brightening and press bevel feedback
- Dome/magnifier bevel mode (half-sphere lens effect)
- Smart dirty-tracking: per-element markChanged() for manual invalidation
- Auto-detection of <video> elements as dynamic content
- CDN import with no build step required

---

## Why it matters

Real glass-morphism on the web has always been a CSS approximation: `backdrop-filter: blur()` with no refraction, no chromatic aberration, no physical bevel. LiquidGlass replaces that approximation with a multi-pass WebGL shader pipeline that samples actual DOM content, bends light through it, and composites the result in real time.

## The big picture

Apple's introduction of Liquid Glass across iOS 26, macOS Tahoe, and iPadOS 26 reset the bar for what interface materials can do. LiquidGlass (the library, by @ybouane) brings that physical quality to any web page, targeting any HTML element, without locking you into a native framework.

## How it works

1. Non-glass children of the root are rasterised onto a hidden canvas via `html-to-image`. Static children are captured once and cached; `data-dynamic` children and `<video>` elements are re-captured every frame.
2. A fragment shader runs per glass element: it crops the compositing canvas at the panel's location, optionally Gaussian-blurs it, then applies refraction, chromatic aberration, Fresnel reflection, specular highlights (Blinn-Phong), an inner rim stroke, and a drop shadow.
3. Each rendered glass canvas is written back to the compositing canvas before the next glass element runs, so stacked glass panels refract each other correctly.

## Zoom in

Fourteen shader parameters are individually tunable via `data-config` JSON: `blurAmount`, `refraction`, `chromAberration`, `edgeHighlight`, `specular`, `fresnel`, `distortion`, `bevelMode` (biconvex pill or dome magnifier), `tintStrength`, `saturation`, `brightness`, `cornerRadius`, `zRadius`, and shadow controls. A MutationObserver watches `data-config`, so live updates cost nothing extra.

## Yes, but

The structural rules are strict. Glass elements must be direct children of the root container; nesting is rejected at init. The root itself is never captured, so backgrounds must live as sibling elements inside it. Each instance opens its own WebGL context, and browsers typically cap concurrent contexts at around 16 system-wide, meaning dozens of simultaneous instances will break. `init()` is async and can take 100-500 ms on a cold page. Cross-origin images need `crossorigin="anonymous"` or they taint the canvas and disable the entire root's effect.

## The bottom line

LiquidGlass is the most physically faithful glass-rendering library available for the open web today, per the README's own accounting of its pipeline. The tradeoffs are real: DOM rasterisation is expensive, the structural constraints are non-trivial, and the dirty-tracking system requires deliberate care. For a portfolio hero, a product landing page, or an OS-style UI shell, it earns its complexity. For a form-heavy SaaS dashboard with dozens of components, it probably does not.

## FAQ

### What is LiquidGlass?

LiquidGlass is a lightweight JavaScript/TypeScript library that renders physically accurate glass effects, including refraction, Gaussian blur, chromatic aberration, Fresnel reflection, and multi-light specular highlights, on any HTML element using WebGL shaders. It captures the DOM content behind each designated glass element, processes it through a multi-pass rendering pipeline, and composites the result in real time. It was created by @ybouane and is available on npm and via CDN.

### How do I install and use LiquidGlass?

Install via npm with `npm install @ybouane/liquidglass`, or import directly from a CDN without a build step: `import { LiquidGlass } from 'https://cdn.jsdelivr.net/npm/@ybouane/liquidglass/dist/index.js'`. Call the async `LiquidGlass.init({ root, glassElements })` after the DOM and webfonts are loaded, it resolves once font prefetching and content pre-capture are complete, which can take 100-500 ms. Configure individual glass panels by setting `data-config` to a JSON string of options like `blurAmount`, `refraction`, and `floating`.

### Is LiquidGlass free or open source?

LiquidGlass is an open-source library available on GitHub at ybouane/liquidglass and published to npm as @ybouane/liquidglass. The sources do not mention any licensing cost, commercial tier, or usage restriction. It can be imported directly from CDN (jsdelivr) at no cost.

### What is LiquidGlass best suited for?

LiquidGlass is best for interfaces where the glass effect is a primary visual feature, such as portfolio hero sections, product landing pages, OS-style web shells, or interactive demos with rich backgrounds (images, video, animated canvas). Its dirty-tracking system short-circuits the render loop on static pages, so it is efficient when most content is stable. It is less suited to complex SaaS dashboards with many components, deep DOM trees, or dozens of concurrent glass panels.

### How does LiquidGlass compare to CSS backdrop-filter glass effects?

CSS `backdrop-filter: blur()` is a fast GPU composite hint that blurs whatever is behind an element, but it cannot simulate refraction, chromatic aberration, Fresnel reflection, or bevel depth. LiquidGlass rasterises the actual DOM content behind each glass element and runs a multi-pass fragment shader, producing physically plausible light-bending, color fringing, and specular highlights that `backdrop-filter` cannot achieve. The tradeoff is complexity: LiquidGlass requires structural constraints (direct child elements, CORS-safe images), has a 100-500 ms async init cost, and is heavier than a single CSS property.

### What are the main limitations or gotchas to know before using LiquidGlass?

Glass elements must be direct children of the root container; nested glass is rejected at init with a console warning. Browsers typically cap WebGL contexts at around 16 system-wide, so spawning many LiquidGlass instances on one page will fail. Cross-origin images need `crossorigin='anonymous'` or they taint the canvas and disable the glass effect for the entire root. Webfonts must be fully loaded before `init()` is called, and `data-dynamic` content is re-rasterised every frame, which is expensive and should be used sparingly.

---
[View on Analog](https://analoghq.ai/ybouane/software-tools/liquidglass)