KSSwipeStack

KSSwipeStack is a lightweight card swiping library for iOS written in Swift.

KSSwipeStack handles any data model and the design/layout of the swipe cards are completely customizable.

Using the options provided you can customize the behavior and animations used in the swipe stack.

Features

Built-in support for:

Example

To run the example project, clone the repo, and run pod install from the Example directory first.

Installation

KSSwipeStack is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod "KSSwipeStack"

Getting started

Create a SwipeView

SwipeView is the container of the swipe stack.

Add a SwipeView to your Storyboard/nib and create an outlet for it.
Run setup on said SwipeView, using one of the provided setup methods.

The simplest form takes no arguments:

swipeView.setup()

You can also use the setup method which takes a SwipeOptions as argument in order to modify the behavior of the stack. See the Options section for further details on how to use SwipeOptions.

var swipeOptions = SwipeOptions()
swipeOptions.allowVerticalSwipes = true

swipeView.setup(options: swipeOptions)

Finally you can pass along a SwipeDelegate reference (if you don't want to use RxSwift), either by itself:

swipeView.setup(swipeDelegate: self)

...or together with some custom SwipeOptions:

swipeView.setup(swipeOptions: swipeOptions, swipeDelegate: self)

Create a custom class extending SwipableView

Styled to properly represent on item of your data.

class ExampleCard: SwipableView {

    override func setData(_ data: SwipableData) {
        super.setData(data)
        backgroundColor = .kicksortGray
        
        let imageView = UIImageView(frame: CGRect(x: 0, y: 0, width: frame.width - 100, height: 200))
        imageView.contentMode = .scaleAspectFit
        imageView.image = #imageLiteral(resourceName: "kicksortLogoInverted")
        imageView.center = center
        addSubview(imageView)
    }
}

Create a simple data model implementing the protocol SwipableData.

The protocol contains only one method, getView, in which you need to return a SwipableView.

func getView(with frame: CGRect) -> SwipableView {
    let view = ExampleCard(frame: frame)
    view.setData(self)
    return view
}

Add cards to the stack

You can add any number of cards of any number of different types to the same stack. You add a card by simply calling addCard with a parameter implementing SwipableData.

swipeView.addCard(ExampleData())

Handle swipes

Using RxSwift

You can observe all swipe events coming from the stack using RxSwift by simply setting up an observer.

swipeView.getSwipes().subscribe(onNext: { (swipe) in
    print("RX SWIPE EVENT")
}, onError: nil, onCompleted: nil, onDisposed: nil).addDisposableTo(disposableBag)

You can also observe if the stack needs a refill based on the refill threshold provided in SwipeOptions.

swipeView.needsRefill().subscribe(onNext: { (swipe) in
    print("RX REFILL EVENT")
}, onError: nil, onCompleted: nil, onDisposed: nil).addDisposableTo(disposableBag)

Using SwipeDelegate

When setting up the SwipeView you can provide a Class implementing SwipeDelegate to handle the swipes received from the stack.

swipeView.setup(options: SwipeOptions(), swipeDelegate: self)

extension ViewController: SwipeDelegate {
    func onNext(_ swipe: Swipe) {
        dump("DELEGATE SWIPE EVENT")
    }
}

Extras

Undo swipe

Call the undoSwipe() method in order to move the latest swiped card back to the stack. You can call the method any number of times in order to go back additional steps through the swipe history. Note that this feature can be disabled by setting allowUndo in SwipeOptions to false.

swipeView.undoSwipe()

If you want to prevent a specific card from being added to the swipe history (and therefore skipped when calling undoSwipe()), you should override isUndoable() for that SwipableView and return false.

Options

Using the SwipeOptions struct you can modify the behavior ot the swipe stack.

public struct SwipeOptions {
    public var throwingThreshold = Float(800)
    public var snapDuration = 0.1
    public var allowHorizontalSwipes = true
    public var allowVerticalSwipes = false
    public var horizontalPanThreshold = CGFloat(0.5)
    public var verticalPanThreshold = CGFloat(0.5)
    public var visibleImageOrigin = CGPoint(x: 0, y: 0)
    public var allowUndo = true
    public var maxRenderedCards = 5
    public var refillThreshold = 10
    public var dismissAnimationDuration = 0.25
    public var freezeWhenDismissing = false
    
    public init(){}
}

Specifying how 'hard' you have to throw a card for it to be dismissed.

public var throwingThreshold = Float(800)

Duration of the snap-back animation

public var snapDuration = 0.1

Make the swipe stack respond to horizontal swipes.

public var allowHorizontalSwipe = true

Make the swipe stack respond to vertical swipes.

public var allowVerticalSwipe = false

X-axis threshold for if a card is dismissed upon release.

public var horizontalPanThreshold = CGFloat(0.5)

Origin of a card in the 'original' state.

public var visibleImageOrigin = CGPoint(x: 0, y: 0)

Allow undoing of swipes.

public var allowUndo = true

How many cards should be rendered in the SwipeView at the same time.

public var maxRenderedCards = 5

Threshold of when a refill event is sent to refill subscribers.

public var refillThreshold = 10

Duration of the dismiss animation.

public var dismissAnimationDuration = 0.25

You can optionally choose to freeze the stack as a card is being dismissed to prevent the user from swiping

public var freezeWhenDismissing = false

Authors

arneson, Simon Arneson, arneson@kicksort.se

Sundin, Gustav Sundin, gustav@kicksort.se

License

KSSwipeStack is available under the MIT license. See the LICENSE file for more info.

manucheri/KSSwipeStack