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

# Basic Usage

## Factory API

The factory API is the primary API. Use it when a deck needs hooks, actions,
events, interaction shared values, or multiple named instances.

```tsx
import { createSwipeDeck } from '@react-native-motion-kit/swipe-deck';

const ProfileDeck = createSwipeDeck<Profile>();

function Screen() {
  return (
    <ProfileDeck.Root data={profiles} getKey={(item) => item.id}>
      <ProfileDeck.Card>{({ item }) => <ProfileCard profile={item} />}</ProfileDeck.Card>
    </ProfileDeck.Root>
  );
}
```

The factory keeps `Root`, `Card`, and hooks on the same item type without
repeating generics in JSX.

## Card Render Info

`Card` receives render info for each mounted item.

| Field      | Meaning                                                 |
| ---------- | ------------------------------------------------------- |
| `item`     | The item from your `data` array.                        |
| `index`    | The item index in `data`.                               |
| `offset`   | The card offset from the active item.                   |
| `role`     | `'current'` for the active card, `'next'` for buffered. |
| `isActive` | `true` only for the active card.                        |

```tsx
<ProfileDeck.Card>
  {({ item, role, isActive }) => <ProfileCard profile={item} role={role} active={isActive} />}
</ProfileDeck.Card>
```

## Interactive Card Content

Cards are non-interactive by default so the deck can own swipe gestures safely.
Use `interactive` when the active card contains touchable children such as CTA buttons or links.

```tsx
<ProfileDeck.Card interactive>
  {({ item }) => <AdCard ad={item} onPressCta={() => openAd(item)} />}
</ProfileDeck.Card>
```

Use the predicate form when only some items should expose touchable children.

```tsx
<ProfileDeck.Card interactive={({ item }) => item.type === 'ad'}>
  {({ item }) => <SwipeVoteCard item={item} />}
</ProfileDeck.Card>
```

`interactive` only affects the active card. Background cards remain non-interactive.
For deeper nested gestures such as card-local carousels or scroll views, prefer a dedicated
future gesture-coordination API instead of exposing raw `pointerEvents`.

## Allowed Directions

`allowedDirections` limits which directions can be accepted as a dismiss.

```tsx
<ProfileDeck.Root
  data={profiles}
  getKey={(item) => item.id}
  allowedDirections={['left', 'right', 'up']}
>
  <ProfileDeck.Card>{({ item }) => <ProfileCard profile={item} />}</ProfileDeck.Card>
</ProfileDeck.Root>
```

- Omit `allowedDirections` to allow left and right.
- Include `'up'` explicitly to allow upward dismisses.
- Gesture up requires `SwipeDeckMotion.tinder({ drag: { mode: 'free' } })`, the default.
- `drag.mode: 'horizontal'` rejects gesture up but does not block `actions.swipeUp()`.
- Pass `[]` to allow dragging but reject every dismiss release and
  programmatic swipe action.

## Static API

Use the static API only when you need inline card rendering and do not need
factory hooks.

```tsx
import { SwipeDeck } from '@react-native-motion-kit/swipe-deck';

function InlineDeck() {
  return (
    <SwipeDeck.Root data={profiles} getKey={(item) => item.id}>
      <SwipeDeck.Card<Profile>>{({ item }) => <ProfileCard profile={item} />}</SwipeDeck.Card>
    </SwipeDeck.Root>
  );
}
```

Static `Root` does not accept `id`, and static `Root` / `Card` do not share a
factory type. Pass the item type to `Card` when you want typed render props.