# Liquid swipe

> Full-bleed pages revealed by a liquid wave: the next page waits behind a breathing bulge on the edge, the bulge follows the finger 1:1 with its centre at the finger's height, and past the threshold or on a flick the liquid floods across and the page changes.

- Type: Component (navigation)
- Access: Pro
- Page: https://goodui.dev/native/components/liquid-swipe
- Markdown: https://goodui.dev/native/components/liquid-swipe.md
- Registry item: https://goodui.dev/native/r/liquid-swipe.json
- Dependencies: react-native-gesture-handler, react-native-reanimated, react-native-svg
- Keywords: react native liquid swipe, liquid page transition, wave onboarding, fluid swipe pager, liquid reveal expo, onboarding animation svg, blob page transition

## When to use

- A welcome or onboarding flow of two to six full-screen pages where each page owns a strong color.
- A showpiece intro, a lookbook or a mood picker: a few pages people flip through for the pleasure of it.
- A 'what's new' story after a big release, one feature per colored page.

## When not to use

- Plain onboarding with a Next button that grows into Get started: use page-dots-onboarding.
- Browsing content cards inside a screen: use carousel or card-deck-swipe.
- More than about six pages, or pages that scroll horizontally themselves: every page stays mounted and the pan belongs to the liquid.
- Switching between app sections: use tab-bar or top-tabs.

## Installation

With the shadcn CLI (needs a components.json in the Expo app), then `npx expo install --fix` so native dependencies match your Expo SDK. The foundation comes along the first time.

```bash
npx shadcn@latest add @goodui-native-pro/liquid-swipe
npx expo install --fix
```

Pro: add `"@goodui-native-pro": { "url": "https://goodui.dev/native/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${GOODUI_LICENSE_KEY}" } }` to the `registries` of components.json and put your license key in .env.local.

The component lands in `components/goodui-native/liquid-swipe/` and imports the foundation from `components/goodui-native/foundation/` with relative paths; it also installs locale.

