Liquid Glass for the web: the rim refraction, light and motion of iOS 27 glass on any rounded element. React bindings and pill tabs. MIT.
| 6 | "rules": [ |
| 7 | "Put the glass first inside a positioned (relative, absolute or fixed), rounded element. It takes the element's corner radius and follows its size.", |
| 8 | "Paint nothing over it: no background, border or box-shadow on the surface. The glass draws its own edge.", |
| 9 | "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.", |
| 10 | "To show or hide a surface, fade and zoom its contents, never the surface itself, and call materialize() and dematerialize() for the glass.", |
| 11 | "Controls on glass get no glass of their own: give the selected or hovered one the liquid-glass-well class.", |
| 12 | "Rim refraction renders in Chromium. Safari and Firefox get the same material, light and motion without the bend." |
| 13 | ], |
| 14 | "groups": [ |
| 15 | { |
| 16 | "id": "options", |
| 17 | "title": "Glass options", |
| 18 | "intro": "Options for `<LiquidGlass />`, `useLiquidGlass(ref, options)`, `createLiquidGlass(element, options)` and `glass.update(options)`. Every option is optional.", |
| 19 | "entries": [ |
| 20 | { |
| 21 | "name": "appearance", |
| 22 | "type": "\"system\" | \"class\" | \"dark\" | \"light\"", |
| 23 | "default": "\"system\"", |
| 24 | "description": "`system` follows prefers-color-scheme. `class` is dark while `<html>` has the `dark` class (Tailwind's class strategy, next-themes). `dark` and `light` fix it.", |
| 25 | "example": "<LiquidGlass appearance=\"class\" />" |
| 26 | }, |
| 27 | { |
| 28 | "name": "variant", |
| 29 | "type": "\"regular\" | \"clear\" | \"lens\"", |
| 30 | "default": "\"regular\"", |
| 31 | "description": "`regular` diffuses and evens out the page so text on the glass stays legible over anything. `clear` only bends and lights the page, for glass over media. `lens` is the clear lens a control lifts into; pair it with `geometry: LENS_GEOMETRY`.", |
| 32 | "example": "<LiquidGlass variant=\"clear\" />" |
| 33 | }, |
| 34 | { |
| 35 | "name": "floating", |
| 36 | "type": "boolean | \"dialog\"", |
| 37 | "default": "false", |
| 38 | "description": "For menus, popovers, dialogs and sheets. Floating glass diffuses the page more, as iOS 27's does, so text beneath washes into soft colour, and the surface casts a drop shadow (`--liquid-glass-shadow`). `\"dialog\"` casts a dialog's deeper shadow (`--liquid-glass-dialog-shadow`).", |
| 39 | "example": "<LiquidGlass floating=\"dialog\" />" |
| 40 | }, |
| 41 | { |
| 42 | "name": "interactive", |
| 43 | "type": "boolean", |
| 44 | "default": "false", |
| 45 | "description": "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.", |
| 46 | "example": "<LiquidGlass interactive />" |
| 47 | }, |
| 48 | { |
| 49 | "name": "swell", |
| 50 | "type": "boolean", |
| 51 | "default": "false", |
| 52 | "description": "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.", |
| 53 | "example": "<LiquidGlass interactive swell />" |
| 54 | }, |
| 55 | { |
| 56 | "name": "tint", |
| 57 | "type": "string", |
| 58 | "default": "near-black in dark, white in light", |
| 59 | "description": "Colour washed over the body by the tone's `tint` share (50% on dark regular glass, 40% on light). Any CSS colour, including `var()`.", |
| 60 | "example": "<LiquidGlass tint=\"var(--background)\" />" |
| 61 | }, |
| 62 | { |
| 63 | "name": "hue", |
| 64 | "type": "string | null", |
| 65 | "default": "null", |
| 66 | "description": "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. Any concrete CSS colour; neutral colours leave the glass untinted.", |
| 67 | "example": "<LiquidGlass hue=\"#3d6bff\" />" |
| 68 | }, |
| 69 | { |
| 70 | "name": "hueStrength", |
| 71 | "type": "number (0–1)", |
| 72 | "default": "1 on light glass, 0.5 on dark", |
| 73 | "description": "How much of the hue the glass takes.", |
| 74 | "example": "<LiquidGlass hue=\"#ff4fa3\" hueStrength={0.7} />" |
| 75 | }, |
| 76 | { |
| 77 | "name": "geometry", |
| 78 | "type": "Partial<GlassGeometry>", |
| 79 | "default": "DEFAULT_GEOMETRY", |
| 80 | "description": "The rim's shape, measured from iOS 27: its width and depth, how steeply it bends, the darkened edge and the glints. See the geometry fields below. `LENS_GEOMETRY` is the rim for a control-high lens.", |
| 81 | "example": "<LiquidGlass geometry={{ maxFall: 0.5, edge: 1 }} />" |
| 82 | }, |
| 83 | { |
| 84 | "name": "tone", |
| 85 | "type": "{ dark?: Partial<GlassTone>; light?: Partial<GlassTone> }", |
| 86 | "description": "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`.", |
| 87 | "example": "<LiquidGlass tone={{ dark: { brightness: 0.4 }, light: { tint: 0.5 } }} />" |
| 88 | }, |
| 89 | { |
| 90 | "name": "fit", |
| 91 | "type": "\"box\" | \"fixed\" | \"scroll\"", |
| 92 | "default": "\"box\"", |
| 93 | "description": "`box` fills the surface. `fixed` fills the nearest containing block for fixed elements, such as a transformed popper wrapper, so the glass holds still while the surface scrolls its own content. `scroll` spans the surface's whole scroll height, for a dialog or sheet that scrolls itself.", |
| 94 | "example": "<LiquidGlass fit=\"scroll\" floating=\"dialog\" />" |
| 95 | }, |
| 96 | { |
| 97 | "name": "refraction", |
| 98 | "type": "boolean", |
| 99 | "default": "true", |
| 100 | "description": "Bend the page at the rim. Rim refraction needs SVG filters in backdrop-filter, which only Chromium renders; Safari and Firefox keep the material without the bend either way.", |
| 101 | "example": "<LiquidGlass refraction={false} />" |
| 102 | }, |
| 103 | { |
| 104 | "name": "samples", |
| 105 | "type": "1 | 4", |
| 106 | "default": "1", |
| 107 | "description": "Refraction samples per pixel. 4 antialiases the bend, so edges it stretches don't stair-step as the glass moves. It costs four displacement passes, so keep it for small glass with nothing blurring its backdrop, like a lens.", |
| 108 | "example": "<LiquidGlass variant=\"lens\" samples={4} />" |
| 109 | } |
| 110 | ] |
| 111 | }, |
| 112 | { |
| 113 | "id": "geometry", |
| 114 | "title": "Geometry fields", |
| 115 | "intro": "Fields of `GlassGeometry`, in CSS pixels unless noted. Pass any subset as `geometry`.", |
| 116 | "entries": [ |
| 117 | { |
| 118 | "name": "bezel", |
| 119 | "type": "number", |
| 120 | "default": "17", |
| 121 | "description": "Width of the refracting rim along the top and bottom. The centre is flat." |
| 122 | }, |
| 123 | { |
| 124 | "name": "thickness", |
| 125 | "type": "number", |
| 126 | "default": "24", |
| 127 | "description": "Glass depth under the top and bottom rims. Deeper glass bends further." |
| 128 | }, |
| 129 | { |
| 130 | "name": "sideBezel", |
| 131 | "type": "number", |
| 132 | "default": "27", |
| 133 | "description": "Width of the refracting rim at the sides and rounded ends." |
| 134 | }, |
| 135 | { |
| 136 | "name": "sideThickness", |
| 137 | "type": "number", |
| 138 | "default": "44", |
| 139 | "description": "Glass depth under the sides and rounded ends." |
| 140 | }, |
| 141 | { |
| 142 | "name": "refractiveIndex", |
| 143 | "type": "number", |
| 144 | "default": "1.5", |
| 145 | "description": "The glass's refractive index, for Snell's law at the rim." |
| 146 | }, |
| 147 | { |
| 148 | "name": "maxFall", |
| 149 | "type": "number (0–1)", |
| 150 | "default": "0.8", |
| 151 | "description": "Rim bend: the steepest the rim's shift may fall per pixel inward. Where it falls, the rim magnifies what is beneath by 1 / (1 − maxFall), so lower values bend more gently and keep text crossing the rim from smearing. The tab lens uses 0.3. Past 1 the lens folds content into mirrored echoes." |
| 152 | }, |
| 153 | { |
| 154 | "name": "edge", |
| 155 | "type": "number", |
| 156 | "default": "0.75", |
| 157 | "description": "Width of iOS 27's darkened edge, a contour where the glass meets the air, with the hairline just inside it. 0 leaves it out." |
| 158 | }, |
| 159 | { |
| 160 | "name": "glint", |
| 161 | "type": "number (0–1)", |
| 162 | "default": "0.4", |
| 163 | "description": "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. 0 keeps an even band." |
| 164 | }, |
| 165 | { |
| 166 | "name": "hairline", |
| 167 | "type": "number", |
| 168 | "default": "1", |
| 169 | "description": "Rim hairline width." |
| 170 | }, |
| 171 | { |
| 172 | "name": "hairlineSides", |
| 173 | "type": "number (0–1)", |
| 174 | "default": "0.15", |
| 175 | "description": "Share of the hairline's strength that reaches the sides." |
| 176 | }, |
| 177 | { |
| 178 | "name": "shadeWidth", |
| 179 | "type": "number", |
| 180 | "default": "1", |
| 181 | "description": "Width of the darkened sides." |
| 182 | }, |
| 183 | { |
| 184 | "name": "glowReach", |
| 185 | "type": "number", |
| 186 | "default": "8", |
| 187 | "description": "How far the inner glow reaches in from the top and bottom rims." |
| 188 | }, |
| 189 | { |
| 190 | "name": "glowBottom", |
| 191 | "type": "number (0–1)", |
| 192 | "default": "0.5", |
| 193 | "description": "Bottom glow strength relative to the top." |
| 194 | } |
| 195 | ] |
| 196 | }, |
| 197 | { |
| 198 | "id": "handle", |
| 199 | "title": "The glass handle", |
| 200 | "intro": "`createLiquidGlass()` and `attachLiquidGlass()` return it; `useLiquidGlass()` returns a ref to it, and `<LiquidGlass glassRef={ref} />` fills one.", |
| 201 | "entries": [ |
| 202 | { |
| 203 | "name": "update(options)", |
| 204 | "type": "(options: LiquidGlassOptions) => void", |
| 205 | "description": "Replaces the options. Cheap: the rim only rebuilds when the geometry changes.", |
| 206 | "example": "glass.update({ variant: \"clear\" });" |
| 207 | }, |
| 208 | { |
| 209 | "name": "magnify(factor)", |
| 210 | "type": "(factor: number) => void", |
| 211 | "description": "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. Cheap enough to call every frame. Needs refraction.", |
| 212 | "example": "glass.magnify(1.1);" |
| 213 | }, |
| 214 | { |
| 215 | "name": "materialize(timing?)", |
| 216 | "type": "(timing?: { duration?, easing?, delay?, scale? }) => Promise<void>", |
| 217 | "description": "Grows the glass from clear to its tone, for surfaces that appear. Fade the surface's contents, never the surface: opacity below 1 hides the glass. For a surface that zooms open, scale its contents and pass the same `scale`; the glass grows by its inset instead.", |
| 218 | "example": "await glass.materialize({ duration: 240, scale: 0.96 });" |
| 219 | }, |
| 220 | { |
| 221 | "name": "dematerialize(timing?)", |
| 222 | "type": "(timing?) => Promise<void>", |
| 223 | "description": "Fades the glass back to clear and holds it there, for surfaces that leave. Wells on it ease back with it.", |
| 224 | "example": "await glass.dematerialize({ duration: 160 });" |
| 225 | }, |
| 226 | { |
| 227 | "name": "destroy()", |
| 228 | "type": "() => void", |
| 229 | "description": "Removes the glass and its filters." |
| 230 | }, |
| 231 | { |
| 232 | "name": "element", |
| 233 | "type": "HTMLElement", |
| 234 | "description": "The glass element, the surface's first child." |
| 235 | }, |
| 236 | { |
| 237 | "name": "appearance", |
| 238 | "type": "\"dark\" | \"light\"", |
| 239 | "description": "The resolved appearance." |
| 240 | } |
| 241 | ] |
| 242 | }, |
| 243 | { |
| 244 | "id": "tabs", |
| 245 | "title": "Tabs", |
| 246 | "intro": "`useLiquidGlassTabs(trackRef, options)` in React, `attachLiquidGlassTabs(track, options)` without it. The track is the tabs' positioned, rounded container. Your tabs and selection stay yours; the thumb follows the selected tab, lifts into a lens that magnifies the labels, stretches as it travels and squashes as it lands. Dragging the selected tab scrubs across the others. Returns `{ update(), destroy() }`.", |
| 247 | "entries": [ |
| 248 | { |
| 249 | "name": "appearance", |
| 250 | "type": "\"system\" | \"class\" | \"dark\" | \"light\"", |
| 251 | "default": "\"system\"", |
| 252 | "description": "As for glass." |
| 253 | }, |
| 254 | { |
| 255 | "name": "orientation", |
| 256 | "type": "\"horizontal\" | \"vertical\"", |
| 257 | "default": "\"horizontal\"", |
| 258 | "description": "Vertical tabs stack and don't scrub." |
| 259 | }, |
| 260 | { |
| 261 | "name": "tabs", |
| 262 | "type": "string", |
| 263 | "default": "'[role=\"tab\"]'", |
| 264 | "description": "Selector for the tabs inside the track.", |
| 265 | "example": "useLiquidGlassTabs(track, { tabs: '[role=\"radio\"]' });" |
| 266 | }, |
| 267 | { |
| 268 | "name": "isSelected", |
| 269 | "type": "(tab: HTMLElement) => boolean", |
| 270 | "default": "aria-selected, aria-checked or data-state=\"active\"", |
| 271 | "description": "Whether a tab is selected. The thumb follows changes to the default attributes by itself; call `update()` after changes to anything else." |
| 272 | }, |
| 273 | { |
| 274 | "name": "onSelect", |
| 275 | "type": "(tab: HTMLElement) => void", |
| 276 | "default": "press and click the tab", |
| 277 | "description": "Selects the tab the thumb was dragged onto." |
| 278 | }, |
| 279 | { |
| 280 | "name": "glass", |
| 281 | "type": "boolean | LiquidGlassOptions", |
| 282 | "default": "glass unless on another glass surface", |
| 283 | "description": "The track's own glass, or its options. On another glass surface the track gets none of its own: it becomes a recessed tint and the thumb a well in that glass." |
| 284 | }, |
| 285 | { |
| 286 | "name": "refraction", |
| 287 | "type": "boolean", |
| 288 | "default": "true", |
| 289 | "description": "Bend the page at the rims." |
| 290 | } |
| 291 | ] |
| 292 | }, |
| 293 | { |
| 294 | "id": "react", |
| 295 | "title": "React", |
| 296 | "intro": "From `@colineapp/liquid-glass/react`. React 18 or later; the core package has no dependencies.", |
| 297 | "entries": [ |
| 298 | { |
| 299 | "name": "<LiquidGlass />", |
| 300 | "type": "LiquidGlassOptions & { className?, style?, children?, glassRef? }", |
| 301 | "description": "Glass behind a surface's content. Render it first inside a positioned, rounded element. `glassRef` receives the handle, for materialize() and magnify().", |
| 302 | "example": "<nav className=\"relative rounded-full px-6 py-3\">\n <LiquidGlass interactive />\n …\n</nav>" |
| 303 | }, |
| 304 | { |
| 305 | "name": "useLiquidGlass(ref, options)", |
| 306 | "type": "RefObject<LiquidGlass | null>", |
| 307 | "description": "Turns an element you already render into a glass surface; the glass is inserted as its first child." |
| 308 | }, |
| 309 | { |
| 310 | "name": "useLiquidGlassTabs(ref, options)", |
| 311 | "type": "RefObject<LiquidGlassTabs | null>", |
| 312 | "description": "Liquid Glass tabs on a track you render. See Tabs." |
| 313 | } |
| 314 | ] |
| 315 | }, |
| 316 | { |
| 317 | "id": "css", |
| 318 | "title": "CSS", |
| 319 | "intro": "Import `@colineapp/liquid-glass/styles.css` once. The filters themselves are set inline by the script, as literal values Safari can read.", |
| 320 | "entries": [ |
| 321 | { |
| 322 | "name": ".liquid-glass-well", |
| 323 | "type": "class", |
| 324 | "description": "For a selected or hovered control on a glass surface: brightens the glass beneath it (dimmer in light), instead of glass on glass.", |
| 325 | "example": "<button className=\"liquid-glass-well rounded-full\">Today</button>" |
| 326 | }, |
| 327 | { |
| 328 | "name": "--liquid-glass-shadow", |
| 329 | "type": "custom property", |
| 330 | "description": "The shadow floating glass casts. Set it on the surface or an ancestor." |
| 331 | }, |
| 332 | { |
| 333 | "name": "--liquid-glass-dialog-shadow", |
| 334 | "type": "custom property", |
| 335 | "description": "The deeper shadow of `floating: \"dialog\"` glass." |
| 336 | } |
| 337 | ] |
| 338 | } |
| 339 | ], |
| 340 | "examples": [ |
| 341 | { |
| 342 | "id": "react", |
| 343 | "title": "A glass toolbar in React", |
| 344 | "description": "Render <LiquidGlass /> first inside a positioned, rounded element.", |
| 345 | "language": "tsx", |
| 346 | "code": "import { LiquidGlass } from \"@colineapp/liquid-glass/react\";\nimport \"@colineapp/liquid-glass/styles.css\";\n\nexport function Toolbar() {\n return (\n <nav className=\"relative flex gap-1 rounded-full p-1.5\">\n <LiquidGlass appearance=\"class\" interactive />\n <button className=\"liquid-glass-well rounded-full px-4 py-2\">Today</button>\n <button className=\"rounded-full px-4 py-2\">Week</button>\n </nav>\n );\n}" |
| 347 | }, |
| 348 | { |
| 349 | "id": "vanilla", |
| 350 | "title": "Without React", |
| 351 | "description": "createLiquidGlass inserts the glass as the element's first child.", |
| 352 | "language": "ts", |
| 353 | "code": "import { createLiquidGlass } from \"@colineapp/liquid-glass\";\nimport \"@colineapp/liquid-glass/styles.css\";\n\nconst glass = createLiquidGlass(document.querySelector(\".toolbar\")!, {\n interactive: true,\n});\n\nglass.update({ variant: \"clear\" });\nglass.destroy();" |
| 354 | }, |
| 355 | { |
| 356 | "id": "tabs", |
| 357 | "title": "Pill tabs", |
| 358 | "description": "Your tabs, your selection; the thumb follows aria-selected.", |
| 359 | "language": "tsx", |
| 360 | "code": "import { useRef } from \"react\";\nimport { useLiquidGlassTabs } from \"@colineapp/liquid-glass/react\";\n\nexport function Period({ value, onChange }: { value: string; onChange: (value: string) => void }) {\n const track = useRef<HTMLDivElement>(null);\n useLiquidGlassTabs(track, { appearance: \"class\" });\n return (\n <div ref={track} role=\"tablist\" className=\"flex rounded-full p-1\">\n {[\"Day\", \"Week\", \"Month\"].map((label) => (\n <button key={label} role=\"tab\" aria-selected={label === value} onClick={() => onChange(label)}\n className=\"rounded-full px-4 py-1.5 text-sm font-medium\">\n {label}\n </button>\n ))}\n </div>\n );\n}" |
| 361 | }, |
| 362 | { |
| 363 | "id": "menu", |
| 364 | "title": "A menu that materializes", |
| 365 | "description": "Fade the contents, never the surface; the glass grows from clear.", |
| 366 | "language": "tsx", |
| 367 | "code": "import { useEffect, useRef, useState } from \"react\";\nimport { LiquidGlass, type LiquidGlassHandle } from \"@colineapp/liquid-glass/react\";\n\nexport function Menu({ open, items }: { open: boolean; items: string[] }) {\n const glass = useRef<LiquidGlassHandle | null>(null);\n const [active, setActive] = useState(-1);\n useEffect(() => {\n if (open) void glass.current?.materialize({ duration: 240, scale: 0.96 });\n }, [open]);\n if (!open) return null;\n return (\n <div role=\"menu\" className=\"absolute right-0 top-12 w-56 rounded-2xl p-1.5\">\n <LiquidGlass glassRef={glass} appearance=\"class\" floating />\n {items.map((item, index) => (\n <button key={item} role=\"menuitem\" onPointerEnter={() => setActive(index)}\n className={`w-full rounded-xl px-3 py-2 text-left ${index === active ? \"liquid-glass-well\" : \"\"}`}>\n {item}\n </button>\n ))}\n </div>\n );\n}" |
| 368 | }, |
| 369 | { |
| 370 | "id": "dialog", |
| 371 | "title": "A glass dialog", |
| 372 | "description": "floating=\"dialog\" casts the deeper shadow; the glass materializes as the contents zoom in.", |
| 373 | "language": "tsx", |
| 374 | "code": "import { useLayoutEffect, useRef } from \"react\";\nimport { LiquidGlass, type LiquidGlassHandle } from \"@colineapp/liquid-glass/react\";\n\nexport function ShareDialog({ onClose }: { onClose: () => void }) {\n const glass = useRef<LiquidGlassHandle | null>(null);\n useLayoutEffect(() => {\n void glass.current?.materialize({ duration: 280, scale: 0.95 });\n }, []);\n const close = () => void glass.current?.dematerialize({ duration: 180, scale: 0.97 }).then(onClose);\n return (\n <div role=\"dialog\" aria-modal=\"true\" className=\"fixed left-1/2 top-1/3 w-80 -translate-x-1/2 rounded-[28px] p-5\">\n <LiquidGlass glassRef={glass} appearance=\"class\" floating=\"dialog\" />\n <h2 className=\"font-semibold\">Share this album</h2>\n <button className=\"liquid-glass-well mt-4 h-10 w-full rounded-full\" onClick={close}>Copy link</button>\n </div>\n );\n}" |
| 375 | }, |
| 376 | { |
| 377 | "id": "search", |
| 378 | "title": "A search field that swells", |
| 379 | "description": "interactive lights it under the pointer; swell springs it on press.", |
| 380 | "language": "tsx", |
| 381 | "code": "<label className=\"relative flex h-11 items-center gap-2 rounded-full px-4\">\n <LiquidGlass appearance=\"class\" interactive swell />\n <SearchIcon />\n <input className=\"bg-transparent outline-none\" placeholder=\"Search\" />\n</label>" |
| 382 | }, |
| 383 | { |
| 384 | "id": "card", |
| 385 | "title": "A glass card", |
| 386 | "description": "Regular glass on a rounded box: the rim bends what crosses it, and the body keeps the card's text legible.", |
| 387 | "language": "tsx", |
| 388 | "code": "import { LiquidGlass } from \"@colineapp/liquid-glass/react\";\nimport \"@colineapp/liquid-glass/styles.css\";\n\nexport function Card() {\n return (\n <div className=\"relative grid gap-1 rounded-[30px] p-5\">\n <LiquidGlass appearance=\"class\" />\n <h3 className=\"font-semibold\">Now playing</h3>\n <p className=\"text-sm opacity-70\">Glass takes the box's radius and follows its size.</p>\n </div>\n );\n}" |
| 389 | } |
| 390 | ] |
| 391 | } |
| 392 |