LiquidGlassJS

Liquid Glass for the whole web — one engine, every browser, every framework.

Real refraction over live DOM — not a screenshot, not Chromium-only. Living spring physics, iOS-26-style metaball merging, adaptive contrast, and accessibility baked in.

Live demo & playground → · API reference · npm

Why another liquid glass library?

Every existing implementation picked one rendering lane and died in it. LiquidGlassJS probes what the browser can do and routes each surface to the best available backend — under a single API:

@surdeddd/liquidglass
├─ physics        springs: press squash, release wobble, hover magnetism
├─ material       ior, frost, bevel, dispersion, specular, tint + presets
├─ a11y           backdrop tone sampling, reduced motion / transparency
├─ dom-sync       resize / intersection / scroll tracking
└─ backends
   ├─ css-svg         backdrop-filter + displacement maps   Chromium · live DOM
   ├─ svg-content     counter-positioned live copy          Safari + Firefox · live DOM
   ├─ webgl-scene     full GPU optics over owned scenes     explicit
   ├─ webgl-overlay   one shared canvas + page snapshot     metaball merging
   └─ css-fallback    graceful blur + tint                  everywhere
Copy

How it compares

	LiquidGlassJS	liquid-glass-react	liquidGL	samasante	liquid-dom
Live-DOM refraction in Chromium	✅	✅	❌ snapshot	✅	🚧 behind flag
Live-DOM refraction in Safari/Firefox	✅	❌ flat blur	❌ snapshot	✅ manual mode	❌
Automatic capability tiering	✅	❌	❌	❌	❌
Physics system (press/wobble/hover)	✅	partial	❌	partial	❌
Metaball merging over your page	✅	❌	❌	❌	❌
Adaptive contrast (auto tint + tone hook)	✅	❌ manual flag	❌	❌	❌
prefers-reduced-motion / transparency	✅	❌	❌	❌	❌
Frameworks	vanilla · element · react 18+19 · vue 3 · svelte	react 19 only	vanilla	react	react 19
Core dependencies	0	—	0	—	—

What it looks like

Spring physics	Metaball merging + tab bar

iOS showcase	Config-exporting playground

One package

Entry	What you get
@surdeddd/liquidglass	Framework-agnostic engine — attach(), zero dependencies
@surdeddd/liquidglass/element	<liquid-glass> web component, works in any framework
@surdeddd/liquidglass/react	React 18 & 19 component + hooks
@surdeddd/liquidglass/vue	Vue 3 component + v-liquid-glass directive
@surdeddd/liquidglass/svelte	Svelte action

React, Vue and Svelte are optional peers — install only the framework you already use.

Quick start

npm i @surdeddd/liquidglass
Copy

No build step — one script tag from a CDN:

<div data-liquid-glass-auto='{"preset":"frosted"}'>glass</div>
<script src="https://unpkg.com/@surdeddd/liquidglass"></script>
<script>
  LiquidGlass.autoAttach()
</script>
Copy

import { attach } from '@surdeddd/liquidglass'

const glass = attach(document.querySelector('.panel'), {
  preset: 'frosted',
  ior: 1.5,
  dispersion: 0.3,
  motionLight: true,
  physics: { wobble: 0.8 }
})

glass.set({ preset: 'clear' })
glass.destroy()
Copy

<script type="module">
  import { define } from '@surdeddd/liquidglass/element'
  define()
</script>

<liquid-glass preset="frosted" merge="dock">Hello</liquid-glass>
Copy

import { LiquidGlass } from '@surdeddd/liquidglass/react'

<LiquidGlass as="nav" preset="clear" dispersion={0.3}>…</LiquidGlass>
Copy

…
…
Copy

…
Copy

Highlights

• Real lens optics — a convex squircle dome refracted by Snell's law (ior, default 1.5): optically flat interior with a subtle whole-body magnification (magnify) and all the bending concentrated in a rim band that tracks your corner radius, exactly like iOS 26.
• Edge chromatic aberration — dispersion splits R/G/B along the rim on every backend, including the default Chromium path.
• Living specular bezel — a two-tone rim highlight that follows the pointer (or device tilt with motionLight: true) instead of a painted-on gradient.
• Tiered rendering — capability probe picks the best backend per browser; fidelity improves as browsers ship new APIs, your code never changes.
• Metaballs — wrap lenses in <liquid-glass-group spacing="48"> (or share a merge group) and they melt into each other through an SDF smooth-min shader, the GlassEffectContainer way.
• Scroll edge — mountScrollEdge(document.body, { position: 'top' }) progressively dissolves content under your floating bars, like iOS scroll edge effects.
• Morphing — morphGlass(from, to) hands one control's geometry to another on a spring, the glassEffectID transition.
• Living physics — a mass–spring–damper system drives gel squash, wobbly release and magnetic hover on any backend; sleeps when idle.
• Adaptive contrast — glass samples backdrop luminance, flips its own tint over light content and exposes data-liquid-glass-tone for your text.
• Accessible by default — reduced motion and reduced transparency are respected live; every injected layer is aria-hidden.
• Fast — 10 lenses at 105 fps on Apple silicon (bench script included); render-on-demand everywhere, no idle loops.

Development

pnpm install
pnpm build && pnpm test && pnpm e2e && pnpm ssr
node scripts/fps-bench.mjs --headed
Copy

The landing + playground lives in apps/docs, the test harness in apps/demo, research notes in docs/research.

License

MIT