liquid-glass.js: iOS Liquid Glass Web Component with SVG & WebGL

Authorozcanyldzhn

Last UpdateSeptember 1, 2026

LicenseMIT

Features

SVG displacement and WebGL rendering modes.
Content-based sizing and fixed pixel dimensions.
Pointer and touch dragging with viewport boundaries.
Shadow DOM encapsulation and unique SVG filter IDs.
Four curvature profiles for different glass shapes.
Tint, blur, specular, bezel, and shadow controls.
Multiple independent glass elements on one page.
Vanilla JavaScript, React, Vue, and TypeScript support.

How To Use It

Installation

Load the stylesheet and ES module before placing <liquid-glass> elements in the page.

<link
  rel="stylesheet"
  href="https://unpkg.com/@ozcanyldzhn/liquid-glass-js/dist/liquid-glass.css"
/>
<script
  type="module"
  src="https://unpkg.com/@ozcanyldzhn/liquid-glass-js/dist/liquid-glass.js">
</script>

You can also install the package from NPM and import the component as follows:

npm install @ozcanyldzhn/liquid-glass-js

import '@ozcanyldzhn/liquid-glass-js';
import '@ozcanyldzhn/liquid-glass-js/css';

Basic Usage

Place the component over a visible image, gradient, or detailed page background.

<div class="demo-stage">
  <liquid-glass
    width="380"
    height="220"
    radius="32"
    ior="2.7"
    thickness="85"
    bezel="48"
  >
    <div class="glass-copy">
      <h3>Weather</h3>
      <p>72°F · Clear</p>
    </div>
  </liquid-glass>
</div>
<style>
.demo-stage {
  min-height: 500px;
  display: grid;
  place-items: center;
  background: url("mountains.jpg") center / cover;
}
.glass-copy {
  padding: 24px;
  color: #fff;
}
</style>

Create an Auto-Sized Glass Control

Leave width and height unset when the Liquid Glass effect should follow its content.

<liquid-glass
  radius="22"
  ior="2.5"
  thickness="55"
>
  <span class="player-action">Now Playing</span>
</liquid-glass>
<style>
.player-action {
  display: block;
  padding: 10px 20px;
  color: #fff;
  font-weight: 600;
}
</style>

Create a Draggable Tinted Card

Set draggable="true" for pointer and touch movement. The component constrains movement to the available viewport area.

<liquid-glass
  width="420"
  height="240"
  radius="36"
  ior="3"
  thickness="100"
  bezel="55"
  tint-color="#7c3aed"
  tint-opacity="12"
  draggable="true"
>
  <div class="glass-widget">
    <h3>Media Controls</h3>
    <p>Drag this panel around the screen.</p>
  </div>
</liquid-glass>

Configuration Options

The main <liquid-glass> element accepts these attributes.

width (number|string, default: auto): Fixed width in pixels. Omit it for content-based sizing.
height (number|string, default: auto): Fixed height in pixels. Omit it for content-based sizing.
radius (number|string, default: 24): Corner radius in pixels.
ior (number|string, default: 3.0): Refraction strength from 1.0 to 3.0.
thickness (number|string, default: 80): Simulated glass depth from 10 to 200.
bezel (number|string, default: 60): Width of the refractive edge from 5 to 100.
surface-fn (string, default: convex_squircle): Surface profile. Available values are convex_squircle, convex_circle, concave, and lip.
blur (number|string, default: 0): Backdrop blur in pixels.
tint-color (string, default: #ffffff): Hex color used for the glass tint.
tint-opacity (number|string, default: 0): Tint opacity from 0 to 100.
specular-opacity (number|string, default: 0): Specular reflection intensity from 0.0 to 1.0.
outer-shadow-blur (number|string, default: 24): Blur radius for the outer shadow.
draggable (boolean, default: false): Activates pointer and touch dragging.
engine (string, default: svg): Selects the svg or webgl rendering engine.

Styling the Glass Content

Refraction, tint, blur, radius, and lighting belong on the <liquid-glass> element. Page CSS controls the HTML placed inside its slot.

<liquid-glass
  radius="28"
  tint-color="#0ea5e9"
  tint-opacity="8"
>
  <div class="profile-glass">
    <img src="avatar.jpg" alt="Profile photo">
    <span>Alex Morgan</span>
  </div>
</liquid-glass>

.profile-glass {
  display: flex;
  align-items: center;
  gap: 12px;
  padding: 12px 18px;
  color: #fff;
}
.profile-glass img {
  width: 36px;
  height: 36px;
  border-radius: 50%;
  object-fit: cover;
}

React and Next.js

React projects can import LiquidGlassReact from the package’s React entry point. Next.js components that render it need to run on the client.

'use client';
import { LiquidGlassReact } from '@ozcanyldzhn/liquid-glass-js/react';
import '@ozcanyldzhn/liquid-glass-js/css';
export default function StatusCard() {
  return (
    <LiquidGlassReact
      width={360}
      height={200}
      radius={30}
      thickness={80}
      bezel={45}
      ior={2.8}
      tintOpacity={6}
    >
      <div style={{ padding: '22px', color: '#fff' }}>
        <h3>System Status</h3>
        <p>All services operational</p>
      </div>
    </LiquidGlassReact>
  );
}

Vue and Nuxt

Vue can use the custom element after the package import. Nuxt pages should render the browser-dependent component inside <ClientOnly>.

<script setup>
import '@ozcanyldzhn/liquid-glass-js';
import '@ozcanyldzhn/liquid-glass-js/css';
</script>
<template>
  <ClientOnly>
    <liquid-glass
      width="360"
      height="200"
      radius="30"
      ior="2.8"
      tint-opacity="6"
    >
      <div class="account-card">
        Account Overview
      </div>
    </liquid-glass>
  </ClientOnly>
</template>
<style scoped>
.account-card {
  padding: 22px;
  color: white;
}
</style>

Alternatives

FAQs

Q: Why does the Liquid Glass effect look weak on my page?
A: Place the component over a background with visible detail. Higher ior, thickness, and bezel values produce a stronger refractive appearance.

Q: Can I place several Liquid Glass elements on one page?
A: Yes. Each instance receives its own SVG filter ID and Shadow DOM.

Q: What is the difference between the SVG and WebGL engines?
A: SVG is the default rendering mode and uses displacement mapping. Set engine="webgl" when the WebGL rendering mode better suits the background and visual treatment.