# 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
FirstPanel 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 `
## Notes [#notes]
### It refracts a dimmed backdrop [#it-refracts-a-dimmed-backdrop]
This is the only surface in the library sitting on a scrim. That changes how the
dials read: the page behind is already darkened and blurred by
`--lq-scrim` + `backdrop-blur-[2px]`, so a `frost` value tuned against bare
wallpaper will look far too heavy here.
Tune dialog optics against the scrim, not against the other components.
### Alert vs. dialog [#alert-vs-dialog]
`AlertDialog` is deliberately modal and un-dismissible by click-outside or
`Escape` — Base UI enforces that. It is for decisions the user must answer, not
for a panel they might wander away from. Reach for
[Dialog](/docs/components/dialog) otherwise — same surface, same scrim, but
dismissible and with a corner close.
# Autocomplete (/docs/components/autocomplete)
## Installation [#installation]
```bash
npx shadcn@latest add https://liqui.design/r/autocomplete.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/autocomplete
```
## Usage [#usage]
```tsx
import {
Autocomplete,
AutocompleteClear,
AutocompleteContent,
AutocompleteEmpty,
AutocompleteInput,
AutocompleteInputGroup,
AutocompleteItem,
AutocompleteList,
} from '@/components/ui/autocomplete';
```
```tsx
No token matches that.
{(token: string) => (
{token}
)}
```
## Notes [#notes]
### What it is, against Combobox [#what-it-is-against-combobox]
They are separate Base UI primitives and separate files here, for the reason
[Menu and ContextMenu](/docs/components/menu) are copies: a registry item is one
file, and sharing the classes would mean a third item that neither component
works without.
The difference is what the control is *for*. A
[combobox](/docs/components/combobox) picks an item out of a set and remembers
which one; an autocomplete suggests completions for a string and hands you the
string. Reach for this when the answer does not have to be on the list.
That has one visible consequence:
```tsx
'flex … px-3 py-[7px]'; // no 16px indicator gutter
```
There is no `ItemIndicator` in this component's anatomy, because nothing in a
suggestion list is ever "the current one". So the rows sit flush instead of
reserving a check column down the left the way a
[select](/docs/components/select)'s do. A gutter with nothing that can ever
appear in it is a margin pretending to be a control.
### The optics are Combobox's, and the argument is sharper [#the-optics-are-comboboxs-and-the-argument-is-sharper]
This popup opens *while* you type, so it resizes constantly — and nothing here
transitions height, for the reason written out in full on
[Combobox](/docs/components/combobox#snapping-is-not-a-compromise-here): a
filtered list lands on a small set of discrete heights that repeat, and every
one of them after the first pass is a cache hit. A resize animation would build
a new displacement map on every frame instead.
If you only read one line of it: **discrete resizes are cheap, continuous ones
are not.**
### `useFilter` for anything but "starts with" [#usefilter-for-anything-but-starts-with]
Base UI exposes its matcher on the component:
```tsx
const filter = Autocomplete.useFilter({ sensitivity: 'base' });
```
Pass your own `items` filtered however you like, and everything on this page
still applies — the popup's size is a consequence of how many rows survive, and
none of the optics care why.
# Avatar (/docs/components/avatar)
## Installation [#installation]
```bash
npx shadcn@latest add https://liqui.design/r/avatar.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/avatar
```
## Usage [#usage]
```tsx
import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
```
```tsx
LT
```
`AvatarFallback` renders when the image fails or when there is no image at all.
`delay` holds it back for the given number of milliseconds so a picture that is
merely slow does not flash initials on its way in.
## Sizes [#sizes]
```tsx
…
```
## Notes [#notes]
### The picture is inset by the bezel [#the-picture-is-inset-by-the-bezel]
`LiquiGlass` renders content above every glass layer. That is the right stacking
for every other component in the library — a menu item does not reach the edge,
a [progress](/docs/components/progress) track is mostly empty, a
[button](/docs/components/button) is a label in the middle of a box — and it is
exactly wrong for an avatar, whose content is the whole disc by default.
A full-bleed photo covers the tint, the specular arc and the entire bezel. Not
dims: covers. What is left is a round `` with a shadow under it, and the
surface underneath is doing real per-pixel work that nobody can see.
So the picture is inset by the width of the bezel:
```tsx
{children}
```
The glass keeps a ring of itself all the way round, and that ring is the part
that refracts the page. The avatar reads as a porthole — a lens with something
behind it, which is what the material is for. With no picture the whole disc is
glass and the initials float on it.
### `size` is a prop, not a class [#size-is-a-prop-not-a-class]
Three numbers are derived from the diameter, and none of them can come from a
`size-*` class:
```tsx
const ring = Math.max(3, Math.round(size * 0.17));
;
```
`radius` has to be exactly half the box or the displacement map's corners stop
matching the circle the element is drawn as, and you get a rounded square's
corners bending inside a circle's outline. `bezel` is also the visible ring, so
it has to shrink with the disc — the same 0.17 ratio the
[checkbox](/docs/components/checkbox) runs (6px on a 20px box), which is where
the library's smallest surfaces bottom out. And `refraction` is a displacement
in pixels, so it scales for the reason the
[contributing rules](https://github.com/leefanv/liqui-design/blob/main/CONTRIBUTING.md)
give: bezel is a fraction of the box, and small components need smaller numbers.
The checkbox can pin its optics because it is one fixed size. An avatar is not,
so the numbers scale instead. Font size rides along too — the fallback's initials
are `1em` against a root sized at `0.36 × size`, which is what makes one class
work at every diameter.
Passing `className="size-16"` will not work: the width and height are inline
styles and inline wins. That is deliberate — a class that changed the box without
changing the optics would give you a 64px disc wearing a 40px avatar's rim.
### There is no AvatarGroup [#there-is-no-avatargroup]
The overlapping stack is the most-requested avatar layout and it is the one thing
this material cannot do honestly. Two glass discs that overlap are two lenses in a
line: the upper one's backdrop is the lower one's tint and specular rim, so its
bezel refracts a piece of UI instead of the page — the same failure
[Select](/docs/components/select) had to design around when its popup opened over
its own trigger, and the reason a
[toggle inside a group](/docs/components/toggle-group) goes flat.
Every other library solves it with a ring of the page's background colour punched
around each disc. There is no page background colour here; that is the whole
premise.
If you want the stack anyway, the honest version is to drop the discs out of the
refraction tier, so what overlaps is tint and rim rather than lens:
```tsx
```
Ten lines in your project, where you can see what it costs, beats an export that
quietly turns the glass off.
### Images travel as text [#images-travel-as-text]
The demo above builds its portraits as SVG data URIs rather than pointing at
files, for the reason the
[media player](/templates/media-player) template gives at length: a registry item
is UTF-8 text from end to end, so a demo that referenced `/portrait.jpg` would
install a 404 into your project. Your own avatars are ordinary `src` strings —
nothing about the component cares.
# Button (/docs/components/button)
## Installation [#installation]
```bash
npx shadcn@latest add https://liqui.design/r/button.json
```
This writes `components/ui/button.tsx` into your project, adds the glass design
tokens to your `globals.css`, and installs `@liqui-design/glass` — the refraction
kernel, which stays a dependency because it is not something you should be
editing. Everything you *would* want to edit is in the file you just received.
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
```
## Usage [#usage]
```tsx
import { Button } from '@/components/ui/button';
```
```tsx
Save
```
## 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 `` [#only-the-glass-variant-opts-out-of-button]
The glass anatomy is four stacked layers plus a content wrapper. A native
`` only accepts phrasing content, so those wrapper `
`s would be
invalid HTML inside one. The glass variant passes `nativeButton={false}`, which
is Base UI's supported escape — `useButton` then supplies `role="button"`,
`tabIndex` and the Enter/Space handlers itself.
`accent` and `danger` have no anatomy to put anywhere, so they are real
`` elements, and the thing `nativeButton={false}` cannot give back comes
back with them: **implicit form submission**.
```tsx
// Submits the form. No `nativeButton`, no workaround.
Claim handle
```
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
⇧⌘NMove 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
```
`nativeButton={false}` follows the *material*. A glass `Button` is four stacked
layers, which is invalid inside a native ``, so it is not one — and Base
UI warns unless the composing component is told so. The solid `accent` close is
a real button again and says nothing. See
[Button](/docs/components/button#only-the-glass-variant-opts-out-of-button).
## Notes [#notes]
### Dialog or Alert Dialog [#dialog-or-alert-dialog]
They share a surface and differ in what they will let the user do.
[Alert Dialog](/docs/components/alert-dialog) refuses `Escape` and
click-outside, because it is asking a question that has to be answered. `Dialog`
takes both, plus the corner `DialogDismiss` — it holds content the user is free
to wander away from.
### Tune it against the scrim [#tune-it-against-the-scrim]
Like Alert Dialog, this is a surface sitting on a dimmed backdrop rather than on
the page. `--lq-scrim` plus `backdrop-blur-[2px]` have already darkened
everything behind it, so a `frost` value tuned against bare wallpaper reads far
too heavy here. Judge dialog optics against the scrim.
### The dismiss stays flat [#the-dismiss-stays-flat]
The × in the corner is not a liqui `Button`. Anything inside the popup has the
dialog's own tint behind it rather than the page, so a second surface there has
nothing to bend but the first one — it is the same rule as
[Switch](/docs/components/switch)'s opaque thumb and
[Slider](/docs/components/slider)'s flat rail: **one surface per control gets to
refract**.
A 28px icon target has nothing left over to survive that on. The action buttons
below it do — their labels carry them and their retint is dense enough — which is
why they keep their glass and the dismiss is only a hover wash and a focus ring
painted on the surface already there.
[Popover](/docs/components/popover#controls-inside-a-popover-go-flat) covers the
general judgement, and `material: 'clear'` when you need to make it explicit.
# Drawer (/docs/components/drawer)
## Installation [#installation]
```bash
npx shadcn@latest add https://liqui.design/r/drawer.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/drawer
```
## Usage [#usage]
```tsx
import {
Drawer,
DrawerBody,
DrawerClose,
DrawerContent,
DrawerDescription,
DrawerHandle,
DrawerTitle,
DrawerTrigger,
} from '@/components/ui/drawer';
```
```tsx
}>Export project
Export project…
```
`side` and `swipeDirection` are two props because they are two decisions — a
bottom sheet with `snapPoints` is often swiped *down to a smaller size* rather
than away. For a plain panel they match.
## From the side [#from-the-side]
## Notes [#notes]
### A big surface is not an expensive one [#a-big-surface-is-not-an-expensive-one]
The displacement map is generated per pixel on a canvas, so a full-width sheet
sounds like the worst case. Two things make it the opposite.
The kernel renders maps for large surfaces at **half resolution**. Displacement
vectors and the specular glow are smooth fields, so stretching them back up is
invisible, and generation plus the PNG decode get roughly four times cheaper.
And a drawer has exactly one size per side, so after the first open every
subsequent one is a cache hit for the rest of the session.
Compare that with [Accordion](/docs/components/accordion), whose items are small
and whose maps are legion because they animate their height. Size is not what
costs; *change* of size is.
### The swipe cannot rebuild a filter [#the-swipe-cannot-rebuild-a-filter]
```tsx
'transition-transform duration-[450ms]';
'data-[swiping]:duration-0';
```
Transform only. Dragging translates the sheet, and the map is keyed on size and
optics — neither of which a translate touches. The repo asserts exactly this in
`checks.spec.ts` by dragging a surface and checking that no filter was recreated.
Which matters more here than anywhere else: a swipe is the one interaction where
a rebuild would be visible as lag, frame by frame, under the reader's finger. It
is also the one interaction that structurally cannot cause one.
Nothing in this component animates width or height for the same reason. A sheet
that resized as it moved would build a new map per frame, which is the failure
[NavigationMenu](/docs/components/navigation-menu#the-panel-moves-and-does-not-resize)
is designed around.
### The scrim changes what you are judging [#the-scrim-changes-what-you-are-judging]
```tsx
'bg-[var(--lq-scrim)] backdrop-blur-[2px]';
'opacity-[calc(1-var(--drawer-swipe-progress))]';
```
The scrim sits between the sheet and the page, so a `frost` tuned over bare
wallpaper reads far too heavy here — the same warning
[Dialog](/docs/components/dialog) gives. Judge drawer optics against a dimmed
page.
The scrim also tracks the gesture: drag the sheet halfway out and the page behind
it is already half back, because its opacity is a function of
`--drawer-swipe-progress`. `data-[swiping]:duration-0` is what keeps it on your
finger instead of 450ms behind it.
### The handle is flat [#the-handle-is-flat]
A grab bar is a small box inside a big surface, so it is a pill of colour rather
than its own lens — one more instance of the rule that puts a wash on
[Dialog](/docs/components/dialog)'s dismiss and flattens a
[toggle inside a group](/docs/components/toggle-group). A lens there would be
bending the sheet it is lying on.
### Tailwind cannot see a class you built at runtime [#tailwind-cannot-see-a-class-you-built-at-runtime]
Worth stating because it is the bug this file was written around:
```tsx
// Never — Tailwind reads the source, so this class never reaches the stylesheet
`data-[ending-style]:${layout.closed}`;
```
The four sides are written out as literal strings in a lookup table. The
repetition is the price of Tailwind being a compiler, and it is cheaper than a
drawer that silently refuses to animate out.
# Field (/docs/components/field)
## Installation [#installation]
```bash
npx shadcn@latest add https://liqui.design/r/field.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/field
```
## Usage [#usage]
```tsx
import {
Field,
FieldControl,
FieldDescription,
FieldError,
FieldLabel,
} from '@/components/ui/field';
```
```tsx
Workspace nameLowercase letters, numbers and dashes.
```
## Examples [#examples]
### Validation [#validation]
Base UI drives validity from the native constraint API, so `match` takes
`ValidityState` keys — `valueMissing`, `typeMismatch`, `patternMismatch` and the
rest.
## Notes [#notes]
### The input is not the surface [#the-input-is-not-the-surface]
The `` stays a plain transparent element *inside* the glass content
layer. Making the input itself the glass root would put the backdrop and tint
layers inside a replaced element, where browsers won't render them — you'd get
an input with no glass and no error explaining why.
### Rings live on the surface [#rings-live-on-the-surface]
Focus and invalid rings belong to the glass, not the input, so they wrap the
whole bezel instead of appearing inside it. The surface reacts to its child's
state through `has-*`:
```tsx
has-[input:focus-visible]:shadow-[0_0_0_3px_color-mix(in_srgb,var(--lq-accent)_35%,transparent)]
has-[input[data-invalid][data-touched]]:shadow-[0_0_0_2px_color-mix(in_srgb,var(--lq-danger)_55%,transparent)]
```
Note `data-touched` — the invalid ring only appears once the user has actually
interacted, so a form doesn't open covered in red.
# Fieldset (/docs/components/fieldset)
## Installation [#installation]
```bash
npx shadcn@latest add https://liqui.design/r/fieldset.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/fieldset
```
## Usage [#usage]
```tsx
import { Fieldset, FieldsetLegend } from '@/components/ui/fieldset';
```
```tsx
```
Disabling the fieldset disables everything in it, and `FieldsetLegend` dims with
it:
```tsx
```
## Notes [#notes]
### The container is not a surface [#the-container-is-not-a-surface]
The obvious thing to do with a fieldset is draw a box round it. It is the wrong
thing here, and the reason is the same one that runs through the whole library.
What goes inside a fieldset is [fields](/docs/components/field) and
[switches](/docs/components/switch) — lenses, both of them. A glass panel behind
them becomes the backdrop those lenses bend, so each control refracts the
panel's tint and specular rim instead of the page. The group stops reading as a
set of surfaces on a wallpaper and starts reading as one flat slab with dents
pressed into it.
The flat controls in there — [checkbox](/docs/components/checkbox),
[radio](/docs/components/radio-group) — have no lens to spoil and would survive
the panel intact. They would simply stop looking like they belong to the same
form as the controls that do.
You have seen this decision three times already:
[a toggle inside a group](/docs/components/toggle-group) goes flat because the
strip is the surface, the [dialog](/docs/components/dialog)'s dismiss is a wash
on a panel that is already there, and there is
[no AvatarGroup](/docs/components/avatar#there-is-no-avatargroup) at all. A
fieldset is the strongest form of the same answer: the container simply is not a
surface.
If a section genuinely needs to sit on its own panel, put the panel *outside*
and let it hold one group:
```tsx
```
Then the controls inside are lenses on a lens, and that is the trade you have
made knowingly rather than one the component made for you.
### `min-width` is the reset that matters [#min-width-is-the-reset-that-matters]
```tsx
'flex min-w-0 flex-col gap-3.5 border-none p-0';
```
A native `