Liquid swipe

ProReact Native · Expo

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.

View as Markdown

Installation

$ npx shadcn@latest add @goodui-native-pro/liquid-swipe

Then run npx expo install --fix so react-native-gesture-handler, react-native-reanimated, react-native-svg match your Expo SDK. Files land in components/goodui-native/liquid-swipe.

Pro components and screens install from the license-gated @goodui-native-pro registry. Setup: Pro access.

Usage

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 }} />;
}

When to use

Use it for
  • 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.
Reach for something else
  • 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.

Examples

Controlled, with your own Back and Next buttons

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

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

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

API reference

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

Motion and haptics

  • 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.
  • Haptic: select when the pull crosses the threshold in either direction
  • Haptic: 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
  • 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.

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.

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).