flutter_card_swiper

To implement a card swiper, use the CardSwiper widget. You must provide the total number of cards via cardsCount and a cardBuilder function that returns the widget for a specific index. The cardBuilder provides the current context, the card index, and threshold percentages for X and Y axes.

import 'package:flutter_card_swiper/flutter_card_swiper.dart';
import 'package:flutter/material.dart';

class Example extends StatelessWidget {
  List<Container> cards = [
    Container(
      alignment: Alignment.center,
      child: const Text('1'),
      color: Colors.blue,
    ),
    Container(
      alignment: Alignment.center,
      child: const Text('2'),
      color: Colors.red,
    ),
    Container(
      alignment: Alignment.center,
      child: const Text('3'),
      color: Colors.purple,
    )
  ];

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Flexible(
        child: CardSwiper(
          cardsCount: cards.length,
          cardBuilder: (context, index, percentThresholdX, percentThresholdY) => cards[index],
        ),
      ),
    );
  }
}

The CardSwiper widget is configured using several parameters to control the behavior, appearance, and interaction of the card stack.

Required Parameters:

• cardBuilder: A function that returns the widget to be rendered as a card.
• cardsCount: The total number of cards in the stack.

Key Configuration Options:

• controller: An instance of CardSwiperController to trigger actions programmatically.
• isLoop: If true, the stack loops back to the beginning after the last card is swiped.
• allowedSwipeDirection: Controls which directions are valid for swiping (e.g., AllowedSwipeDirection.all, AllowedSwipeDirection.left, etc.).
• numberOfCardsDisplayed: Determines how many cards are visible in the stack at once.
• onSwipe: A callback triggered when a user swipes. Returning false cancels the swipe.
• onUndo: A callback triggered when an undo action is requested. Returning false cancels the undo.
• showBackCardOnUndo: When true, swiping triggers an undo action and shows the previous card in the background.

CardSwiper(
  cardBuilder: (index, indexFromEnd) => MyCardWidget(index),
  cardsCount: 10,
  isLoop: true,
  allowedSwipeDirection: AllowedSwipeDirection.all,
  onSwipe: (direction) {
    // Return true to allow swipe, false to cancel
    return true;
  },
)

The following parameters are available for the CardSwiper constructor:

| Parameter | Default | Description |
|-------------------------|:--------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `cardBuilder` | - | Widget builder for rendering cards |
| `cardsCount` | - | Number of cards |
| `controller` | - | Controller to trigger swipe actions |
| `duration` | 200 milliseconds | The duration that every animation should last |
| `initialIndex` | 0 | Index of the first card when the swiper is initialized |
| `isDisabled` | false | Set to `true` if swiping should be disabled, has no impact when triggered from the outside |
| `isLoop` | true | Set to `true` if the stack should loop |
| `maxAngle` | 30 | Maximum angle that the card can reach during swiping |
| `allowedSwipeDirection` | AllowedSwipeDirection.all | Sets the direction in which the card can be swiped. It can be set to any combination of left, right up or down. |
| `numberOfCardsDisplayed` | 2 | Number of cards displayed at the same time |
| `onEnd` | - | Callback when there are no more cards left to swipe |
| `onSwipe` | - | Callback when the user swipes a card. If the function returns `false`, the swipe action is canceled. If it returns `true`, the swipe action is performed as expected |
| `onTapDisabled` | - | Callback when a card is tapped and `isDisabled` is `true` |
| `onUndo` | - | Callback when the controller calls undo. If the function returns `false`, the undo action is canceled. If it returns `true`, the undo action is performed as expected |
| `padding` | EdgeInsets.symmetric(horizontal: 20, vertical: 25) | The padding around the swiper |
| `scale` | 0.9 | Scale of the card that is behind the front card |
| `threshold` | 50 | Threshold from which the card is swiped away |
| `onSwipeDirectionChange` | - | A callback containing the horizontal and vertical swipe direction |
| `showBackCardOnUndo` | - | If true, the previous card will be shown in the background when swiping, and the swipe action will trigger an undo |
| `undoSwipeThreshold` | 50 | The horizontal swipe distance threshold, in pixels, after which the back card switches to the previous card. Only active when showBackCardOnUndo is true |
| `undoDirection` | UndoDirection.left | The direction of the swipe to trigger an undo |

The CardSwiper widget is the primary component for creating a card stack UI that users can swipe. It requires a cardBuilder to define the appearance of each card and a cardsCount to define the total number of cards in the stack.

Key Configuration Options

• cardBuilder: A function that returns a widget for a given index. It provides the index, build context, and drag ratios (vertical and horizontal) relative to the threshold.
• cardsCount: The total number of cards (must be > 0).
• initialIndex: The starting card index (defaults to 0).
• controller: An optional CardSwiperController for programmatic control.
• isLoop: If true, swiping the last card returns the user to the first card (defaults to true).
• numberOfCardsDisplayed: How many cards are visible in the stack (defaults to 2).
• threshold: The percentage of card width (1-100) required to trigger a swipe (defaults to 50).
• scale: The scale of the card behind the front card (defaults to 0.9).
• backCardOffset: The position offset of the back card (defaults to Offset(0, 40)).

Callbacks

• onSwipe: Triggered when a swipe is performed. Returning false cancels the swipe.
• onEnd: Triggered when no more cards are left to swipe.
• onUndo: Triggered when an undo action is performed. Returning false cancels the undo.
• onSwipeDirectionChange: Triggered when the detected swipe direction changes.

CardSwiper(
  cardsCount: 10,
  cardBuilder: (index, context, verticalDragRatio, horizontalDragRatio) {
    return MyCardWidget(index);
  },
  onSwipe: (oldIndex, currentIndex, direction) {
    // Handle swipe
    return true;
  },
)

The CardSwiperDirection class represents the direction of a card swipe using an angle in degrees. The angle follows a clockwise rotation:

• 0°: Top
• 90°: Right
• 180°: Bottom
• 270°: Left

Standard Directions

You can use the following static constants for cardinal directions:

• CardSwiperDirection.top (0°)
• CardSwiperDirection.right (90°)
• CardSwiperDirection.bottom (180°)
• CardSwiperDirection.left (270°)
• CardSwiperDirection.none (Infinity)

Custom Directions

You can create custom directions (e.g., diagonal swipes) using CardSwiperDirection.custom(angle, {String? name}). Angles are automatically normalized to the [0, 360) range.

Direction Comparison and Properties

• isCloseTo(other, {double tolerance = 5}): Checks if a direction is approximately equal to another within a specified degree tolerance.
• isHorizontal: Returns true if the direction is approximately left or right.
• isVertical: Returns true if the direction is approximately top or bottom.

// Using standard directions
final direction = CardSwiperDirection.right;

// Creating a custom diagonal direction
final diagonal = CardSwiperDirection.custom(45); // top-right

// Checking properties
if (direction.isHorizontal) {
  print('Swiped horizontally');
}

// Comparing directions with tolerance
if (diagonal.isCloseTo(CardSwiperDirection.custom(40), tolerance: 10)) {
  print('Close enough!');
}