💧 LiquidLens: Apple Liquid Glass for Every Platform

The iOS 26 Liquid Glass effect with real edge refraction. Blur was never the effect. One optical engine, five platforms: Web · React · React Native · Flutter · SwiftUI.

↑ Real footage from artifacts/01-playground.html. Drag any panel, tune the material live.

⭐ If LiquidLens saves you a week of shader math, star the repo. Stars are how other developers find it.

📖 Table of Contents

Blur is NOT Liquid Glass · Features · Quick start · Five platforms · Showcase · How it works · The vision · Docs · FAQ · Contributing

🔍 Blur is NOT Liquid Glass

Search "liquid glass CSS" and nearly every tutorial hands you backdrop-filter: blur(12px) with a white tint. That recipe has a name: glassmorphism. It peaked in 2020. Apple's Liquid Glass (WWDC 2025, iOS 26, macOS Tahoe) is a different material entirely. It bends light at its edges, the way the rim of a real lens does. Hold a glass of water over a page of text and watch the letters warp near the rim. That warp is the effect. A blur can't produce it.

	🧊 Glassmorphism (what tutorials teach)	💧 Liquid Glass (what Apple ships, what LiquidLens does)
Backdrop blur + tint	✅	✅
Edge refraction / lensing	❌	✅ the defining trait
Motion-tracking specular highlight	❌	✅
Chromatic edge (light dispersion)	❌	✅
Adaptive shadow & legibility	❌	✅
Regular / Clear variants (Apple's vocabulary)	❌	✅

⚡ Features

🔬 Physically-based refraction. A convex-squircle edge, Snell's law (air n=1.0 entering glass n=1.5), and signed-distance fields, compiled into a per-element displacement map. This is the optics implemented, not the optics imitated.

🪶 Zero-dependency core. One JS file, two CSS files. No build step, no framework, no npm account. A <script> tag gets you glass.

🎛️ Live-tunable material. Refraction, bezel, blur, saturation, specular, tint hue and opacity. All adjustable at runtime through LiquidGlass.set().

✨ Motion-reactive specular. Highlights glide with the pointer, or with device tilt on mobile. The same cue you get from tilting an iPhone.

🧩 Apple's real vocabulary. Regular and Clear variants, semantic tints, press illumination, morph containers.

♿ Accessible by default. Honors prefers-reduced-transparency (opaque fallback, GPU work skipped), prefers-reduced-motion, and prefers-contrast.

📱 Five platforms, one mental model. The same parameters produce the same pixels on Web, React, React Native (Skia shader), Flutter (GLSL shader), and SwiftUI (Apple's native glassEffect).

🤖 AI-ready. Ships AI_CONTEXT.md plus five agent skills, so AI coding assistants build correct Liquid Glass from this repo on the first attempt.

🚀 Quick start (30 seconds to glass)

<link rel="stylesheet" href="packages/core/tokens.css">
<link rel="stylesheet" href="packages/core/liquid-glass.css">

<div class="lg-glass" data-glass style="--lg-radius:28px; padding:24px;">
  Hello, glass.
</div>

<script src="packages/core/liquid-glass.js"></script>
<script>LiquidGlass.init({ refraction: 18, bezel: 22, blur: 3 });</script>

Done. A fully composited Liquid Glass pane with working edge refraction. More recipes:

<!-- Clear variant over bright media (scrim keeps text legible) -->
<div class="lg-glass lg-clear" data-glass><span class="lg-scrim"></span> Play ▶ </div>

<!-- Semantic tint + press illumination -->
<button class="lg-glass lg-btn lg-tint-blue lg-press" data-glass>Confirm</button>

<!-- Tune the physics live -->
<script>LiquidGlass.set({ refraction: 34, tintHue: 280 });</script>

Prefer npm? npm i @liquidlens/core, then import LiquidGlass from '@liquidlens/core'.

🌍 One engine, five platforms

Platform	Package	How refraction happens	Fallback
🌐 Web / vanilla JS	packages/core	SVG feDisplacementMap as backdrop-filter	blur + specular (Safari/Firefox)
⚛️ React	packages/react	<LiquidGlass> + useLiquidGlass over the core	same as web
📱 React Native	packages/react-native	@shopify/react-native-skia SkSL runtime shader	expo-blur glassmorphism
🐦 Flutter	packages/flutter	bundled GLSL fragment shader (liquid_glass.frag)	BackdropFilter blur
🍎 SwiftUI	packages/swiftui	Apple's native .glassEffect (iOS 26+)	.ultraThinMaterial (pre-iOS 26)

⚛️ React: show me the code

import { LiquidGlass, useLiquidGlass } from '@liquidlens/react';
import '@liquidlens/core/liquid-glass.css';

function Card() {
  const { set } = useLiquidGlass({ refraction: 18, bezel: 22, blur: 3 });
  return <LiquidGlass radius={28} tint="blue" interactive>Hello</LiquidGlass>;
}

📱 React Native: show me the code

import { LiquidGlassSkia } from '@liquidlens/react-native';

<LiquidGlassSkia width={300} height={160} radius={28} refraction={18} bezel={22}>
  <Text style={{ color: 'white' }}>Hello</Text>
</LiquidGlassSkia>

🐦 Flutter: show me the code

await LiquidGlassRefractive.load();          // once at startup
LiquidGlassRefractive(
  size: const Size(280, 160), borderRadius: 30, refraction: 18, bezel: 22,
  child: const Center(child: Text('Hello', style: TextStyle(color: Colors.white))),
);

🍎 SwiftUI: show me the code

Text("Hello").padding()
    .liquidGlass()                                    // native .glassEffect on iOS 26+
Button("Save") {}.liquidGlassStyle(prominent: true, tint: .blue)

🖼️ Showcase gallery

Six production-quality screens. Each one is a single self-contained HTML file. Open in Chrome, Edge, or Arc. No build step.

🎵 Music player	🔒 Lock screen	⛅ Weather
🎛️ Control Center	📊 Dashboard	🧪 Playground

The examples/ folder adds 14 focused component demos: buttons, toolbars, docks, segmented controls, sliders, notifications, search bars, modals, chips, side panels, tooltips.

🧠 How the refraction works (the 60-second physics)

1. Model the glass edge as a convex squircle: height(x) = (1 − (1−x)⁴)^¼. Apple builds its shapes on this superellipse.
2. Across the edge band, apply Snell's law (n₁ sin θ₁ = n₂ sin θ₂, air into glass at 1.5) to get each ray's deflection.
3. Read every pixel's depth and outward direction from a rounded-rect signed distance field.
4. Encode the deflections into a bitmap. Red = X shift, Green = Y shift, 128 = neutral.
5. feDisplacementMap shifts the backdrop by ((R−128)/127) × scale. The background magnifies at the rim, the way it does through real glass.

The same model ships as an SkSL shader for React Native and a GLSL fragment shader for Flutter, so refraction: 18 means the same 18 pixels on every platform. Full math with code: docs/02-optics-and-physics.md.

🎯 Why I built this

Built by Ashutosh Sharma, aka DevBehindYou. Developer at heart, SEO specialist by mind, analyst by habit. "I Engineer Visibility."

When Apple unveiled Liquid Glass at WWDC 2025, I went hunting for a faithful web implementation. I found an ocean of blur(12px) tutorials wearing the name. The lensing, the one behavior that makes the material read as alive, was missing from every single one. Nothing spanned the platforms a real product ships on either.

So I did it the hard way. I read the physics, reverse-engineered the displacement-map technique, and verified the output pixel by pixel in a real rendering engine: 20 pages, zero console errors, refraction confirmed on every glass element before I called it done. Then I wrapped the whole thing in Apple's own design vocabulary (Regular and Clear, tints, interactive, morph) and ported one optical model to Skia, GLSL, and Apple's native API.

The goal: any developer, or any AI agent, should ship correct and accessible Liquid Glass in minutes, on any platform, with no PhD in optics required. This repo is the library plus the complete knowledge base behind it.

📚 Documentation

Start with the friendly ELI5 explainer 🧒. Then go as deep as you want:

Learn	Build	Master
What is Liquid Glass?	Web implementation guide	Full API reference
Optics & physics	Design tokens & theming	Cross-platform guide
Material anatomy	Regular vs Clear variants	Browser support & perf
UI/UX guidelines (HIG)	Accessibility	FAQ

🤖 For AI agents: AI_CONTEXT.md is a dense machine-readable spec, and skills/ carries five ready-to-use skills (web, React, Flutter, SwiftUI builders, plus a QA auditor).

❓ FAQ

Why does my glass render as plain blur in Safari or Firefox?

Using an SVG filter as a backdrop-filter (the refraction path) currently works in Chromium engines: Chrome, Edge, Arc, Brave, Opera. Safari and Firefox fall back automatically to blur + specular, which still reads as quality glass. Apple's native platforms refract everywhere. That gap is the reason the SwiftUI port calls the system glassEffect instead of imitating it. Details →

How is this different from a glassmorphism CSS generator?

Generators output a blur, a tint, and a border. LiquidLens adds the missing physics: a per-element displacement map bends the backdrop at the edges, the optical signature of Apple's material. See the comparison above.

My glass is invisible. Why?

Two usual causes. The element sits over a flat background (glass needs a rich backdrop to refract: gradients, photos, text). Or blur is set so high it erases the lensing. Keep blur between 0 and 4 px.

Does it hurt performance?

Displacement maps are generated on create and resize only, capped by the quality parameter. Animate transform and scale, which stay cheap. Prefer a few large panes over dozens of tiny ones. Performance model →

Is it accessible?

Yes. prefers-reduced-transparency swaps in an opaque surface and skips the GPU work. prefers-reduced-motion freezes highlights. prefers-contrast strengthens edges. Accessibility guide →

Can I use it in production?

The core is dependency-free, MIT-licensed, and degrades cleanly. Treat the refraction as progressive enhancement (Chromium gets the full effect), keep text contrast WCAG-compliant, and you are production-ready. The RN Skia and Flutter shader paths are marked experimental. Test those on your target devices first.

Does it work with Tailwind / Next.js / Vue / Svelte?

Yes. The core is framework-agnostic. Any element carrying class="lg-glass" data-glass works. The React package adds idiomatic bindings. Other frameworks can call LiquidGlass.apply(el) directly.

🤝 Contributing

PRs welcome. The bar lives in CONTRIBUTING.md. Short version: refraction is non-negotiable, accessibility ships with the feature, and the core stays dependency-free. Found a bug? Open an issue with a screenshot over a busy background.

⭐ Star the repo if this saved you time. Stars are how other developers find real Liquid Glass.

📄 License

MIT © Ashutosh Sharma (DevBehindYou). "Liquid Glass" is Apple's design language. LiquidLens is an independent, educational implementation, not affiliated with or endorsed by Apple Inc.

---

<sub>LiquidLens · Apple Liquid Glass UI library · iOS 26 glass effect · CSS refraction · glassmorphism, evolved
Web · React · React Native · Flutter · SwiftUI. Made with Snell's law and love for the craft.

Built by DevBehindYou (Ashutosh Sharma) · GitHub · LinkedIn · Medium · X</sub>