# @colineapp/liquid-glass

> 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. Install: `npm install @colineapp/liquid-glass`. npm: https://www.npmjs.com/package/@colineapp/liquid-glass. Playground: https://liquid-glass.coline.space.

Liquid Glass is a material, not a component library: put `<LiquidGlass />` first inside any positioned, rounded element and it becomes glass. Every option below has its own plain-text page.

## Docs

- [Agents guide](https://liquid-glass.coline.space/agents.md): how to use the package correctly, with the rules that keep the glass from blanking
- [Full reference](https://liquid-glass.coline.space/docs/api.md): every option, geometry field, method and export
- [Everything in one file](https://liquid-glass.coline.space/llms-full.txt)
- [Reference as JSON](https://liquid-glass.coline.space/options.json)

## Examples

- [A glass toolbar in React](https://liquid-glass.coline.space/docs/examples/react.md): Render <LiquidGlass /> first inside a positioned, rounded element.
- [Without React](https://liquid-glass.coline.space/docs/examples/vanilla.md): createLiquidGlass inserts the glass as the element's first child.
- [Pill tabs](https://liquid-glass.coline.space/docs/examples/tabs.md): Your tabs, your selection; the thumb follows aria-selected.
- [A menu that materializes](https://liquid-glass.coline.space/docs/examples/menu.md): Fade the contents, never the surface; the glass grows from clear.
- [A glass dialog](https://liquid-glass.coline.space/docs/examples/dialog.md): floating="dialog" casts the deeper shadow; the glass materializes as the contents zoom in.
- [A search field that swells](https://liquid-glass.coline.space/docs/examples/search.md): interactive lights it under the pointer; swell springs it on press.
- [A glass card](https://liquid-glass.coline.space/docs/examples/card.md): Regular glass on a rounded box: the rim bends what crosses it, and the body keeps the card's text legible.

## Options

- [Glass options: appearance](https://liquid-glass.coline.space/docs/options/appearance.md): `system` follows prefers-color-scheme
- [Glass options: variant](https://liquid-glass.coline.space/docs/options/variant.md): `regular` diffuses and evens out the page so text on the glass stays legible over anything
- [Glass options: floating](https://liquid-glass.coline.space/docs/options/floating.md): For menus, popovers, dialogs and sheets
- [Glass options: interactive](https://liquid-glass.coline.space/docs/options/interactive.md): For glass that holds controls, like SwiftUI's `.glassEffect(.regular.interactive())`: the pointer warms the glass beneath it, and a press blooms out from there
- [Glass options: swell](https://liquid-glass.coline.space/docs/options/swell.md): For glass you press, like a search field: pressed, the surface swells about its centre on the tabs' spring and springs back with a slight overshoot on release
- [Glass options: tint](https://liquid-glass.coline.space/docs/options/tint.md): Colour washed over the body by the tone's `tint` share (50% on dark regular glass, 40% on light)
- [Glass options: hue](https://liquid-glass.coline.space/docs/options/hue.md): A colour whose hue the glass takes on, like tinted iOS glass: each pixel beneath shifts toward the hue at its own brightness, so colours behind keep their chroma
- [Glass options: hueStrength](https://liquid-glass.coline.space/docs/options/hueStrength.md): How much of the hue the glass takes
- [Glass options: geometry](https://liquid-glass.coline.space/docs/options/geometry.md): The rim's shape, measured from iOS 27: its width and depth, how steeply it bends, the darkened edge and the glints
- [Glass options: tone](https://liquid-glass.coline.space/docs/options/tone.md): Per-appearance overrides of the variant's filters: body `blur`, `floatingBlur`, `saturate`, `contrast`, `brightness`, `tint` share, and the rim's `highlightContrast`, `highlightBrightness`, `shadeBrightness`, `glowSaturate`, `glowBrightness`, `edgeBrightness`
- [Glass options: fit](https://liquid-glass.coline.space/docs/options/fit.md): `box` fills the surface
- [Glass options: refraction](https://liquid-glass.coline.space/docs/options/refraction.md): Bend the page at the rim
- [Glass options: samples](https://liquid-glass.coline.space/docs/options/samples.md): Refraction samples per pixel
- [Geometry fields: bezel](https://liquid-glass.coline.space/docs/options/geometry-bezel.md): Width of the refracting rim along the top and bottom
- [Geometry fields: thickness](https://liquid-glass.coline.space/docs/options/geometry-thickness.md): Glass depth under the top and bottom rims
- [Geometry fields: sideBezel](https://liquid-glass.coline.space/docs/options/geometry-sideBezel.md): Width of the refracting rim at the sides and rounded ends
- [Geometry fields: sideThickness](https://liquid-glass.coline.space/docs/options/geometry-sideThickness.md): Glass depth under the sides and rounded ends
- [Geometry fields: refractiveIndex](https://liquid-glass.coline.space/docs/options/geometry-refractiveIndex.md): The glass's refractive index, for Snell's law at the rim
- [Geometry fields: maxFall](https://liquid-glass.coline.space/docs/options/geometry-maxFall.md): Rim bend: the steepest the rim's shift may fall per pixel inward
- [Geometry fields: edge](https://liquid-glass.coline.space/docs/options/geometry-edge.md): Width of iOS 27's darkened edge, a contour where the glass meets the air, with the hairline just inside it
- [Geometry fields: glint](https://liquid-glass.coline.space/docs/options/geometry-glint.md): Share of the hairline's light that gathers into glints where the light catches the curve, at the top-left and, fainter, the bottom-right
- [Geometry fields: hairline](https://liquid-glass.coline.space/docs/options/geometry-hairline.md): Rim hairline width
- [Geometry fields: hairlineSides](https://liquid-glass.coline.space/docs/options/geometry-hairlineSides.md): Share of the hairline's strength that reaches the sides
- [Geometry fields: shadeWidth](https://liquid-glass.coline.space/docs/options/geometry-shadeWidth.md): Width of the darkened sides
- [Geometry fields: glowReach](https://liquid-glass.coline.space/docs/options/geometry-glowReach.md): How far the inner glow reaches in from the top and bottom rims
- [Geometry fields: glowBottom](https://liquid-glass.coline.space/docs/options/geometry-glowBottom.md): Bottom glow strength relative to the top
- [The glass handle: update(options)](https://liquid-glass.coline.space/docs/options/handle-update.md): Replaces the options
- [The glass handle: magnify(factor)](https://liquid-glass.coline.space/docs/options/handle-magnify.md): Magnifies what is beneath the glass about its centre, as a raised lens does (1 for none), and sharpens it so it doesn't come out soft
- [The glass handle: materialize(timing?)](https://liquid-glass.coline.space/docs/options/handle-materialize.md): Grows the glass from clear to its tone, for surfaces that appear
- [The glass handle: dematerialize(timing?)](https://liquid-glass.coline.space/docs/options/handle-dematerialize.md): Fades the glass back to clear and holds it there, for surfaces that leave
- [The glass handle: destroy()](https://liquid-glass.coline.space/docs/options/handle-destroy.md): Removes the glass and its filters
- [The glass handle: element](https://liquid-glass.coline.space/docs/options/handle-element.md): The glass element, the surface's first child
- [The glass handle: appearance](https://liquid-glass.coline.space/docs/options/handle-appearance.md): The resolved appearance
- [Tabs: appearance](https://liquid-glass.coline.space/docs/options/tabs-appearance.md): As for glass
- [Tabs: orientation](https://liquid-glass.coline.space/docs/options/tabs-orientation.md): Vertical tabs stack and don't scrub
- [Tabs: tabs](https://liquid-glass.coline.space/docs/options/tabs-tabs.md): Selector for the tabs inside the track
- [Tabs: isSelected](https://liquid-glass.coline.space/docs/options/tabs-isSelected.md): Whether a tab is selected
- [Tabs: onSelect](https://liquid-glass.coline.space/docs/options/tabs-onSelect.md): Selects the tab the thumb was dragged onto
- [Tabs: glass](https://liquid-glass.coline.space/docs/options/tabs-glass.md): The track's own glass, or its options
- [Tabs: refraction](https://liquid-glass.coline.space/docs/options/tabs-refraction.md): Bend the page at the rims
- [React: <LiquidGlass />](https://liquid-glass.coline.space/docs/options/react-LiquidGlass.md): Glass behind a surface's content
- [React: useLiquidGlass(ref, options)](https://liquid-glass.coline.space/docs/options/react-useLiquidGlass.md): Turns an element you already render into a glass surface; the glass is inserted as its first child
- [React: useLiquidGlassTabs(ref, options)](https://liquid-glass.coline.space/docs/options/react-useLiquidGlassTabs.md): Liquid Glass tabs on a track you render
- [CSS: .liquid-glass-well](https://liquid-glass.coline.space/docs/options/css-liquid-glass-well.md): For a selected or hovered control on a glass surface: brightens the glass beneath it (dimmer in light), instead of glass on glass
- [CSS: --liquid-glass-shadow](https://liquid-glass.coline.space/docs/options/css-liquid-glass-shadow.md): The shadow floating glass casts
- [CSS: --liquid-glass-dialog-shadow](https://liquid-glass.coline.space/docs/options/css-liquid-glass-dialog-shadow.md): The deeper shadow of `floating: "dialog"` glass