Card deck swipe

ProReact Native · Expo

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.

View as Markdown

Installation

$ npx shadcn@latest add @goodui-native-pro/card-deck-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/card-deck-swipe.

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

Usage

import { useRef } from "react";
import { Image, View } from "react-native";
import { Button } from "@/components/goodui-native/button/button";
import { CardDeckSwipe, type CardDeckSwipeHandle } from "@/components/goodui-native/card-deck-swipe/card-deck-swipe";

type Stay = { id: string; title: string; photo: string };

export function Discover({ stays, save, skip }: { stays: Stay[]; save: (s: Stay) => void; skip: (s: Stay) => void }) {
  const deck = useRef<CardDeckSwipeHandle>(null);
  return (
    <View style={{ gap: 16 }}>
      <CardDeckSwipe
        ref={deck}
        data={stays}
        keyExtractor={(s) => s.id}
        leftLabel="Skip"
        rightLabel="Save"
        undoLabel="Undo"
        accessibilityLabel="Stays for your weekend"
        getItemLabel={(s) => s.title}
        onSwipeLeft={skip}
        onSwipeRight={save}
        renderCard={({ item }) => <Image source={{ uri: item.photo }} style={{ flex: 1 }} />}
      />
      <View style={{ flexDirection: "row", gap: 12 }}>
        <Button variant="secondary" onPress={() => deck.current?.swipeLeft()}>Skip</Button>
        <Button onPress={() => deck.current?.swipeRight()}>Save</Button>
      </View>
    </View>
  );
}

When to use

Use it for
  • Deciding on one item at a time with a yes or a no: people, stays, products, job posts, adoption profiles.
  • Sorting a queue quickly: flashcards (again, got it), inbox triage (snooze, archive), photo review (keep, discard).
  • Discovery screens where the next item should already be visible under the current one.
Reach for something else
  • Browsing items side by side or going back and forth freely: use carousel.
  • Revealing actions on a row of a list: use swipe-actions.
  • A single confirmation: use swipe-to-confirm or hold-to-confirm.
  • Inside a horizontally scrolling container: the two gestures fight.

Examples

Three directions: giving upLabel turns the upward swipe on

<CardDeckSwipe data={people} leftLabel="Pass" rightLabel="Like" upLabel="Super like" accessibilityLabel="People near you" renderCard={({ item }) => <Profile person={item} />} onSwipe={(direction, person) => api.vote(person.id, direction)} />

A deck that ends, with an empty state and undo

<CardDeckSwipe ref={deck} data={words} aspectRatio={1.5} leftLabel="Again" rightLabel="Got it" undoLabel="Undo" accessibilityLabel="Flashcards" onEmpty={finish} empty={<Button onPress={restart}>Study again</Button>} renderCard={({ item }) => <Flashcard word={item} />} />

Your own stamps, and a hint that teaches the gesture on first open

<CardDeckSwipe ref={deck} data={mail} loop leftLabel="Snooze" rightLabel="Archive" accessibilityLabel="Unread mail" renderStamp={(direction) => <Pill tone={direction === "right" ? "accent" : "warning"} />} renderCard={({ item }) => <MailCard mail={item} />} />
// once, after the screen appears
useEffect(() => { const t = setTimeout(() => deck.current?.peek("right"), 600); return () => clearTimeout(t); }, []);

API reference

