---
title: "Introduction"
description: "What this library is, why it exists and how it works under the hood."
canonical_url: "https://liquid-glass.bodbod.ir/docs/getting-started/introduction"
---
# Introduction

> What this library is, why it exists and how it works under the hood.

`@mahbodhastam/liquid-glass` is a set of Vue 3 components and a Nuxt module that put a glass lens on top of an image, a video or a chunk of your page. The lens bends and magnifies what's behind it, splits colours slightly at the edges, adds a bit of grain and catches a highlight on the rim. It's the look Apple calls "liquid glass".

The effect is drawn by a WebGL2 shader, so it looks the same in Chrome, Firefox and Safari.

<code-preview>
<glass-demo>



</glass-demo>

<template v-slot:code="">

```vue
<script setup lang="ts">
import { LiquidGlass } from '@mahbodhastam/liquid-glass'

const backdrop = ref<HTMLImageElement | null>(null)
</script>

<template>
  <div class="relative grid place-items-center overflow-hidden rounded-2xl">
    <img ref="backdrop" src="/backdrop.jpg" alt="" class="absolute inset-0 size-full object-cover">
    <LiquidGlass
      :source="backdrop"
      :blur="0"
      :refraction="1"
      :zoom="1.1"
      :aberration="0.5"
      class="relative rounded-3xl px-10 py-6 font-semibold text-white"
    >
      Drag me
    </LiquidGlass>
  </div>
</template>
```

</template>
</code-preview>

<tip>

There are more examples in the playground. Clone the [repository](https://github.com/MahbodHastam/liquid-glass) and run `pnpm install && pnpm build && pnpm dev` for the Vite playground, or `pnpm dev:nuxt` for the Nuxt one.

</tip>

## Why a shader

The usual way to fake this on the web is an SVG displacement filter used as a `backdrop-filter`. That only works in Chromium. Safari and Firefox ignore it, so you end up with a plain blur.

This library skips the filter and does the refraction itself on the GPU. The cost is that it needs something to refract.

## How it works

### 1. It needs a picture of what's behind the glass

A canvas can't see the pixels that sit behind it on the page, and neither can WebGL. So each lens is given a [backdrop source](https://liquid-glass.bodbod.ir/docs/guide/backdrops) to read from:

- an `<img>`, `<video>` or `<canvas>` you pass in with `:source`, or
- a snapshot of any HTML, taken by wrapping it in `<LiquidGlassBackdrop>`.

That source is uploaded to the GPU as a texture. Scrolling the page just moves the lens over that texture, so nothing is re-uploaded while you scroll.

### 2. The backdrop is blurred once

If `blur` is above zero, the texture goes through a dual Kawase blur: it is shrunk a few times and scaled back up. That costs far less than a large Gaussian kernel. The result is cached and only redone when the backdrop itself changes.

### 3. The glass pass

For every pixel of the lens, the shader works out where that pixel sits relative to the lens shape, a rounded rectangle whose radius comes from your CSS `border-radius`. That gives it three things:

- A mask that gives clean, anti-aliased corners.
- A bevel. The lens is flat in the middle and curves steeply near the rim, following a quarter-circle profile.
- The direction the surface faces, which is where light bends.

Then it samples the backdrop. The sample point is pulled toward the centre by `zoom` and pushed along the surface direction by `refraction`, more strongly near the rim. That's the bending you see.

With `aberration` on, red and blue are read from slightly different points than green, which gives the coloured fringe. After that come the frost grain, your tint, a specular highlight that faces `lightAngle`, and an inner edge glow.

With aberration off the pass reads the texture once per pixel instead of three times, and that code is compiled out of the shader entirely.

### 4. One context for the whole page

Browsers limit how many WebGL contexts a page can hold, so every lens shares a single hidden WebGL2 canvas. It draws a lens, hands the result to that lens's own small canvas, then moves on to the next one. Where the browser supports it, the pixels are passed over with `transferToImageBitmap` rather than copied. When the last lens unmounts, the context is released.

### 5. Frames only happen when something changed

There's no animation loop. A frame is requested when something actually changed: a prop, the lens moving or resizing, the pointer moving over an interactive lens, a new video frame. If nothing is happening, the library makes no `requestAnimationFrame` calls and no GL calls at all. Lenses that are off-screen, and tabs in the background, don't render.

### 6. Server render and fallbacks

On the server there's no WebGL, so `<LiquidGlass>` renders a normal element styled with CSS `backdrop-filter`. After the component mounts it upgrades to the shader, and the markup doesn't change in a way that causes hydration warnings.

The CSS version also stays in place whenever the shader can't or shouldn't run: no WebGL2, a lost context, a cross-origin image without CORS, or a user preference such as reduced transparency. See [Accessibility](https://liquid-glass.bodbod.ir/docs/guide/accessibility) for the full list.

## What it doesn't do

- It can't refract live, arbitrary DOM for free. Snapshots are rasterised copies and have [limits](https://liquid-glass.bodbod.ir/docs/guide/backdrops#snapshot-limitations).
- It doesn't guarantee your text is readable. That's down to your tint and your backdrop. See [legibility](https://liquid-glass.bodbod.ir/docs/guide/accessibility#legibility-is-your-responsibility).
- There's no WebGL1 path. Without WebGL2 you get the CSS fallback.
- Real-device mobile performance numbers haven't been measured yet. See [Performance](https://liquid-glass.bodbod.ir/docs/guide/performance).

## Requirements

- Vue 3.4 or newer, tested on 3.4 and 3.5
- Nuxt 3.13 or newer, including Nuxt 4
- A browser with WebGL2: Chrome, Edge, Firefox, or Safari 15+ on desktop and iOS


## Sitemap

See the full [sitemap](https://liquid-glass.bodbod.ir/sitemap.md) for all pages.
