# Using @colineapp/liquid-glass

For coding agents adding Liquid Glass to a web app. Liquid Glass for the web: the rim refraction, light and motion of iOS 27's glass on any rounded element, with React bindings and tabs whose thumb lifts into a lens. MIT.

Version 0.1.0. Every option has a plain-text page under https://liquid-glass.coline.space/docs/options/; the index is https://liquid-glass.coline.space/llms.txt.

## Install

```sh
npm install @colineapp/liquid-glass
```

Import the stylesheet once, at the app's root:

```ts
import "@colineapp/liquid-glass/styles.css";
```

## Pick the entry point

- React: `import { LiquidGlass, useLiquidGlass, useLiquidGlassTabs } from "@colineapp/liquid-glass/react"`.
- Anything else: `import { createLiquidGlass, attachLiquidGlassTabs } from "@colineapp/liquid-glass"`.
- With a class-based dark mode (Tailwind `dark:`, next-themes), pass `appearance="class"`. Otherwise the glass follows prefers-color-scheme.

## Pick the options

| Surface | Options |
| --- | --- |
| Nav bar, toolbar, card | none, or `interactive` if it holds controls |
| Search field, button you press | `interactive swell` |
| Menu, popover | `floating`, and `materialize()` on open |
| Dialog, sheet | `floating="dialog"`, `fit="scroll"` if it scrolls itself |
| Glass over a photo or video | `variant="clear"` |
| Tinted glass | `hue="#3d6bff"` |
| Segmented control, tab bar | `useLiquidGlassTabs(trackRef)` on your own tabs |
| A magnifying lens | `variant="lens" geometry={LENS_GEOMETRY} samples={4}`, then `magnify()` |

## Rules that keep the glass working

- Put the glass first inside a positioned (relative, absolute or fixed), rounded element. It takes the element's corner radius and follows its size.
- Paint nothing over it: no background, border or box-shadow on the surface. The glass draws its own edge.
- No opacity below 1, filter, mask or backdrop-filter on the surface or its ancestors while the glass shows. Each makes a backdrop root, and the glass would see only that element instead of the page.
- To show or hide a surface, fade and zoom its contents, never the surface itself, and call materialize() and dematerialize() for the glass.
- Controls on glass get no glass of their own: give the selected or hovered one the liquid-glass-well class.
- Rim refraction renders in Chromium. Safari and Firefox get the same material, light and motion without the bend.

## Checking your work

- The surface element has `data-liquid-glass="dark"` or `"light"` once the glass is attached, and its glass child has `data-ready` once the rim is built.
- In Chromium the glass child also has `data-refraction`. If the glass looks flat grey or empty, an ancestor has opacity, a filter, a mask or a backdrop-filter.
- Don't put a background colour on the surface to make it look glassy: the glass is the background.

## Examples

### A glass toolbar in React

Render <LiquidGlass /> first inside a positioned, rounded element.

```tsx
import { LiquidGlass } from "@colineapp/liquid-glass/react";
import "@colineapp/liquid-glass/styles.css";

export function Toolbar() {
  return (
    <nav className="relative flex gap-1 rounded-full p-1.5">
      <LiquidGlass appearance="class" interactive />
      <button className="liquid-glass-well rounded-full px-4 py-2">Today</button>
      <button className="rounded-full px-4 py-2">Week</button>
    </nav>
  );
}
```

### Without React

createLiquidGlass inserts the glass as the element's first child.

```ts
import { createLiquidGlass } from "@colineapp/liquid-glass";
import "@colineapp/liquid-glass/styles.css";

const glass = createLiquidGlass(document.querySelector(".toolbar")!, {
  interactive: true,
});

glass.update({ variant: "clear" });
glass.destroy();
```

### Pill tabs

Your tabs, your selection; the thumb follows aria-selected.

```tsx
import { useRef } from "react";
import { useLiquidGlassTabs } from "@colineapp/liquid-glass/react";

export function Period({ value, onChange }: { value: string; onChange: (value: string) => void }) {
  const track = useRef<HTMLDivElement>(null);
  useLiquidGlassTabs(track, { appearance: "class" });
  return (
    <div ref={track} role="tablist" className="flex rounded-full p-1">
      {["Day", "Week", "Month"].map((label) => (
        <button key={label} role="tab" aria-selected={label === value} onClick={() => onChange(label)}
          className="rounded-full px-4 py-1.5 text-sm font-medium">
          {label}
        </button>
      ))}
    </div>
  );
}
```

### A menu that materializes

Fade the contents, never the surface; the glass grows from clear.

```tsx
import { useEffect, useRef, useState } from "react";
import { LiquidGlass, type LiquidGlassHandle } from "@colineapp/liquid-glass/react";

export function Menu({ open, items }: { open: boolean; items: string[] }) {
  const glass = useRef<LiquidGlassHandle | null>(null);
  const [active, setActive] = useState(-1);
  useEffect(() => {
    if (open) void glass.current?.materialize({ duration: 240, scale: 0.96 });
  }, [open]);
  if (!open) return null;
  return (
    <div role="menu" className="absolute right-0 top-12 w-56 rounded-2xl p-1.5">
      <LiquidGlass glassRef={glass} appearance="class" floating />
      {items.map((item, index) => (
        <button key={item} role="menuitem" onPointerEnter={() => setActive(index)}
          className={`w-full rounded-xl px-3 py-2 text-left ${index === active ? "liquid-glass-well" : ""}`}>
          {item}
        </button>
      ))}
    </div>
  );
}
```

### A glass dialog

floating="dialog" casts the deeper shadow; the glass materializes as the contents zoom in.

```tsx
import { useLayoutEffect, useRef } from "react";
import { LiquidGlass, type LiquidGlassHandle } from "@colineapp/liquid-glass/react";

export function ShareDialog({ onClose }: { onClose: () => void }) {
  const glass = useRef<LiquidGlassHandle | null>(null);
  useLayoutEffect(() => {
    void glass.current?.materialize({ duration: 280, scale: 0.95 });
  }, []);
  const close = () => void glass.current?.dematerialize({ duration: 180, scale: 0.97 }).then(onClose);
  return (
    <div role="dialog" aria-modal="true" className="fixed left-1/2 top-1/3 w-80 -translate-x-1/2 rounded-[28px] p-5">
      <LiquidGlass glassRef={glass} appearance="class" floating="dialog" />
      <h2 className="font-semibold">Share this album</h2>
      <button className="liquid-glass-well mt-4 h-10 w-full rounded-full" onClick={close}>Copy link</button>
    </div>
  );
}
```

### A search field that swells

interactive lights it under the pointer; swell springs it on press.

```tsx
<label className="relative flex h-11 items-center gap-2 rounded-full px-4">
  <LiquidGlass appearance="class" interactive swell />
  <SearchIcon />
  <input className="bg-transparent outline-none" placeholder="Search" />
</label>
```

### A magnifying lens

The tab lens on its own: the lens variant, its geometry, four samples and magnify().

```tsx
import { useRef } from "react";
import { LENS_GEOMETRY } from "@colineapp/liquid-glass";
import { LiquidGlass, type LiquidGlassHandle } from "@colineapp/liquid-glass/react";

export function Lens() {
  const lens = useRef<LiquidGlassHandle | null>(null);
  return (
    <div
      className="absolute size-24 rounded-full"
      onPointerDown={() => lens.current?.magnify(1.15)}
      onPointerUp={() => lens.current?.magnify(1)}
    >
      <LiquidGlass glassRef={lens} appearance="class" variant="lens" geometry={LENS_GEOMETRY} samples={4} />
    </div>
  );
}
```