# Gooey (liquid-gooey) Liquid UI for React: touching pieces merge like goo, stretch and bow like liquid, while text, icons and images stay crisp. ## When to use - Floating action / plus button that splits into satellite actions (speed dial, "New file / Add image / New folder"). Effect: `morph`. - Toolbar, avatar group or chip cluster whose pieces should read as one merged surface. Effect: `morph`. - Slider thumb, segmented-control or tab indicator that should trail and stretch as it moves. Effect: `move`. - Draggable card, list row or dropdown pill that should bow while it is dragged. Effect: `bend`. - Two draggable photo cards that run molten into each other where they touch (before/after, "combine" gestures). Effect: `melt`. ### When not to use - Static layouts with nothing moving or touching. The liquid only shows while pieces meet or move. - Dense lists or grids of many items. Every group runs an SVG filter; WebKit rasterises it on the CPU. - Non-React stacks. The package is React-only (no vanilla build, no custom element). - Pieces with opaque backgrounds you cannot remove. The liquid is the surface; an opaque child hides it. ## Install ```bash npm install liquid-gooey pnpm add liquid-gooey yarn add liquid-gooey ``` ```tsx import { Liquid } from 'liquid-gooey' ``` - React component only: `` (the group) and `` (each piece). - Peer dependencies: `react >=18`, `react-dom >=18`. No runtime dependencies. - ESM and CJS builds, TypeScript types included. - The dist has no `"use client"` directive. In the Next.js App Router, put the component that renders `` in a file that starts with `"use client"`. - Cross-browser, Safari included: the filters run on SVG content, never CSS `url()` filters on HTML. ## Basic usage The detail page's Install & Usage tab (React is the only platform): ```tsx import { Liquid } from 'liquid-gooey' ``` The playground under the examples also renders a live "Copy Studio code" snippet for the selected effect. At its defaults (dark page) it produces: ```tsx // Effect: Morph import { Liquid } from 'liquid-gooey' ``` ```tsx // Effect: Move
``` ```tsx // Effect: Bend
…
 ``` ```tsx // Effect: Melt ``` `blur` and `contrast` are omitted from the live snippet while they sit at their defaults (6 and 18). ## Options (free) | Option / prop | Values | Default | What it does | | --- | --- | --- | --- | | `Liquid.Item effect` | `"morph"`, `"move"`, `"bend"`, `"melt"` | `"morph"` | Morph: pieces merge and split. Move: the surface trails a moving element with a droplet tail. Bend: the body bows with drag velocity. Melt: two images run molten into each other. | | `Liquid blur` | 0 to 16, step 0.5 | `6` | Goo blur in px. Higher bridges pieces from farther apart and reads softer. Not used by `melt`. | | `Liquid contrast` | 4 to 40, step 1 | `18` | Sharpness of the liquid edge. Higher is crisper and beadier; lower is hazier. Not used by `melt`. | | `Liquid fill` | any CSS colour | `'#fff'` | Colour of the liquid surface. Page snippets use `"#fff"`, `"#202020"` (morph, bend) and `"#525252"` (move). | | `Liquid shadow` | `box-shadow` syntax, multi-layer | none | Shadow drawn on the merged silhouette, so it follows every merge and split. | | `Liquid.Item x`, `y` | number (px) | `0` | Morph position offset. The library animates the element and its liquid together. | | `Liquid.Item transition` | `"snappy"`, `"smooth"`, `"bouncy"`, or `{ duration, ease }` | `"smooth"` | Timing for `x`/`y` changes. | | `Liquid.Item delay` | ms | `0` | Delay before an `x`/`y` transition starts. Use it to stagger. | | `Liquid.Item move` | `{ stretch: 0.6, trail: 0.35 }` in the page snippet | library tuning | Move-only tuning object. The page shows these values; it does not expose sliders for them. | The playground tuner has three controls: the Effect tabs (Morph / Move / Bend / Melt) set `effect`, "Goo blur" sets `blur`, and "Contrast" sets `contrast`. Blur and contrast are hidden for Melt, which carries its own surface tuning. Fill, shadow, `x`/`y`, `transition` and `delay` come from the Install & Usage snippet and the Copy prompt text, not from tuner controls. Rule of thumb from the package docs: neighbours bridge once `blur` is roughly as large as the gap between them. Items 8px apart barely bridge at `blur={5}` and merge cleanly at `blur={12}`. ## Recipes ### Plus menu that splits into actions (morph) Use when: a floating "+" button should bloom into two or three action buttons. ```tsx import { useState } from 'react' import { Liquid } from 'liquid-gooey' const ACTIONS = [ { label: 'New file', x: -54, y: -34 }, { label: 'Add image', x: 0, y: -64 }, { label: 'New folder', x: 54, y: -34 }, ] export function PlusMenu() { const [open, setOpen] = useState(false) return ( // Sized to hold the open footprint; items stack at one slot. {ACTIONS.map((a, i) => ( ))} ) } ``` `.round-btn` is 40x40, `border-radius: 50%`, `background: transparent`. ### Liquid slider thumb (move) Use when: a custom range control should feel like a drop of liquid being dragged. ```tsx