> For AI agents: the complete documentation index is available at https://react-native-swipe-deck.pages.dev/llms.txt, the full documentation bundle is available at https://react-native-swipe-deck.pages.dev/llms-full.txt.

# API Reference

## Main Exports

```ts
export {
  SwipeDeckActionMotion,
  SwipeDeckMotion,
  createSwipeDeck,
  SwipeDeck,
  SwipeDeckUndoMotion,
} from '@react-native-motion-kit/swipe-deck';
```

[Go to source](https://github.com/react-native-motion-kit/react-native-swipe-deck/blob/main/src/index.tsx)

## `createSwipeDeck<T>(config?)`

Creates a typed deck family.

```tsx
const ProfileDeck = createSwipeDeck<Profile>({
  motion: SwipeDeckMotion.tinder(),
});
```

The returned instance includes:

- `Root`
- `Card`
- `useDeckState`
- `useDeckActions`
- `useDeckInteraction`
- `useDeckEvent`
- `useDeckEventListener`

## `SwipeDeck.Root` Props

[Go to source](https://github.com/react-native-motion-kit/react-native-swipe-deck/blob/main/src/types.ts)

| Prop                | Type                                 | Notes                                     |
| ------------------- | ------------------------------------ | ----------------------------------------- |
| `id`                | `string`                             | Factory-scoped deck namespace.            |
| `data`              | `readonly T[]`                       | Ordered items rendered by the deck.       |
| `getKey`            | `(item: T, index: number) => string` | Required stable item key.                 |
| `initialIndex`      | `number`                             | Initial active item index.                |
| `disabled`          | `boolean`                            | Disables accepted actions and gestures.   |
| `allowedDirections` | `AllowedDirections`                  | Limits accepted dismiss directions.       |
| `swipeThreshold`    | `SwipeThreshold`                     | Root-level dismiss threshold override.    |
| `velocityThreshold` | `number`                             | Root-level flick threshold override.      |
| `motion`            | `SwipeDeckMotionPreset`              | Gesture-driven motion preset.             |
| `actionMotion`      | `SwipeDeckActionMotionRecipe`        | Programmatic swipe motion recipe.         |
| `undoMotion`        | `SwipeDeckUndoMotionRecipe`          | Programmatic undo restore motion recipe.  |
| `undoEnabled`       | `boolean`                            | Enables undo history tracking.            |
| `visibleCardCount`  | `number`                             | Maximum mounted forward card budget.      |
| `containerStyle`    | `StyleProp<ViewStyle>`               | Style applied to the deck container.      |
| `children`          | `ReactNode`                          | Must include a matching `SwipeDeck.Card`. |

```ts
type AllowedDirections = readonly ('left' | 'right' | 'up')[];
type SwipeThreshold = number | ((layout: SwipeDeckLayout) => number);
```

Static `SwipeDeck.Root` accepts the same props except `id`.

See [Multi-Instance Management](https://react-native-swipe-deck.pages.dev/guide/usage/multi-instance-management.md) for the complete id contract.

`id` is not an item key. Use a stable deck namespace such as `"nearby"`,
`"recommended"`, or a navigation route key that does not change while the screen
is mounted. Identity is stable while at least one committed Root or public hook
consumer remains mounted for that id. After the final cleanup and deferred
eviction, a later consumer receives fresh actions and interaction shared values.
Do not derive ids from item ids, timestamps, or values that change while mounted.
Two simultaneous Roots from the same factory still require distinct ids.

## `SwipeDeck.Card` Props

| Prop          | Type                                                 | Notes                                               |
| ------------- | ---------------------------------------------------- | --------------------------------------------------- |
| `interactive` | `boolean \| ((info: SwipeRenderInfo<T>) => boolean)` | Enables touchable children on the active card only. |
| `style`       | `StyleProp<ViewStyle>`                               | Style applied to the absolute card.                 |
| `children`    | `(info: SwipeRenderInfo<T>) => ReactNode`            | Renders one item in the bounded window.             |

`SwipeRenderInfo<T>` includes `item`, `index`, `offset`, `role`, and
`isActive`.

## State And Actions

```ts
type SwipeDeckState = {
  activeIndex: number;
  count: number;
  isCompleted: boolean;
  canSwipe: boolean;
  canUndo: boolean;
};

type SwipeDeckActions = {
  swipeLeft: SwipeDeckAction;
  swipeRight: SwipeDeckAction;
  swipeUp: SwipeDeckAction;
  undo: SwipeDeckUndoAction;
};
```

Programmatic actions return `boolean` to tell whether the action was accepted.

## Interaction

```ts
type SwipeDeckInteractionPhase = 'idle' | 'dragging' | 'dismissing' | 'undoing';
```

`SwipeDirection` is `'left' | 'right' | 'up'`. Omitted `allowedDirections`
allows only left and right; upward dismisses are opt-in.

`useDeckInteraction()` returns Reanimated shared values for `progress`,
`signedProgress`, `direction`, `intentDirection`, `dismissDirection`,
`translationX`, `translationY`, `isDragging`, and `phase`. `intentDirection`
is the policy-filtered live semantic source for overlays: `'left'`, `'right'`,
`'up'`, or `null`. Only centered upward gestures enter the internal up cone;
ordinary upper-left and upper-right diagonals remain horizontal. If that raw
horizontal winner is not allowed, `intentDirection`, `progress`, and
`signedProgress` stay neutral while card translation still follows the finger.
`signedProgress` and numeric `direction` remain horizontal-only and are `0` for
upward intent or dismiss. `dismissDirection` can be `'left'`, `'right'`, `'up'`,
or `null` after a dismiss is accepted.

## Events

```ts
type SwipeDeckEventMap<T> = {
  swipe: SwipeEvent<T>;
  undo: UndoEvent<T>;
  indexChange: { index: number };
  endReached: true;
};
```

Use `useDeckEvent` for latest event snapshots and `useDeckEventListener` for
imperative subscriptions.

## Motion Helpers

- `SwipeDeckMotion.tinder(options?)`
- `SwipeDeckActionMotion.direct(options?)`
- `SwipeDeckActionMotion.springboard(options?)`
- `SwipeDeckUndoMotion.spring(options?)`
- `SwipeDeckUndoMotion.timing(options?)`

For behavior details, prefer the guide pages over treating this reference as an
onboarding surface.