# liquefy-ui

> A TypeScript UI library for React that renders highly transparent Liquid Glass
> through WebGL optics, physical springs and Base UI accessibility primitives.
> Independent open-source project, not affiliated with Apple Inc.

```bash
pnpm add @liquefy-ui/react @liquefy-ui/core @liquefy-ui/icons
```

```tsx
import { LiquefyProvider, LiquidButton } from '@liquefy-ui/react'
import '@liquefy-ui/react/styles.css'
// Using Tailwind v4? Import '@liquefy-ui/react/tailwind.css' instead, before
// 'tailwindcss', and the bridged tokens plus the correct layer order come with it.

export function App() {
  return (
    <LiquefyProvider theme="system" tint="#8f8f8f">
      <LiquidButton>Create magic</LiquidButton>
    </LiquefyProvider>
  )
}
```

Or copy the source into your own repo with the shadcn CLI. The namespace is
registered in shadcn's registry directory, so it resolves with nothing added to
`components.json`:

```bash
npx shadcn@latest add @liquefy-ui/liquid-button
```

The `https://liquefy-ui.com/r/<name>.json` URL that namespace resolves to still works, and
is what a CLI too old to know the directory needs.

Rules an agent should not have to guess:

- Every component is a client component. The npm bundles carry a `'use client'`
  banner and so does every file in the registry, so importing from a Next.js
  server component is fine. Only your own handlers need a directive of their own.
- `LiquefyProvider` is required. Components read tint, spacing, motion and WebGL
  settings from it. A nested provider does **not** inherit from the one above it:
  unset props fall back to the library defaults, so name what you want to keep.
- There is no `variant="primary"` on `LiquidButton`. Buttons vary by `size`,
  `tint`, `isLoading`, `lens` and `webgl`. `variant` exists on `LiquidSurface`
  (`'clear' | 'tinted'`) and `LiquidChip`.
- Every component accepts a `styles` prop: CSS properties plus the `p`/`px`/`mt`/
  `w`/`h`/`size`/`bg`/`radius` shorthands on the `--lq-space` scale, `$token`
  references, responsive objects like `{ base: 1, md: 3 }`, and state keys such as
  `_hover`, `_focusVisible`, `_disabled`, `_dark`. There is no `styled()` and no
  `sx` prop.
- Everything is imported from the package root. There are no deep entry points,
  and names not listed below — `compileLiquidStyles`, `useLiquefyPortalContainer`,
  the internal glyphs — are not exported from it.
- Overlays (Dialog, Drawer, Menu, Select, Tooltip) are built on Base UI and render
  into a portal inside the provider. Focus handling, Escape and collision-aware
  placement are already done; do not re-implement them.
- Accordion headers are in the normal tab order rather than a roving composite,
  which is what WAI-ARIA specifies. Arrow keys do not move between them.
- The library does not read `prefers-reduced-motion` or
  `prefers-reduced-transparency` itself. Map them to the `motion` and
  `transparency` props if the product wants that.

## Components

