# @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, menus that pour out of their button, and segmented tabs whose thumb clears into a lens. MIT.

Version 0.2.0. Install: `npm install @colineapp/liquid-glass`. npm: https://www.npmjs.com/package/@colineapp/liquid-glass. Source: https://upstream.codes/coline/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.
- [Segmented tabs](https://liquid-glass.coline.space/docs/examples/tabs.md): Your tabs, your selection; the thumb follows aria-selected. Every label the same colour, semibold when selected.
- [A menu that pours out of its button](https://liquid-glass.coline.space/docs/examples/menu.md): The button becomes the menu, and the menu draws back into it. A pill slides under the row you point at.
- [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, swells it on press and leans it after a drag.
- [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 the page so text on the glass stays legible over anything, as clear or tinted as its `level`
- [Glass options: level](https://liquid-glass.coline.space/docs/options/level.md): How clear or tinted regular glass is, as iOS 27's Liquid Glass slider sets it: 0 is More Clear, 0.5 a light frost and a faint wash, 1 More Tinted (iOS 27's own default), anything in between
- [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, a press blooms out from there while the glass swells, and light glass floats on a faint shadow (`--liquid-glass-control-shadow`)
- [Glass options: swell](https://liquid-glass.coline.space/docs/options/swell.md): Pressed, the surface swells about its centre and springs back with a slight overshoot on release; held and dragged, it leans after the pointer like taffy, stretching along the pull
- [Glass options: shape](https://liquid-glass.coline.space/docs/options/shape.md): Glass of an outline no rounded rectangle makes: an SVG path of absolute M, L, H, V, C and Z commands in the surface's CSS pixels, or a function from its size to one
- [Glass options: tint](https://liquid-glass.coline.space/docs/options/tint.md): Colour washed over the body by the tone's `tint` share (about a sixth on light regular glass at the default level, a quarter on dark, more on floating glass and toward More Tinted)
- [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`, `saturate`, `contrast`, `brightness` and `tint` share, the same for floating glass (`floatingBlur`, `floatingSaturate`, `floatingContrast`, `floatingBrightness`, `floatingTint`), 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: rimShare](https://liquid-glass.coline.space/docs/options/geometry-rimShare.md): Most of the corner radius the top and bottom rims may take
- [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: nearly the top's, as the light iOS 27's glass gathers along its lower edge is
- [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, over 240ms on ease-out cubic by default
- [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, over 180ms by default
- [The glass handle: pourFrom(source, options?)](https://liquid-glass.coline.space/docs/options/handle-pourFrom.md): Pours a menu or popover out of the button that opened it, as iOS 27's do: the glass starts as the button and inflates into the surface, its height leading and overshooting, while the contents ride inside it and sharpen as it lands
- [The glass handle: drawBack()](https://liquid-glass.coline.space/docs/options/handle-drawBack.md): Draws the surface back into where it poured from: the contents go first and the glass rounds into a drop that shrinks into the button, which reappears with a bulge
- [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
- [React: <LiquidGlassTabLabel />](https://liquid-glass.coline.space/docs/options/react-LiquidGlassTabLabel.md): A tab's text, semibold while its tab is selected (or a drag would land on it), as iOS 27's segmented control sets it, without the tab changing width
- [React: useLiquidGlassHighlight(ref, options?)](https://liquid-glass.coline.space/docs/options/react-useLiquidGlassHighlight.md): A hover pill for the rows of a glass menu or list: a well that slides to the row under the pointer or with focus
- [More exports: attachLiquidGlassHighlight(surface, options?)](https://liquid-glass.coline.space/docs/options/functions-attachLiquidGlassHighlight.md): Gives a glass surface's rows a hover pill: a well that slides to the row under the pointer or with focus
- [More exports: prewarmLiquidGlass(radii?, geometry?)](https://liquid-glass.coline.space/docs/options/functions-prewarmLiquidGlass.md): Builds the rim for these corner radii while the page is idle, so glass whose corners animate through them is sharp on every frame
- [More exports: createShapedGlass(path, width, height, radius, pixelRatio?, geometry?)](https://liquid-glass.coline.space/docs/options/functions-createShapedGlass.md): The refraction map and masks for an outline, as raw pixels, as the `shape` option renders them
- [More exports: createGlassSlices(radius, pixelRatio?, geometry?)](https://liquid-glass.coline.space/docs/options/functions-createGlassSlices.md): The lens for a rounded box as raw pixels: a rounded square of side 2r + 1 that assembles over any size
- [More exports: kickGlass(element, velocity)](https://liquid-glass.coline.space/docs/options/functions-kickGlass.md): Kicks the swell of the glass around `element`: positive bulges it, negative makes it give, and it rings back to rest
- [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
- [CSS: --liquid-glass-control-shadow](https://liquid-glass.coline.space/docs/options/css-liquid-glass-control-shadow.md): The faint shadow light interactive glass floats on
- [CSS: --liquid-glass-tabs-tint](https://liquid-glass.coline.space/docs/options/css-liquid-glass-tabs-tint.md): The colour a tabs track's glass is washed with: near-black in dark, a light grey for a light segmented control
- [CSS: --liquid-glass-tabs-fill](https://liquid-glass.coline.space/docs/options/css-liquid-glass-tabs-fill.md): The colour of a segmented control's solid thumb (white in light, grey in dark), with --liquid-glass-tabs-fill-alpha