# Card deck swipe

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

- Type: Component (data)
- Access: Pro
- Page: https://goodui.dev/native/components/card-deck-swipe
- Markdown: https://goodui.dev/native/components/card-deck-swipe.md
- Registry item: https://goodui.dev/native/r/card-deck-swipe.json
- Dependencies: react-native-gesture-handler, react-native-reanimated, react-native-svg
- Keywords: react native tinder cards, swipe deck, swipe cards expo, card stack swipe, like skip cards, flashcards swipe, swipeable card stack reanimated

## When to use

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

## When not to use

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

## 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/card-deck-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/card-deck-swipe/` and imports the foundation from `components/goodui-native/foundation/` with relative paths.

## Usage

```tsx
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>
  );
}
```

## Examples

### Three directions: giving upLabel turns the upward swipe on

```tsx
<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

```tsx
<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

```tsx
<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

### CardDeckSwipe

`import { CardDeckSwipe } from "@/components/goodui-native/card-deck-swipe/card-deck-swipe";`

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

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

## Motion

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

## Haptics

- select when the drag crosses a commit threshold
- tap when a card leaves left or right, success when it leaves upward
- undo when a card comes back

## Performance

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

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

## Related

- [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.
- [Swipe actions](https://goodui.dev/native/components/swipe-actions.md): Row actions that unfold with the finger; a long swipe lets the edge action take over and run, and destructive actions collapse the row before it leaves.
- [Swipe to confirm](https://goodui.dev/native/components/swipe-to-confirm.md): Slide to confirm: the thumb follows the finger 1:1, the track fills behind it and the label fades, a tick marks the point of no return, and at the end the track gathers into a spinner and opens into the result.
- [Like button](https://goodui.dev/native/components/like-button.md): A like toggle with one moment of delight: the heart squashes and springs back filled, a ring expands and particles burst while the count rolls; it updates optimistically and rolls back if the request fails.
- [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

Card deck swipe: 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. 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