- [GlassCard](https://liquefy-ui.com/llms/glass-card.md): A content card with eyebrow, title, description, body and footer slots on the liquid surface.
- [GlassDock, DockItem](https://liquefy-ui.com/llms/glass-dock.md): A macOS-style dock: a glass rail of icon buttons that magnify under the pointer.
- [LiquidAccordion, LiquidAccordionItem](https://liquefy-ui.com/llms/liquid-accordion.md): Stacked disclosure panels with real headings and a height-measured open animation.
- [LiquidAlert](https://liquefy-ui.com/llms/liquid-alert.md): An inline status message in four severities, with an optional dismiss button.
- [LiquidAvatar, LiquidAvatarGroup](https://liquefy-ui.com/llms/liquid-avatar.md): A circular avatar with image, initials and status dot, plus an overlapping group.
- [LiquidBadge](https://liquefy-ui.com/llms/liquid-badge.md): A small count or status pill for hanging off icons and labels.
- [LiquidBreadcrumbs](https://liquefy-ui.com/llms/liquid-breadcrumbs.md): A trail of links with glyph separators and a current-page marker.
- [LiquidButton](https://liquefy-ui.com/llms/liquid-button.md): The primary action control: WebGL rim light, jelly press spring and a loading state.
- [LiquidCheckbox](https://liquefy-ui.com/llms/liquid-checkbox.md): A checkbox with a springy tick, indeterminate state and label support.
- [LiquidChip](https://liquefy-ui.com/llms/liquid-chip.md): A compact tag that can be selected, tinted and dismissed.
- [LiquidDialog](https://liquefy-ui.com/llms/liquid-dialog.md): A modal on Base UI: trapped focus, inert background and wired-up title and description.
- [LiquidDivider](https://liquefy-ui.com/llms/liquid-divider.md): A hairline rule, horizontal or vertical, with optional inline content.
- [LiquidDrawer](https://liquefy-ui.com/llms/liquid-drawer.md): A side panel that slides from the left, right or bottom edge, on Base UI Dialog.
- [LiquidIconButton](https://liquefy-ui.com/llms/liquid-icon-button.md): A square icon-only button that takes its accessible name from a label prop.
- [LiquidList, LiquidListItem, LiquidListSubheader](https://liquefy-ui.com/llms/liquid-list.md): A glass list with items, descriptions, leading icons, trailing slots and subheaders.
- [LiquidMenu](https://liquefy-ui.com/llms/liquid-menu.md): A dropdown action menu on Base UI: arrow keys, typeahead and collision-aware placement.
- [LiquidPagination](https://liquefy-ui.com/llms/liquid-pagination.md): A page strip with ellipsis truncation and previous/next controls.
- [LiquidProgress, LiquidSpinner](https://liquefy-ui.com/llms/liquid-progress.md): A determinate progress bar and an indeterminate spinner sharing one accent.
- [LiquidRadioGroup, LiquidRadio](https://liquefy-ui.com/llms/liquid-radio.md): A radio group with a springy dot and keyboard-driven selection.
- [LiquidRating](https://liquefy-ui.com/llms/liquid-rating.md): A star rating that reads and writes a numeric value.
- [LiquidSegmented](https://liquefy-ui.com/llms/liquid-segmented.md): A segmented control whose glass indicator slides between options.
- [LiquidSelect](https://liquefy-ui.com/llms/liquid-select.md): A listbox dropdown on Base UI: typeahead, focus return and a glass popover.
- [LiquidSkeleton](https://liquefy-ui.com/llms/liquid-skeleton.md): A shimmering placeholder block for content that has not arrived.
- [LiquidSlider](https://liquefy-ui.com/llms/liquid-slider.md): A range input with a luminous track and a dimensional thumb.
- [LiquidSurface](https://liquefy-ui.com/llms/liquid-surface.md): The base material every glass component is built on: rim light, refraction and springs.
- [LiquidSwitch](https://liquefy-ui.com/llms/liquid-switch.md): A toggle whose thumb squashes as it travels.
- [LiquidTableContainer, LiquidTable, LiquidTableHead, LiquidTableBody, LiquidTableRow, LiquidTableCell, LiquidTableHeaderCell](https://liquefy-ui.com/llms/liquid-table.md): A composable data table on a glass container, with row hover and selection.
- [LiquidTabs, LiquidTabList, LiquidTab, LiquidTabPanel](https://liquefy-ui.com/llms/liquid-tabs.md): Composable tabs on Base UI, with a glowing underline that springs between them.
- [LiquidTextField](https://liquefy-ui.com/llms/liquid-text-field.md): A single-line text input with label, hint and invalid state.
- [LiquidTextArea](https://liquefy-ui.com/llms/liquid-textarea.md): A multi-line text input that keeps the field styling of LiquidTextField.
- [LiquidToastProvider, useLiquidToast](https://liquefy-ui.com/llms/liquid-toast.md): A toast provider and a useLiquidToast hook for transient messages.
- [LiquidTooltip](https://liquefy-ui.com/llms/liquid-tooltip.md): A glass bubble on hover and focus, positioned by Base UI so it stays on screen.

## Provider and internals

- [internal-glyphs](https://liquefy-ui.com/llms/internal-glyphs.md): The small inline SVG glyphs the components draw for chevrons, checks and status icons.
- [defaultBreakpoints, LiquefyProvider, useLiquefyConfig](https://liquefy-ui.com/llms/provider.md): LiquefyProvider and the config hooks every component reads its tokens from.
- [getLiquefyStyleSheet, useLiquidStyles](https://liquefy-ui.com/llms/styles-prop.md): The `styles` prop engine: shorthands, token references, breakpoints and state selectors.
- [useLiquidGlass](https://liquefy-ui.com/llms/use-liquid-glass.md): The hook that wires an element to the WebGL renderer and the motion springs.

## Icons

- [@liquefy-ui/icons](https://liquefy-ui.com/llms/icons.md): 44 rounded 24×24 SVG icons, one named export each
- [Icon gallery](https://liquefy-ui.com/#/components/icons): every icon, sized and stroked live

## Engine

- [@liquefy-ui/core](https://liquefy-ui.com/llms/core.md): the dependency-free renderer, lens filter and spring engine

## Reference

- [llms-full.txt](https://liquefy-ui.com/llms-full.txt): every exported type declaration and design token in one file
- [Registry index](https://liquefy-ui.com/r/registry.json): shadcn-compatible items for copying source
- [MCP server](https://liquefy-ui.com/llms/mcp.md): the same catalog as tool calls, for agents that call tools

## Optional

- [Component docs](https://liquefy-ui.com/#/components): live demos and prop tables (JavaScript required)
- [Documentation](https://liquefy-ui.com/#/docs): provider, theming, the styles prop, motion, frameworks, Tailwind, AI tooling, accessibility, performance, troubleshooting
- [Playground](https://liquefy-ui.com/#/playground): every provider prop as a live control