glass.magnify(factor) magnifies what is beneath the glass about its centre, as a raised lens does (1 for none). It is cheap enough to call every frame, and sharpens what it magnifies so it doesn't come out soft.

Controls on glass

Controls on a glass surface shouldn't get glass of their own. Give the selected or hovered one the liquid-glass-well class and it brightens the glass beneath it.

<button className={selected ? "liquid-glass-well rounded-full" : "rounded-full"}>Today</button>

For the rows of a menu or list, attachLiquidGlassHighlight(surface) (or useLiquidGlassHighlight(ref)) adds a well that slides to the row under the pointer or with focus. Each edge rides its own spring, so it stretches toward the row it is heading for and gathers up as it lands. It finds menu items and options by default; pass items for other rows.

Menus that pour out of their button

On iOS 27 a menu is its button, grown: the button becomes a drop of glass that inflates into the menu over it, and closing, the menu shrinks back into the button as a drop, which bulges as it takes it back. pourFrom() and drawBack() do that with the surface's own glass, so it is the same glass on every frame, and carry the contents inside it.

const glass = useRef<LiquidGlassHandle | null>(null);
const button = useRef<HTMLButtonElement>(null);

// Once the menu is shown and placed:
useLayoutEffect(() => {
  if (open && button.current) void glass.current?.pourFrom(button.current, { cover: true });
}, [open]);

async function close() {
  // false if it was reopened while drawing back.
  if (await glass.current?.drawBack()) setShown(false);
}

<div role="menu" className="absolute rounded-3xl p-1.5">
  <LiquidGlass glassRef={glass} floating />
  …
</div>;

• cover: true moves the menu over its button, as iOS 27's menus sit, for buttons up to 56px tall. Leave it off for a popover anchored to a field it mustn't hide; it still grows out of the field.
• Pass a point ({ x, y }, client pixels) for a context menu, and submenu: true for a sub-menu, which unfolds out of its own edge beside its row and folds back faster.
• side says which side of the source the surface sits on; it is measured when left out.
• The menu's corners pass through every radius from 4 to 48px. Floating glass builds them ahead of time when it first appears; if your menus mount only as they open, call prewarmLiquidGlass() at startup so the first one pours out sharp.

Tabs

A horizontal track is iOS 27's segmented control, measured frame by frame from SwiftUI recordings. The selected tab is a solid thumb, white in light and grey in dark. Choosing a tab, it clears from the centre out into a clear lens larger than the track, over the labels, which bend at its rim; it stretches along its path with its speed, hangs at the tab it reached for a moment, and drops back in, refilling from the rim. Pressing the selected tab lifts it in place, and dragging it scrubs across the others. A change of tab the viewer didn't make, such as a route change, slides flat. A vertical list is a sidebar instead: its selected tab is a well in the glass, and its lens grows less.

import { LiquidGlassTabLabel, useLiquidGlassTabs } from "@colineapp/liquid-glass/react";

export function Period({ value, onChange }) {
  const track = useRef(null);
  useLiquidGlassTabs(track);
  return (
    <div ref={track} role="tablist" className="flex rounded-full p-0.5">
      {["Day", "Week", "Month"].map((label) => (
        <button key={label} role="tab" aria-selected={label === value} onClick={() => onChange(label)}>
          <LiquidGlassTabLabel>{label}</LiquidGlassTabLabel>
        </button>
      ))}
    </div>
  );
}

Without React, attachLiquidGlassTabs(track, options) does the same and returns update() and destroy().

• Your tabs and selection stay yours. The thumb follows aria-selected, aria-checked or Radix's data-state="active"; pass isSelected for anything else.
• A tab the thumb is dragged onto gets pressed and clicked, as a pointer would. Pass onSelect to handle it yourself.
• The selected label is semibold, and so is the one a drag would land on. LiquidGlassTabLabel holds each label at its semibold width, so tabs don't change width; without React, mark a label up as <span class="liquid-glass-tabs-label" data-text="Week"><span>Week</span></span>.
• Give every label the same, primary text colour: the thumb alone marks the selection, as on iOS 27, and muted labels turn muddy over coloured glass.
• On another glass surface the track gets no glass of its own: it becomes a recessed tint. glass: true or false decides it yourself.
• --liquid-glass-tabs-tint sets the track's wash, and --liquid-glass-tabs-fill the thumb's colour.
• orientation: "vertical" stacks the tabs. Vertical tabs don't scrub.

Appearing and leaving