PropTypeDefault
data*
The cards, first on top. Append to it as the deck runs low; do not reorder what is already there.
T[]—
renderCard*
Renders the face of a card. It fills the card; keep it free of Pressables and use `onCardPress`.
(info: { item: T; index: number }) => ReactNode—
keyExtractor
Stable key per item. Defaults to the index.
(item: T, index: number) => string—
ref
Imperative handle: `ref.current?.swipeRight()`, `swipeLeft()`, `swipeUp()`, `undo()`, `peek()`.
Ref<CardDeckSwipeHandle>—
leftLabel*
What a swipe to the left means, for example "Skip". Shown on the stamp and read as the accessibility action.
string—
rightLabel*
What a swipe to the right means, for example "Like". Shown on the stamp and read as the accessibility action.
string—
upLabel
What a swipe up means, for example "Super like". Giving it turns the upward swipe on.
string—
undoLabel
Name of the undo accessibility action, for example "Undo". Without it screen readers get no undo action.
string—
onSwipeLeft
Called when a card leaves to the left.
(item: T, index: number) => void—
onSwipeRight
Called when a card leaves to the right.
(item: T, index: number) => void—
onSwipeUp
Called when a card leaves upward.
(item: T, index: number) => void—
onSwipe
Called for every swipe, with its direction.
(direction: CardDeckSwipeDirection, item: T, index: number) => void—
onUndo
Called when a card comes back, with the direction it had left in.
(item: T, index: number, direction: CardDeckSwipeDirection) => void—
onEmpty
Called when the last card has been swiped (never with `loop`).
() => void—
onCardPress
Called when the top card is tapped.
(item: T, index: number) => void—
empty
Shown in place of the deck once every card is gone, for example an empty state with a reload button.
ReactNode—
loop
Start over from the first card after the last one, forever.
booleanfalse
stamps
Show the stamps that fade in with the drag. Default `true`.
booleantrue
renderStamp
Replaces the built-in stamp (icon and label) of a direction with your own node.
(direction: CardDeckSwipeDirection) => ReactNode—
aspectRatio
Card width divided by its height. Default 0.72.
number0.72
disabled
Freezes the deck: no gestures, no imperative swipes.
booleanfalse
getItemLabel
Short description of a card for screen readers, for example a name. Read as the deck's value.
(item: T, index: number) => string—
accessibilityLabel*
Name of the deck, for example "People near you".
string—
style
Style for the outer container.
StyleProp<ViewStyle>—
testID
Identifier for end-to-end tests.
string—

Motion and haptics

  • Drag: the card tracks the finger 1:1 on both axes and turns around the grab point, so that point stays under the finger. Grabbed in the top half it leans with the drag, in the bottom half against it, up to 18 degrees at one card width.
  • Stamps fade and grow from 0.8 to 1 with the distance and are full at the commit threshold (30% of the width, 20% of the height for up); the upward stamp takes over once the drag is more up than sideways.
  • Pile: each card below is 5% smaller and peeks 10 pt out; its depth is one level per card above minus how far those cards have travelled, so it rises in step with the drag and sinks back in step with an undo.
  • Release past the threshold, or a flick faster than 800 pt/s, throws the card off screen on the smooth spring carrying the finger's velocity. Anything else springs back on snappy with the same velocity.
  • Imperative swipes play what a hand does: a pull to the threshold on the slow timing, then the throw. peek() pulls most of the way and springs back.
  • Undo flies the card back from the side it left on the smooth spring.
  • Reduced motion: the card still follows the finger but does not turn, stamps do not scale, and throws, undo and imperative swipes change the card at once; peek() does nothing.
  • Haptic: select when the drag crosses a commit threshold
  • Haptic: tap when a card leaves left or right, success when it leaves upward
  • Haptic: undo when a card comes back
  • The drag, the rotation, the stamps and the pile run on the UI thread from a fixed pool of shared values; React renders once per swipe.
  • At most eight cards are mounted: four in the pile and the four most recently swiped (so they can finish flying out or come back).
  • The UI thread advances to the next card the moment a card is thrown, so fast consecutive swipes do not wait for React.

Accessibility

  • The deck is one accessible group named by accessibilityLabel; its value is the top card (getItemLabel, or its position such as 2/6).
  • Swiping is gesture-only, so every direction is an accessibility action named by your labels (leftLabel, rightLabel, upLabel) plus undo when undoLabel is given; activate calls onCardPress.
  • After a swipe the direction label and the next card are announced; after an undo, undoLabel and the card that came back.
  • On the web the deck takes focus: Left, Right and Up arrows swipe, Backspace undoes, Enter presses the top card.
  • There are no built-in strings: every word a screen reader says comes from your props.
  • Directions are physical and do not mirror under RTL: right is the positive answer in every language, as in the apps people know.

Notes for AI

  • leftLabel, rightLabel and accessibilityLabel are required. They are the stamp text and the screen reader actions: pass short verbs (Skip, Save), not sentences.
  • The upward swipe exists only when upLabel is given; do not add a prop to enable it.
  • renderCard fills the card (use flex: 1). Card faces receive no touches: do not put Pressables inside, use onCardPress and buttons under the deck wired to the ref.
  • The handle is swipeLeft, swipeRight, swipeUp, undo and peek. Pass the ref as a prop (React 19): <CardDeckSwipe ref={deck} />.
  • index in every callback is the index in data, also with loop.
  • Load more by appending to data; never reorder or remove the cards already in it. To restart a finished deck, change its key.
  • It takes the width of its parent; height is width / aspectRatio plus 20 pt for the pile. Give it 16 pt gutters and nothing scrolling horizontally around it.
  • With upLabel the deck also claims upward drags; keep it out of the upper part of a long scrolling page.
  • Requires GestureHandlerRootView at the app root (see the foundation setup).