Swipe Deck React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Swipe Deck is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import SwipeDeck from @/components/ui/swipe-deck.

import { useState } from "react"
import { SwipeDeck, type SwipeDeckDirection } from "@/components/ui/swipe-deck"

type Receipt = { id: string; vendor: string; amount: string; category: string }

const receipts: Receipt[] = [
  { id: "exp-2041", vendor: "Whole Foods Market", amount: "$214.50", category: "Hospitality" },
  { id: "exp-2042", vendor: "FedEx", amount: "$86.00", category: "Shipping" },
  { id: "exp-2044", vendor: "Hilton Boston", amount: "$412.00", category: "Lodging" },
]

export function ApproveExpenses({ save }: { save: (id: string, approved: boolean) => Promise<void> }) {
  const [approved, setApproved] = useState(0)
  return (
    <SwipeDeck
      items={receipts}
      getItemLabel={(r) => `${r.vendor}, ${r.amount}`}
      renderCard={(r) => (
        <div className="flex h-full flex-col gap-2 p-5">
          <span className="text-[15px] font-semibold">{r.vendor}</span>
          <span className="text-4xl font-bold tabular-nums">{r.amount}</span>
          <span className="text-sm text-muted-foreground">{r.category}</span>
        </div>
      )}
      onSwipe={(r, direction: SwipeDeckDirection) => {
        if (direction === "right") setApproved((n) => n + 1)
        return save(r.id, direction === "right")
      }}
      labels={{ left: "Reject", right: "Approve", undo: "Undo", empty: `Done: ${approved} approved` }}
    />
  )
}

Props

• items*
  T[]

  The cards, each with a stable id. Appending while in use fills the stack; removing clamps the index.

• renderCard*
  (item: T, state: { index: number; isTop: boolean }) => ReactNode

  The card's content. The deck draws the card surface (radius, shadow, overflow) around it.

• getItemLabeldefault "item.id"
  (item: T) => string

  The card's accessible name and the text announced after a decision.

• directionsdefault "left, right"
  ("left" | "right" | "up")[]

  The allowed directions. Adding "up" gives a third choice (Later), a stamp at the bottom of the card and a smaller middle button; without "right" its button is hidden.

• visibleCardsdefault 3
  number

  Cards drawn in the stack, 1 to 4. The rest mount when they reach it; fewer items draw fewer cards.

• stackdefault "stack"
  "stack" | "fan" | "none"

  stack: the cards behind peek out below, scaled to 0.95 / 0.9. fan: they lean ±3° alternately. none: only the top card shows; the next fades in as it leaves.

• rotationdefault 12
  number

  Degrees of tilt at a full-width drag, around the bottom of the card. 0 keeps it upright.

• leftTonedefault "danger"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The reject stamp and button. Stamps always carry text and an icon, so color is never the only cue.

• rightTonedefault "success"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The accept stamp and button. Brand orange suits a like on a marketplace.

• upTonedefault "info"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The later stamp and button, when "up" is allowed.

• radiusdefault "lg"
  "md" | "lg"

  Card radius: md 16px (rounded-2xl), lg 24px (rounded-3xl).

• showActionsdefault true
  boolean

  The round 56px buttons under the deck: the mouse, keyboard and screen reader path to every decision.

• showUndodefault true
  boolean

  The undo button next to them. Off also turns off Backspace and Cmd/Ctrl+Z.

• stampsdefault true
  boolean

  The labels that fade in on the card while it is dragged and lock in when a direction is armed.

• hapticsdefault true
  boolean

  A medium tick when a drag arms a direction, light on commit, selection on undo, error when onSwipe rejects. Through lib/haptics, silent on desktops.

• disableddefault false
  boolean

  Dims the deck and blocks drags, keys and buttons.

• index
  number

  How many cards are decided, to control the deck from outside (set 0 to start over).

• defaultIndexdefault 0
  number

  The starting index while uncontrolled: how many cards count as decided on mount. At the item count the deck opens on its empty state.

• onIndexChange
  (index: number) => void

  Fires after every decision, undo and failed save.

• onSwipe
  (item: T, direction: SwipeDeckDirection) => (void | Promise<unknown>)

  Runs once the card has left. Return a promise to save: the deck waits for it before the next decision, and a rejection brings the card back with labels.error.

• onUndo
  (item: T, direction: SwipeDeckDirection) => void

  Runs when a card comes back through the undo button or a key.

• onEmpty
  () => void

  Runs after the last card is decided (after its save resolves, when onSwipe returns a promise).

• emptyState
  ReactNode

  Shown in the deck's place after the last card. Defaults to <EmptyState size="sm" title={labels.empty} /> with a check; its first button gets focus.

• icons
  Partial<Record<"left" | "right" | "up", ReactNode>>

  Icons for the stamps and buttons per direction. Defaults: X, Check, Clock.

• setApi
  (api: SwipeDeckApi) => void

  Hands out { swipe(direction), undo(), index } to drive the deck from your own controls. swipe animates like a button press.

• labels
  Partial<SwipeDeckLabels>

  Every string: left "Reject", right "Accept", up "Later", undo "Undo", empty "All done", region "Cards", instructions (read with the top card; the English default names Up when it is allowed and drops Backspace without undo), decided(label, direction, remaining) for the announcement, error "Couldn't save. Try again.". English defaults in DEFAULT_SWIPE_DECK_LABELS.

• classNames
  Partial<Record<"stack" | "card" | "stamp" | "actions" | "action" | "undo" | "empty" | "error", string>>

  Extra classes for the inner parts. The stack is aspect-[3/4]; override it here, e.g. { stack: "aspect-[4/5]" }.

• className
  string

  Extra classes for the root, merged last. The deck is capped at max-w-sm and centered. A thrown card flies past the deck's edges, so give a page that can scroll sideways an overflow-x-clip wrapper.

Parts

FAQ

More React mobile components