materialize() grows the glass from clear to its tone, and dematerialize() fades it back and holds it there, so a dialog or sheet can open and close without fading its surface. Wells on it ease back to clear glass as it leaves. Both ease out on a cubic curve, 240ms in and 180ms out by default: on a steeper curve half of an opening lands in its first frame, and the glass seems to pop.

For a surface that zooms as it opens, scale its contents and pass the same scale: the glass grows by its inset instead, since scaling it blanks it.

const glass = useRef<LiquidGlassHandle | null>(null);
useLayoutEffect(() => {
  if (open) void glass.current?.materialize({ scale: 0.965 });
}, [open]);

<LiquidGlass glassRef={glass} floating="dialog" />;

For CSS-driven animations, run the liquid-glass-materialize and liquid-glass-dematerialize keyframes on .liquid-glass-layer.

Accessibility

• prefers-reduced-transparency replaces the glass with a solid fill of the tint colour.
• prefers-contrast: more darkens the sides and turns the edge into a contrasting border.
• prefers-reduced-motion keeps the tab thumb from lifting and travelling, the glass from swelling, and menus from pouring: a covered button still becomes its menu, at once.
• forced-colors hides the glass and outlines the selected tab.

How it works

The rim is a squircle-shaped bevel. For each pixel across it, a view ray meets the tilted surface, refracts by Snell's law and travels through the glass to the page. The shift is capped wherever it would fall faster than maxFall times the rim moving inward. Past 1, neighbouring pixels would sample in reverse and fold the page into mirrored echoes; lower caps bend more gently, which the tab lens uses so labels crossing its rim don't smear. On small glass the top and bottom rims stop short of the middle (rimShare), so the body shows the page as it is. The result becomes an feDisplacementMap in a layer of its own over the body, masked to where the rim bends: the displacement takes the nearest pixel, and run over the whole body it drew the page coarser than the page itself on some GPUs. Four more masks draw the rim hairline, darkened sides, inner glow, and the darkened edge where the glass meets the air. Part of the hairline gathers into glints where a light from the top-left catches the curve, fainter where it returns at the bottom-right.

The lens is rendered once per corner radius as a rounded square of side 2r + 1 and cut into nine slices. Fixed corners and stretched edges assemble it over a box of any size, so surfaces can resize and change radius while the glass stays on. Glass of another outline is rendered whole: each pixel is shaded from its distance to the nearest point of the outline and the outline's normal there.

The tab thumb's centre and size ride one spring, as UIKit's do, and its stretch follows its speed a beat behind. A pouring menu's width, height and corner each ride their own: its height leads and overshoots, its width follows, and the corners stay round in flight and tighten as it lands. Every spring steps at a fixed 240 Hz, so motion is the same at any frame rate.

createGlassSlices() and createShapedGlass() expose the lens as raw pixels if you want to use it somewhere else.

Known gaps

This is a close approximation of Apple's glass, not a copy. Pull requests are welcome for any of these:

• Separate glass doesn't merge. Apple's glass merges and splits as surfaces move near each other. Here glass swells when pressed and leans when dragged, the tab thumb stretches as it travels, and a menu pours out of its button as one drop, but two surfaces never flow into each other.
• Light doesn't follow the device. The rim's glints are lit from a fixed top-left light. They don't move with the pointer or device tilt.
• Refraction is Chromium only. Safari and Firefox don't run SVG filters in backdrop-filter, so they get the material and rim light without the bend.
• Only the rim bends. The flat middle of the surface shows the page unmagnified, and there is no chromatic dispersion at the edge.
• One radius per rounded box. The lens takes border-top-left-radius for every corner, so a box with mixed corner radii gets the wrong rim. Draw it as a shape instead, at the cost of a build per size.
• Scaling the surface blanks it in Chromium for a few frames, so menus and dialogs can't use a scale-in animation on the surface itself (see Appearing and leaving).

Demo

The playground and docs are at https://liquid-glass.coline.space, with plain-text docs for agents at /llms.txt and /agents.md. demo/ is that site, a Coline Site built on the published package. Run it with npm install && npm run dev inside that folder.

Source

The repository is coline/liquid-glass on upstream.codes:

git clone https://git.coline.app/coline/liquid-glass.git

The package is developed inside Coline's monorepo, at packages/liquid-glass, next to the app whose glass it ships, and this repository is published from there. Issues and change requests are welcome here and get ported back. In the monorepo, scripts/sync-liquid-glass.sh republishes it. It splits packages/liquid-glass out of origin/main with git subtree split, which gives the same commits every time, and pushes the result here as main, so every sync is a fast-forward.

License

MIT