# Quick start (/docs) liqui is a set of liquid-glass components built on [Base UI](https://base-ui.com) primitives. Components arrive as **source code in your project** through the shadcn CLI; only the refraction kernel stays a dependency. It comes out of [Liquid Glass Design](https://liquidglassdesign.com/?ref=liqui.design), a gallery of liquid glass references — this is the part of that collection you can install. ## Install [#install] Adding a component is the whole setup: ```bash npx shadcn@latest add https://liqui.design/r/button.json ``` That writes `components/ui/button.tsx` into your project, adds the glass design tokens to your `globals.css`, and installs [`@liqui-design/glass`](https://www.npmjs.com/package/@liqui-design/glass) — the SVG filter registry, displacement-map generator and browser fallbacks. That package is the one part of liqui you are not meant to edit; everything else lands in your repo as plain TSX. Installing more than one? Register the namespace once in `components.json` and drop the URLs: ```json title="components.json" { "registries": { "@liqui-design": "https://liqui.design/r/{name}.json" } } ``` ```bash npx shadcn@latest add @liqui-design/button @liqui-design/select ``` `@liqui-design/button` is a **registry** item, not an npm package — `@liqui-design` here is a key you just defined in your own `components.json`, and it resolves through the shadcn CLI. `npm i @liqui-design/button` will not work. The only thing that comes from npm is `@liqui-design/glass`, and the CLI installs it for you. Building your own surfaces on top of `LiquiGlass` instead? The theme is installable on its own — it is what every component above pulls in: ```bash npx shadcn@latest add https://liqui.design/r/liqui.json ``` Already using shadcn/ui? liqui is built on the same Base UI base (`shadcn init -b base`), so your existing `components.json`, `cn()` and Tailwind token setup carry over unchanged. ## Use it [#use-it] ```tsx import { Button } from '@/components/ui/button'; export default function Page() { return (
); } ``` Note the background. Glass refracts what is behind it, so a surface on a flat fill has nothing to show — see [Glass](/docs/handbook/glass) before you judge how it looks. ## Requirements [#requirements] * React 18 or 19 * Tailwind CSS v4 * Refraction renders in every modern browser: Chromium refracts whatever is behind a surface, Safari and Firefox refract inside a `LiquiBackdrop` and fall back to frosted blur elsewhere ([details](/docs/handbook/glass#safari-and-firefox)) # Accordion (/docs/components/accordion) ## Installation [#installation] ```bash npx shadcn@latest add https://liqui.design/r/accordion.json ``` Installing more than one? Register the namespace once in `components.json` and drop the URLs: ```json title="components.json" { "registries": { "@liqui-design": "https://liqui.design/r/{name}.json" } } ``` ```bash npx shadcn@latest add @liqui-design/accordion ``` ## Usage [#usage] ```tsx import { Accordion, AccordionItem, AccordionPanel, AccordionTrigger, } from '@/components/ui/accordion'; ``` ```tsx First Panel content. ``` Pass `openMultiple={false}` to `Accordion` for the one-open-at-a-time behaviour. ## Notes [#notes] ### Glass on an animating box [#glass-on-an-animating-box] This is the library's stress test. The surface grows and shrinks with the panel, and a new size means a new displacement map — the bezel has to follow the new box or the refraction detaches from the edge mid-animation. That works because maps are cached module-wide by size and optics. An accordion that has been opened once reopens without regenerating anything; only the first open at each height pays. Height itself comes from Base UI's own panel measurement: ```tsx h-[var(--accordion-panel-height)] data-[starting-style]:h-0 data-[ending-style]:h-0 ``` ### Why the content wrapper is clipped [#why-the-content-wrapper-is-clipped] The panel animates by clipping, so the glass content wrapper carries `overflow-hidden` — the wrapper already has the surface's corners, so the clip follows the same continuous curve: ```tsx ``` Without it the panel's square corners punch through the surface's rounded ones while the height is animating. This is exactly the kind of thing `contentClassName` exists for — it is glass-internal geometry that the component on top has to control. ### Stacking cost [#stacking-cost] Each item is a separate `backdrop-filter` surface, and that is the cost that actually shows up in frame times. A long list of glass rows is the one layout worth profiling — see [Glass](/docs/handbook/glass#performance-budget). # Alert Dialog (/docs/components/alert-dialog) ## Installation [#installation] ```bash npx shadcn@latest add https://liqui.design/r/alert-dialog.json ``` Installing more than one? Register the namespace once in `components.json` and drop the URLs: ```json title="components.json" { "registries": { "@liqui-design": "https://liqui.design/r/{name}.json" } } ``` ```bash npx shadcn@latest add @liqui-design/alert-dialog ``` ## Usage [#usage] ```tsx import { AlertDialog, AlertDialogActions, AlertDialogClose, AlertDialogContent, AlertDialogDescription, AlertDialogTitle, AlertDialogTrigger, } from '@/components/ui/alert-dialog'; ``` ```tsx Delete} /> Delete this workspace? This cannot be undone. Cancel} /> Delete} /> ``` `render` is Base UI's composition prop: the trigger and close *become* the button rather than wrapping it, so you don't end up with a button inside a button. `nativeButton={false}` is required when you compose a trigger or close with a **glass** `Button`. The glass anatomy is invalid inside a native ` ``` ## Examples [#examples] ### Variants [#variants] Three variants, **two materials**. `glass` is the lens. `accent` and `danger` are solid fills with no backdrop filter behind them at all. That split is [the library's rule](/docs/handbook/glass#not-everything-is-glass) and it is Apple's: glass is for a surface you act *through*, a solid fill is for something that carries meaning. A tinted lens contradicts itself — the point of the colour is that it says *this is the one*, and the point of the lens is that it lets the wallpaper through. The accent variant used to be a retint of `--lq-tint`, which meant it was one blue over a bright photograph and a noticeably different one over a dark backdrop. It is now `--lq-accent`, and it is that colour everywhere. Retune the solid fills through `--lq-accent` and `--lq-danger`; there is no glass underneath to compose with, so a plain `background` override works too. ### Tuning the glass [#tuning-the-glass] The `glass` prop reaches the surface underneath. `frost` is the material density dial: `0` is Apple's "clear" tier, `1` is "regular". Refraction and bezel control how wide and how strong the lens at the rim is. A solid variant has no surface to reach, so the optical dials are ignored there. `radius` is the exception — it is geometry rather than optics, and a round accent button still has to be able to say so: ```tsx ``` ### Disabled [#disabled] ## Notes [#notes] ### Only the glass variant opts out of ` ``` It follows that a composing trigger only needs telling about the glass variant: ```tsx Cancel} /> Copy link} /> ``` Passing `nativeButton={false}` alongside a solid Button is not harmless — Base UI would put `role="button"` and its own key handling on an element that already has both. ### Backdrop [#backdrop] A glass button on a flat fill is just a grey box. Put it over imagery, a gradient, or anything with edges for the bezel to bend. See [Glass](/docs/handbook/glass) for the full material guide. The solid variants have no such requirement, which is a second reason to reach for one: an accent button is the button that has to work on every backdrop your app will ever have. ### Browser support [#browser-support] Chromium refracts whatever is behind the button. Safari and Firefox drop `backdrop-filter` when it references an SVG filter, so there the button refracts a copy of its backdrop when it sits in a `LiquiBackdrop`, and frosts anywhere else, keeping the same rim. No configuration needed, but do check both — see [Glass](/docs/handbook/glass#safari-and-firefox). The solid variants render identically everywhere: there is no filter to fall back from. # Checkbox Group (/docs/components/checkbox-group) ## Installation [#installation] ```bash npx shadcn@latest add https://liqui.design/r/checkbox-group.json ``` Installing more than one? Register the namespace once in `components.json` and drop the URLs: ```json title="components.json" { "registries": { "@liqui-design": "https://liqui.design/r/{name}.json" } } ``` ```bash npx shadcn@latest add @liqui-design/checkbox-group ``` It brings [Checkbox](/docs/components/checkbox) with it — the group is state, and the boxes are what you can see. ## Usage [#usage] ```tsx import { Checkbox, CheckboxLabel } from '@/components/ui/checkbox'; import { CheckboxGroup } from '@/components/ui/checkbox-group'; ``` ```tsx HTTPS … ``` A group needs a name. `aria-label` works; a visible one is better, and [Fieldset](/docs/components/fieldset) is what that looks like — its legend is associated with everything inside it, which is what the demo above uses. ## Parent checkbox [#parent-checkbox] ```tsx Repository access … ``` `allValues` is what lets the group work out whether the parent is fully ticked, empty, or somewhere in between. ## Notes [#notes] ### "Some of these" is a mark, not a material [#some-of-these-is-a-mark-not-a-material] The mixed state carries the *same* accent retint as a fully checked box, and changes the tick to a dash: ```tsx 'data-[checked]:[--lq-tint:color-mix(in_srgb,var(--lq-accent)_88%,transparent)]'; 'data-[indeterminate]:[--lq-tint:color-mix(in_srgb,var(--lq-accent)_88%,transparent)]'; ``` The tempting alternative is to express "partly" by weakening the surface — a paler tint, a softer rim, half the opacity. It cannot be done here, because the library already spends dimming on something else: a disabled control is `opacity-50`, and a half-selected parent that looked faded would read as one you are not allowed to press. So the material stays at full strength and the *mark* carries the meaning. This is the same reason [Checkbox](/docs/components/checkbox) retints rather than painting a filled box in the first place — state changes are supposed to leave the glass being glass. ### The mark comes from state, not from a prop [#the-mark-comes-from-state-not-from-a-prop] Inside a group, a `parent` checkbox is put into the mixed state by the group. Nothing is passed down to it, so a component that picked its icon from an `indeterminate` prop would draw a tick on a half-selected parent: ```tsx {state.indeterminate ? Dash : Tick}} /> ``` Reading it off the indicator's own state is what makes `` work with no further wiring, and it is why the checkbox source looks the way it does. ### The group is a stack and a gap [#the-group-is-a-stack-and-a-gap] No surface, for the reason [Radio Group](/docs/components/radio-group#the-group-is-still-not-a-surface) gives: this is a list, not a strip. The boxes do not share a box — each is a small control with text beside it and a gap under it — so there is nothing here that could hold a surface, and a panel drawn around them would be a card they happen to be lying on. That card is [Fieldset](/docs/components/fieldset), and it is not a surface either. The indentation under a parent is layout, not a component — a `ml-7` on a plain `
`, as in the demo above. It is deliberately not built in: the offset that lines children up under a parent depends on your checkbox size and label gap, and a component that guessed would be wrong at every size but one. # Checkbox (/docs/components/checkbox) ## Installation [#installation] ```bash npx shadcn@latest add https://liqui.design/r/checkbox.json ``` Installing more than one? Register the namespace once in `components.json` and drop the URLs: ```json title="components.json" { "registries": { "@liqui-design": "https://liqui.design/r/{name}.json" } } ``` ```bash npx shadcn@latest add @liqui-design/checkbox ``` ## Usage [#usage] ```tsx import { Checkbox, CheckboxLabel } from '@/components/ui/checkbox'; ``` ```tsx Show hidden files ``` `CheckboxLabel` is a plain `
} /> New Folder ⇧⌘N Move to Trash ``` The full anatomy also ships `ContextMenuGroup`, `ContextMenuGroupLabel`, `ContextMenuCheckboxItem`, `ContextMenuRadioGroup`, `ContextMenuRadioItem`, `ContextMenuSub`, `ContextMenuSubTrigger` and `ContextMenuSubContent`. ## Notes [#notes] ### The portal stays mounted [#the-portal-stays-mounted] `ContextMenuContent` renders through ``. A closed menu stays in the DOM, so its filter and already-decoded displacement map survive close and the next open is instant. Without it, every open pays the `feImage` decode window again, and the menu appears as flat frosted blur for \~150ms before refraction arrives. That reads as lag even though nothing is slow. `display: none` → shown **restarts** any CSS animation still attached to an element. The refraction fade-in is therefore cold-gated inside `@liqui-design/glass` and removed once it has played — otherwise a keep-mounted popup would re-fade on every single open, which looks worse than the problem it solves. ### Submenus get softer optics [#submenus-get-softer-optics] A submenu is a narrower box, so the popup defaults would over-bend it: ```tsx ``` Same principle as the checkbox — bezel is a fraction of the box, so smaller boxes need smaller numbers. ### Trigger area [#trigger-area] `ContextMenuTrigger` takes `render` and becomes your element. Give it a real box with dimensions; a zero-height trigger has nothing to right-click. # Dialog (/docs/components/dialog) ## Installation [#installation] ```bash npx shadcn@latest add https://liqui.design/r/dialog.json ``` Installing more than one? Register the namespace once in `components.json` and drop the URLs: ```json title="components.json" { "registries": { "@liqui-design": "https://liqui.design/r/{name}.json" } } ``` ```bash npx shadcn@latest add @liqui-design/dialog ``` ## Usage [#usage] ```tsx import { Dialog, DialogActions, DialogClose, DialogContent, DialogDescription, DialogDismiss, DialogTitle, DialogTrigger, } from '@/components/ui/dialog'; ``` ```tsx Share workspace} /> Share this workspace Anyone with the link can open it. Cancel} /> Copy link} /> ``` `nativeButton={false}` follows the *material*. A glass `Button` is four stacked layers, which is invalid inside a native ` ; ``` `errors` is keyed by the `name` on each [`Field`](/docs/components/field). A bare `` with no `match` renders whatever the form routed to that field. ## Notes [#notes] ### It is the errors, and nothing else [#it-is-the-errors-and-nothing-else] There is no surface here, and there should not be. A form is a set of controls that each already carry their own glass; a panel behind them would be the backdrop every one of those lenses bends. That is the argument spelled out on [Fieldset](/docs/components/fieldset), one level down and unchanged. What the component is actually for is this: ```tsx
``` Base UI routes each message to the field with that `name`, so a server rejection lands under the control it is about rather than in a banner at the top of the page. Then `Field.Control` clears it on the next change to that field — the error goes away as you fix it, without your state having to notice. That behaviour is the entire reason to reach for `` over a ``, and it is worth knowing that it is *internal*: you set `errors` once from the response and never have to unset it. ### Validation timing [#validation-timing] ```tsx ``` `onSubmit` is the default, and it means what it says: fields are checked when the form is submitted, and re-check on change afterwards. That is the timing [Input](/docs/components/input#which-means-the-states-belong-to-a-child)'s invalid ring is built around — it waits for `data-touched` too, so a required field is not red before anyone has been near it. `validationMode` on a `Field` overrides the form's, which is how one awkward control gets `onChange` without dragging the rest of the page with it. ### Server functions [#server-functions] A form driven by `useActionState` passes `action` instead of `onSubmit`, and the error plumbing is identical: ```tsx const [state, formAction, pending] = React.useActionState(submit, {}); ``` Everything in this component is a `` underneath, so React's own form handling applies unchanged. # Components (/docs/components) Thirty-seven components, most of them a `LiquiGlass` surface with a Base UI primitive driving it. A few deliberately are not — a [separator](/docs/components/separator) is one pixel wide and has no room for a bezel, a [fieldset](/docs/components/fieldset) would only be a lens for the lenses inside it to bend — and those pages say why, because knowing where the material stops is part of using it. Every tile below is the real component rendering the real material. Open one to try it, read what is specific about putting it on glass, and copy the source `shadcn add` writes into your project. Every tile sits in a `LiquiBackdrop`, so it refracts in Safari and Firefox too. A popup a tile opens portals out of it and frosts there, which is worth seeing — see [Glass](/docs/handbook/glass#safari-and-firefox). ## Installing [#installing] Any one of them is a single command, and the first one you add brings the glass design tokens with it: ```bash npx shadcn@latest add https://liqui.design/r/button.json ``` See [Quick start](/docs) for the namespace setup if you are adding several. # Input (/docs/components/input) ## Installation [#installation] ```bash npx shadcn@latest add https://liqui.design/r/input.json ``` Installing more than one? Register the namespace once in `components.json` and drop the URLs: ```json title="components.json" { "registries": { "@liqui-design": "https://liqui.design/r/{name}.json" } } ``` ```bash npx shadcn@latest add @liqui-design/input ``` ## Usage [#usage] ```tsx import { Input } from '@/components/ui/input'; ``` ```tsx ``` `className` lands on the glass surface, because the surface is the component's box — `` has to widen the thing you can see, not a transparent element inside it. Use `inputClassName` for the `` itself. ## Slots [#slots] ```tsx } end={px} /> ``` ## Notes [#notes] ### The input cannot be the surface [#the-input-cannot-be-the-surface] `LiquiGlass` renders four layers — refracting backdrop, tint, specular rim, then your content on top. An `` is a replaced element: it has no place to put children, so those layers would have nowhere to go. That is the same constraint that keeps [Button](/docs/components/button) and [Select](/docs/components/select)'s trigger off the native `} /> Notifications You are all caught up. ``` `PopoverContent` collapses Base UI's portal, positioner and popup into one part. Positioner props pass straight through, so `side`, `align` and `sideOffset` work as documented — `sideOffset` just defaults to `10` to clear the tail rather than Base UI's `0`. `nativeButton={false}` on the trigger: a *glass* `Button` is not a native `} /> Undo — ⌘Z ``` `TooltipTrigger` is the one trigger in the library that does **not** want `nativeButton={false}`. It doesn't run Base UI's button hook, so it takes the element you render as-is and a liqui [Button](/docs/components/button) drops straight in. ## Examples [#examples] ### Sides [#sides] ## Notes [#notes] ### It carries more frost than anything else [#it-carries-more-frost-than-anything-else] A tooltip is a line of small text with no container of its own, sitting wherever the pointer happens to be. At the library default of `frost: 0.35` its legibility is whatever the wallpaper underneath decides, which for a component whose whole job is to be read is the wrong trade. `TooltipContent` runs `frost: 0.7` — roughly Apple's *regular* material. Still glass, still refracting, but carrying its own contrast. The optics are scaled down to match the box: ```ts { radius: 5, blur: 1, refraction: 30, bezel: 6, frost: 0.7 } ``` The label is 11px, the size macOS sets its tooltips in, so the chip is 20px tall — and a rounded rectangle rather than a pill, as macOS draws it. A 20px chip driven at a menu's `refraction: 120` is all bezel and no glass. With [Checkbox](/docs/components/checkbox) and [Radio](/docs/components/radio-group) now flat, this is one of the smallest surfaces the lens is still asked to render, and it is a good place to check a global `refractionScale` you have pushed up. ### No tail, on purpose [#no-tail-on-purpose] [Popover](/docs/components/popover#the-tail-is-the-material-minus-the-lens) has one and this doesn't, which is a size decision rather than a taste one. A tail can wear the popup's blur and tint. What it cannot wear is the kernel's specular layer — that is an image generated for the surface's own box, and a shape outside that box has no access to it. On a panel the gap shows up as a few pixels along one edge of something large. On a 28px chip it is most of the join: the tail comes out darker than the edge it hangs off, and the seam ends up more noticeable than the pointing it was there to do. A tooltip is already adjacent to the thing it describes and only exists while that thing is hovered, so it has less need to point than a popover does. If you want one anyway, the popover's `PopoverArrow` is the pattern to copy — retune the blur and fill for `frost: 0.7` before you do. ### One provider per group [#one-provider-per-group] `TooltipProvider` shares a delay across the tooltips inside it: once one has opened, moving to its neighbours shows theirs instantly. That is what makes a row of icon buttons read as one control rather than three. Base UI marks those instant openings with `data-instant`, which the popup uses to skip its own scale-in — a tooltip that animates while the pointer is already past it is just lag. Skip the provider and each tooltip waits out its own delay. # Glass (/docs/handbook/glass) Most liqui components are a `LiquiGlass` surface with a component-shaped content layer on top. Understanding the material is most of understanding the library — and knowing [which components are deliberately not made of it](#not-everything-is-glass) is the rest. ## The anatomy [#the-anatomy] A surface is four stacked layers plus your content: | Layer | What it does | | -------------- | -------------------------------------------------------------------- | | **Backdrop A** | `blur()` + `saturate()`. Never changes after first paint. | | **Backdrop B** | Displacement only — `backdrop-filter: url(#…)`, sampling A's output. | | **Tint** | A gradient carrying legibility, scaled by `frost`. | | **Specular** | A canvas-rendered rim light that makes the edge read as polished. | | **Content** | Your children, above all of it. | Blur and displacement are on **separate layers** deliberately. While the filter's `feImage` decodes its map, Chromium treats an entire `url(#f) blur() saturate()` chain as inert — combined on one layer, even the base blur would pop in late. Split, the surface is frosted from the first frame and refraction fades in over it. ## It needs something to refract [#it-needs-something-to-refract] Those are the three Button variants on a flat fill. The two solid ones look exactly as they do anywhere else. The glass one has gone slack — it is not broken, there is simply nothing behind it to bend. Glass is a lens; a lens over a solid colour shows you the solid colour. Put surfaces over photography, video, a gradient with real edges, or content that scrolls underneath. If your design calls for glass on a flat background, you want `material="clear"` and a tint, not refraction. ## Not everything is glass [#not-everything-is-glass] The line the library draws is the one Apple draws, and it is not about which components are important enough to get the nice material: > **Glass is for a surface you act *through*. A solid fill is for a control > that carries a *value*.** Buttons, popups, menus, toolbars, sheets and dialogs are the first kind — they are the layer floating over your content, and letting that content through is what the material is for. Checkbox, [Radio](/docs/components/radio-group), [Toggle](/docs/components/toggle) and [Switch](/docs/components/switch) are the second, and they are flat: `--lq-control` with a hairline at rest, `--lq-accent` when they are on. [Button](/docs/components/button) sits on both sides of the line, which is why it is the clearest illustration of it. Its default variant is glass, because pressing a button *does* something. Its `accent` and `danger` variants are solid, because those say *this is the one* — and a tinted lens contradicts itself: the colour is the whole message, and the lens exists to let the wallpaper through it. Accent over a night photograph and accent over a bright one were two different colours. This is also why a brand colour never needs `frost` tuning in liqui. Nothing carrying `--lq-accent` is a backdrop-filtered surface, so there is no transparency for a backdrop to leak through in the first place. ## The dials [#the-dials] | Prop | Range | What it controls | | -------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `frost` | 0–1 | Material density. `0` ≈ Apple's *clear* (needs a busy backdrop and its own dimming), `1` ≈ *regular* (adaptive frosted, safe anywhere). Default `0.54`. | | `refraction` | px | `feDisplacementMap` scale — how hard the rim bends. | | `bezel` | px | How wide the refracting rim is. Menus want \~28, buttons \~11. | | `blur` | px | Base blur. `frost` adds up to 14px on top. | | `dispersion` | 0+ | Chromatic aberration. Costs \~3× filter work — leave at `0` unless it's a hero surface. | | `specular` | 0–1 | Rim light opacity. | | `radius` | px | Corner radius. Also drives the displacement map's shape. | | `corner` | `squircle` \| `round` | Corner shape. `squircle` (default) is the continuous corner, drawn 1.4× where `corner-shape` renders so it reads as large as a round one. `round` is a plain circular arc at exactly `radius`, map and lighting included. A capsule or a disc is round either way. | | `material` | `auto` \| `frost` \| `clear` | Rendering tier. `auto` refracts where the browser can, copies a `LiquiBackdrop` where it cannot, and frosts elsewhere. | | `finish` | `classic` \| `prism` | How the surface is lit. `classic` lights the top and bottom edges and frosts the pane. `prism` is one key light, a dark far rim, a hairline round the outline and a brightened, lightly tinted interior — glass type, as a surface. Wants a narrow bezel, a soft bend and a colour fringe; `prismGlassTheme` is that tuning. | | `lightAngle` | ° | Where the light comes from, clockwise from above. Unset, the finish's own: `0` for classic, `1` for prism. | | `edgeShade`, `hairline`, `brightness`, `tintFloor` | 0–1 | The rest of the lighting: shade on the edges facing away from the light, opacity of the outline, brightness pushed through the glass, and the tint left at `frost: 0`. Each follows the finish unless set. | Each of these is a per-surface prop, and the components set the geometric ones (`radius`, `refraction`, `bezel`) to values scaled to their own size. To move them all at once — or to change the colours — see [Theming](/docs/handbook/theming). ## Corners [#corners] Every corner in liqui is a continuous one — the squircle Apple draws, where the curve eases out of the straight edge instead of meeting it at a seam — and every component draws it the same way. **A glass surface** gets it from the kernel. `radius` is the round-corner size you mean; where `corner-shape: squircle` renders (Chromium 139+), the kernel raises it 1.4× so the softer curve reads the same size, and draws the map and the lighting on that curve. A surface whose corners reach half its height is a capsule or a disc, and keeps a true semicircle — a superellipse cannot close into one. `corner="round"` opts a surface out: a plain circular arc at exactly `radius`, for the few shapes the system itself draws that way. **Anything inside a surface** — a hover wash, a highlighted menu item, a pressed toggle — follows the surface. The surface publishes its corner as `--lq-radius` and its shape as `--lq-corner`, and a container states its inset once, next to its padding, with the height of what it holds: ```tsx // The container: its padding, and its items' height.
{/* The item: the surface's radius less the inset, on the surface's shape. */}
``` Same centre, parallel curves, an even gap all the way round — and a theme's `radiusScale` reaches the items through the surface, so they never drift out of step with it. Where the concentric radius comes out at half an item's height or more, the item is a capsule, and `lq-nest` gives it half its height on round corners — the rule the kernel applies to a surface. On a capsule strip the items come out capsules too. **Anything with a radius of its own** — a solid button, a checkbox, a chip — takes `lq-squircle`, with its radius as written and its height: ```tsx ``` It gets exactly what a glass surface gets from the kernel: the radius 1.4× larger where the squircle renders, times the theme's `radiusScale`, and a true capsule once that reaches half the height. A box *around* a glass surface — the groove a tab indicator slides in — is the surface's corner plus the inset. Circles and pills stay `rounded-full`. Safari and Firefox do not draw `corner-shape` yet. There every corner is round at the radius as written — the same look liqui had before the squircle. ## Performance budget [#performance-budget] The expensive parts are the canvas-generated displacement map and the `backdrop-filter` chain, in that order. * **Maps are cached** module-wide, keyed by size + optics. Ten buttons of the same size cost one map. * **Filters are hoisted** into a single persistent hidden `` registry, so a remounted surface references an already-decoded filter and refracts on the first frame. This is why reopening a menu has no warm-up. * **Generation is half-resolution** above roughly 180×180. * `dispersion > 0` triples the filter work. Reserve it. * Stacking many large `backdrop-filter` surfaces is the one thing that will actually cost you frames. Prefer one large surface over a dozen small ones. ## Safari and Firefox [#safari-and-firefox] Refraction is `backdrop-filter: url(#svg)`: the page behind the surface, run through the displacement filter. Chromium draws that. Safari drops the whole `backdrop-filter` value when it references an SVG filter, and Firefox ignores it (WebKit bug 245510 has an implementation in review). What both *do* draw is the same SVG filter on an element's own content — so a surface that knows what is behind it can refract a copy of that instead. `LiquiBackdrop` is how it knows. It is a positioned box that paints `backdrop` behind its children, and every `LiquiGlass` inside it copies that backdrop when the page cannot be refracted, offset by its own position in the box: ```tsx import { LiquiBackdrop, LiquiGlass } from '@liqui-design/glass'; }> … ``` The home stage and every preview on this site are one, which is why they refract in Safari. The copy is only ever the backdrop, so two kinds of surface stay on frost: one nested in another surface (what is behind a button on a panel is the panel), and one portalled out of the box (a popup). Both keep the rim. If something inside the box moves by a transform — a drag — pass a `revision` that changes with it, since no observer sees a transform. ### Rendering tiers [#rendering-tiers] Each surface picks a tier when it mounts, by feature detection, best first. There is nothing to configure. | Tier | What it draws | Chromium | Safari, Firefox | | ----------------------- | --------------------------------------- | ------------------ | ------------------------ | | **Backdrop refraction** | The page behind the surface, displaced | Every surface | — | | **Copy refraction** | A copy of the known backdrop, displaced | — | Inside a `LiquiBackdrop` | | **Frost** | Blur, tint and the baked rim | `material="frost"` | Everywhere else | | **Clear** | Tint and rim, no backdrop filter | `material="clear"` | `material="clear"` | The baked rim — highlight, edge line, hairline — is a pair of images, not a filter, so it is the same on every tier but clear, in every browser. ### Capabilities [#capabilities] | Capability | Chromium¹ | Safari | Firefox | | -------------------------------- | :-------: | :----: | :-----: | | Refraction over any content | ✅ | —² | —² | | Refraction over a known backdrop | ✅ | ✅³ | ✅³ | | Chromatic dispersion | ✅ | ✅³ | ✅³ | | Baked rim lighting | ✅ | ✅ | ✅ | | Frosted fallback | ✅ | ✅ | ✅ | | Continuous corners | ✅⁴ | —⁵ | —⁵ | * ¹ Chrome, Edge, Arc, Opera and other Blink browsers. * ² No SVG filter in `backdrop-filter` yet (WebKit bug 245510). The surface frosts. * ³ Inside a `LiquiBackdrop`. * ⁴ Chromium 139+, through `corner-shape: squircle`. * ⁵ Round corners at the declared radius — see [Corners](#corners). There *is* something to check: **look at your UI in Safari.** A design tuned to `frost: 0` can be unreadable on a surface with no backdrop to copy, because in the refraction tiers the lens was doing the work the tint would otherwise have to do. Also honour user preference — a surface that ignores `prefers-reduced-transparency` is an accessibility bug, not a style choice: ```css @media (prefers-reduced-transparency: reduce) { .liqui-glass { --lq-tint: var(--fd-background); --lq-tint-deep: var(--fd-background); } } ``` ## Two things that will bite you [#two-things-that-will-bite-you] **Never measure a surface with `getBoundingClientRect`.** Popups open under a `scale()` transition, and a rect measured mid-animation bakes a permanently undersized displacement map that nothing re-fires to correct. The result looks like weak frosted blur and is very hard to trace back. liqui uses `ResizeObserver` `contentRect` and `offsetWidth`, both of which are layout sizes and immune to transforms. **Never build the displacement map as an SVG data URI.** Chromium rasterizes `feImage` SVG sources with CSS features disabled — `mix-blend-mode` and modern `hsl()` silently do nothing, corrupting the map into a full-surface smear. Generate it on a canvas. ## Where to look next [#where-to-look-next] Tuning these dials is mostly a matter of having seen enough of the material. liqui grew out of [Liquid Glass Design](https://liquidglassdesign.com/?ref=liqui.design), a growing gallery of liquid glass and glassmorphism references — interfaces, artwork and motion, each with the style prompt used to recreate it. It is the fastest way to work out what you are actually aiming at before you start moving `frost` and `refraction` around. # Theming (/docs/handbook/theming) liqui is themed along two axes, and they work nothing alike. **Colour is CSS.** Every colour a surface paints comes from a `--lq-*` custom property. Change fourteen variables and the whole library changes with them — including the parts React never sees, like a popup portalled to `document.body`. **Optics are JavaScript.** `refraction`, `bezel`, `radius` and `profile` feed a canvas-generated displacement map and an SVG filter, so they cannot be custom properties. They are props, and they arrive globally through a provider. ## The editor [#the-editor] The theme editor turns both halves as dials and hands back exactly the snippets on this page. Open it from **Theme** in the header of any page: it docks beside the page, and the page you were reading becomes the preview. [/theme](/theme) is the same editor full-page, beside a fixed preview. Three things about it are worth knowing before you open it: * **It themes the whole site, not the panel next to it.** Walk back into the docs and every component page is wearing what you made. That is the only honest way to judge a theme — a swatch grid will not tell you whether your tint survives on a menu. * **It stays in your browser.** The theme is kept in `localStorage` and nothing is sent anywhere. **Export → Copy share link** encodes it into the URL if you want to hand it to someone. * **It only ever emits what you changed.** Both snippets, and the stored value, are a diff against the shipped theme — so a later liqui release retuning a default you never touched still reaches you. ## The tokens [#the-tokens] | Token | What it paints | | ------------------ | --------------------------------------------------------------------------------------------------- | | `--lq-text` | Content on glass. | | `--lq-text-dim` | Labels, placeholders, secondary text. | | `--lq-tint` | The glass itself — the light end of the tint gradient. | | `--lq-tint-deep` | The dark end of that gradient. | | `--lq-rim-hi` | The bright catch-light along the top edge. | | `--lq-rim-lo` | The dimmer counter-light along the bottom. | | `--lq-shadow` | Depth under an `elevated` surface. Two layers. | | `--lq-highlight` | The hover wash on interactive surfaces. | | `--lq-control` | The resting fill of a *flat* control — checkbox, radio, toggle. Not glass: nothing blurs behind it. | | `--lq-control-rim` | That control's hairline edge. Reads dark on a light theme and light on a dark one. | | `--lq-accent` | Prominent buttons, focus rings, checked state, selection. | | `--lq-danger` | Destructive fills. | | `--lq-danger-text` | The same red, dark enough to read as *text* on light glass. | | `--lq-scrim` | The wash behind a modal surface. | Everything else in the `--lq-` namespace is per-component plumbing — `--lq-tail-rim` on a popup's arrow, `--lq-radius` written per surface from the `radius` prop. Setting those globally does nothing useful. If you installed through the shadcn CLI, all fourteen are already in your `globals.css` under `:root` and `.dark`, and editing them there is the whole job. If you imported the stylesheet instead, override after the import: ```css @import '@liqui-design/glass/tokens.css'; :root { --lq-accent: #8b5cf6; --lq-tint: rgba(250, 246, 255, 0.4); } [data-theme='dark'], .dark { --lq-accent: #b794ff; --lq-tint: rgba(32, 22, 56, 0.58); } ``` Dark mode is keyed on **both** `[data-theme='dark']` and `.dark`: the first is liqui's own convention, the second is what next-themes writes. Write your overrides under both, or they will apply in only one of the two setups. The two selectors have the same specificity as `:root`, so an override block written after the import wins — but a `:root` override written after it also beats the stylesheet's *dark* block. Always write the pair. ## The optics provider [#the-optics-provider] ```tsx import { LiquiThemeProvider } from '@liqui-design/glass'; export function Providers({ children }: { children: React.ReactNode }) { return ( {children} ); } ``` The provider takes colour too — `theme.light` and `theme.dark` accept the same fourteen tokens and are written into a `