Built-in strings follow `<GooduiLocaleProvider>` (one [language pack](https://goodui.dev/native/r/locale-tr.json) translates the whole kit); the `labels` prop overrides them for one instance.

## Usage

```tsx
import { View } from "react-native";
import { LiquidSwipe, type LiquidSwipePage } from "@/components/goodui-native/liquid-swipe/liquid-swipe";
import { Display, Text } from "@/components/goodui-native/foundation/text";

function Page({ title, body, ink }: { title: string; body: string; ink: string }) {
  return (
    <View style={{ flex: 1, justifyContent: "flex-end", padding: 24, paddingBottom: 64, paddingEnd: 88 }}>
      <Display size={30} style={{ color: ink }}>{title}</Display>
      <Text style={{ color: ink, opacity: 0.72 }}>{body}</Text>
    </View>
  );
}

const pages: LiquidSwipePage[] = [
  { key: "find", color: "#F3EADB", label: "Find the quiet places", render: ({ ink }) => <Page ink={ink} title="Find the quiet places" body="Trails and coves that are not in the guidebooks." /> },
  { key: "when", color: "#FF5A3C", label: "Go when it is empty", render: ({ ink }) => <Page ink={ink} title="Go when it is empty" body="Live crowd levels tell you the hour to set off." /> },
  { key: "keep", color: "#16325C", label: "Keep it offline", render: ({ ink }) => <Page ink={ink} title="Keep it offline" body="Maps stay on your phone, even with no signal." /> },
];

export function Welcome() {
  return <LiquidSwipe pages={pages} accessibilityLabel="Welcome tour" style={{ flex: 1 }} />;
}
```

## Examples

### Controlled, with your own Back and Next buttons

```tsx
const [index, setIndex] = useState(0);

<LiquidSwipe pages={pages} index={index} onIndexChange={setIndex} />
<Button variant="secondary" disabled={index === 0} onPress={() => setIndex(index - 1)}>Back</Button>
<Button onPress={() => setIndex(index + 1)}>Next</Button>
```

### Hint the gesture once on first launch through the handle

```tsx
const ref = useRef<LiquidSwipeHandle>(null);

useEffect(() => {
  // Pull the wave a fifth of the way, at mid height, then let it go: it springs back and wobbles.
  const a = setTimeout(() => ref.current?.pull(0.2, 0.5), 800);
  const b = setTimeout(() => ref.current?.release(), 1300);
  return () => { clearTimeout(a); clearTimeout(b); };
}, []);

<LiquidSwipe ref={ref} pages={pages} />
```

### Bulge near the top, a short pull is enough, no indicator

```tsx
<LiquidSwipe pages={moods} bulgeAt={0.34} threshold={0.2} indicator={false} haptic="pop" onIndexChange={setMood} />
```

## API reference

### LiquidSwipe

`import { LiquidSwipe } from "@/components/goodui-native/liquid-swipe/liquid-swipe";`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pages` (required) | `LiquidSwipePage[]` | – | The pages, in order. Built for two to six. |
| `index` | `number` | – | The settled page (controlled). Pair with `onIndexChange`. |
| `defaultIndex` | `number` | `0` | The first page (uncontrolled). Default 0. |
| `onIndexChange` | `(index: number) => void` | – | Called when a different page settles: at release, as the flood starts. |
| `ref` | `Ref<LiquidSwipeHandle>` | – | Imperative handle: `ref.current?.next()`, `back()`, `goTo(i)`, and `pull()` / `release()` for a scripted hint. |
| `threshold` | `number` | `0.35` | How far the wave must be pulled before letting go changes the page, as a share of the width. Default 0.35. A flick changes it from anywhere. |
| `bulgeAt` | `number` | `0.68` | Height at which the bulge rests, 0 (top) to 1 (bottom). Default 0.68, within thumb reach. |
| `breathe` | `boolean` | `true` | Let the resting bulge breathe to invite the gesture. Default `true`. Always off under reduced motion. |
| `indicator` | `boolean` | `true` | Show the page indicator. Default `true`. Screen readers keep their page control either way. |
| `indicatorOffset` | `number` | `24` | Distance of the indicator from the bottom edge. Default 24. Add the bottom safe area inset on full-screen pages. |
| `haptic` | `HapticName \| false` | `"whoosh"` | Cue as the page changes. `false` turns it off. Default `whoosh`. |
| `disabled` | `boolean` | `false` | Turns the gesture and the handle off; `index` and the ref still move the pages. |
| `accessibilityLabel` | `string` | – | Name of the pager for screen readers. Default "Pages". Same as `labels.pager`. |
| `labels` | `Partial<LiquidSwipeLabels>` | – | Overrides for the built-in strings; a GooduiLocaleProvider pack sets them app-wide. |
| `style` | `StyleProp<ViewStyle>` | – | Style for the outer container. |
| `testID` | `string` | – | Identifier for end-to-end tests. |

## Accessibility

- The page indicator is one adjustable control named by accessibilityLabel (default 'Pages') whose value is 'Page 2 of 4' plus the page's label; swipe up and down on it (increment and decrement) to change the page. On the web it is a slider: focus it and use the arrow keys, mirrored under RTL.
- The handle in the bulge is a button named 'Next page': double tap (the activate action) floods the next page in; on the web it takes focus and Enter or Space.
- Only the settled page is exposed: the others are hidden from screen readers and inert on the web, although they stay mounted for the liquid.
- A page change is announced with its position and label through AccessibilityInfo.announceForAccessibility.
- With indicator={false} the adjustable control stays, so screen reader and keyboard users can still change pages.
- Ink for the indicator and the chevron is picked per page from the page color (near-white on dark, near-black on light); pass page.ink when a brand color needs a specific one.

## Motion

- Idle: the bulge of the next page breathes, reaching out about 7 pt and slimming a little, on a 1.7 s sine loop.
- Touch down on the bulge: it swells toward the finger on the snappy spring before anything moves.
- Drag: the tip of the wave moves 1:1 with the finger; the wave's centre trails the finger's height on the snappy spring; a short pull is a narrow tongue, and the wave spreads along the whole edge as it goes. The page underneath drifts away a little.
- Reveal: the incoming page's content stays hidden during a short pull, then fades in behind the wave once the pull passes about a quarter of the width, drifting into place; where its window ends it dissolves into the liquid instead of being cut.
- Release past the threshold (35% of the width by default), or a flick faster than 500 pt/s: the liquid floods across on the smooth spring carrying the finger's velocity, and the bulge of the page after it grows out of the edge during the last quarter.
- Release earlier: the wave returns on the bouncy spring with the finger's velocity, squashes once behind its rest shape (shorter and a little taller) and settles.
- Dragging the other way pulls the current page back out to the edge with the tip under the finger; the same threshold and flick decide.
- next(), back(), goTo() and a controlled index move the liquid on the smooth spring; several pages flood or drain in sequence.
- Reduced motion: the wave still follows the finger, but releases, buttons and index changes jump to the result, there is no breathing, swell or content drift.

## Haptics

- select when the pull crosses the threshold in either direction
- whoosh (the `haptic` prop) as the page changes by a release, a tap on the handle or on the indicator; changes through the ref, a controlled index or a screen reader action stay quiet

## Performance

- The drag, the wave path and the reveal run on the UI thread: one shared pager position drives every page, so a page change needs no hand-off between layers and React renders only when the settled page changes.
- Each page after the first is one SVG path (plus six faint strokes that add up to its soft shadow) and a clipped view; only the page in play re-draws, and the breathing loop touches the resting bulge alone.
- Every page stays mounted. Keep it to two to six pages and keep heavy content (video, long lists) out of them.

## Notes for AI

- Give the component a size: flex: 1 in a full-screen route, or a fixed height. It fills its box and clips to it.
- pages is [{ key, color, label, render }]. color is the page's background AND the liquid's color; do not draw your own full-size background in render unless it is the same color.
- render receives { index, active, ink }: color your text and icons with ink so they read on the page color.
- Keep page content clear of the trailing edge near bulgeAt (default 68% of the height): the bulge reaches about 60 pt in and 170 pt tall. The indicator sits 24 pt from the bottom at the start edge; add the bottom safe area inset to indicatorOffset on full-screen pages.
- Content of the incoming page is shown inside the flat part of the liquid and dissolves toward the wave; the bulge itself is plain color. That is by design: the reveal is a moving clip, so there is no mask dependency.
- For buttons outside the pages use index + onIndexChange, or the ref: next(), back(), goTo(i). pull(amount, at) and release() script the gesture for a hint.
- onIndexChange fires at release, when the flood starts, not when it ends.
- Buttons inside a page work, also in the corners next to the edge (only the box around the resting bulge is the handle); do not put horizontally scrolling content inside a page.
- Requires GestureHandlerRootView at the app root (see the foundation setup).

## Related

- [Onboarding pager](https://goodui.dev/native/components/page-dots-onboarding.md): A full-screen onboarding pager: pages follow the finger 1:1 with parallax on their content, the page dot stretches toward the next page like a worm, and the Next button grows with the swipe into a full-width Get started on the last page.
- [Carousel](https://goodui.dev/native/components/carousel.md): A snapping card carousel that follows the finger 1:1, shrinks and dims the neighbours, stretches its pagination pill with the drag, and turns that pill into a timer when it autoplays.
- [Card deck swipe](https://goodui.dev/native/components/card-deck-swipe.md): A swipe deck: the top card follows the finger and turns around the point it was grabbed at, stamps fade in with the distance, the pile underneath rises exactly as far as the card has travelled, and letting go throws it with your velocity or springs it back.
- [Stories](https://goodui.dev/native/components/stories.md): An Instagram-style story viewer that grows out of the tapped avatar: segmented bars fill at the top, tap right or left to step, hold to pause while the chrome steps aside, swipe sideways to the next person with a plain slide, and drag down to send it back into the avatar.

## Guidance for AI tools

Liquid swipe: Full-bleed pages revealed by a liquid wave: the next page waits behind a breathing bulge on the edge, the bulge follows the finger 1:1 with its centre at the finger's height, and past the threshold or on a flick the liquid floods across and the page changes. Use only the documented props. Keep accessibility, reduced motion and both color schemes intact when adapting it.

Full library index: https://goodui.dev/native/llms.txt
