Koloda

by Yalantis

Yalantis / Koloda

KolodaView is a class designed to simplify the implementation of Tinder like cards on iOS.

4.8K Stars 745 Forks Last release: about 3 years ago (4.3.1) MIT License 434 Commits 35 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

KolodaView cocoapodsCarthage compatible Swift 5.0

Yalantis

Check this article on our blog. And another one article on our blog

Preview Preview

Purpose

KolodaView is a class designed to simplify the implementation of Tinder like cards on iOS. It adds convenient functionality such as a UITableView-style dataSource/delegate interface for loading views dynamically, and efficient view loading, unloading .

Supported OS & SDK Versions

  • Supported build target - iOS 11.0 (Xcode 9)

ARC Compatibility

KolodaView requires ARC.

Thread Safety

KolodaView is subclassed from UIView and - as with all UIKit components - it should only be accessed from the main thread. You may wish to use threads for loading or updating KolodaView contents or items, but always ensure that once your content has loaded, you switch back to the main thread before updating the KolodaView.

Installation

To install via CocoaPods add this lines to your Podfile. You need CocoaPods v. 1.1 or higher

ruby
use_frameworks!
pod "Koloda"

To install via Carthage add this lines to your Cartfile

ruby
github "Yalantis/Koloda"

To install manually the KolodaView class in an app, just drag the KolodaView, DraggableCardView, OverlayView class files (demo files and assets are not needed) into your project. Also you need to install facebook-pop. Or add bridging header if you are using CocoaPods.

Usage

  1. Import

    Koloda
    module to your
    MyKolodaViewController
    class
    import Koloda
    
  2. Add

    KolodaView
    to
    MyKolodaViewController
    , then set dataSource and delegate for it ```swift class MyKolodaViewController: UIViewController { @IBOutlet weak var kolodaView: KolodaView!
    override func viewDidLoad() {
        super.viewDidLoad()
    
    
    kolodaView.dataSource = self
    kolodaView.delegate = self

    }

    } ```

  3. Conform your

    MyKolodaViewController
    to
    KolodaViewDelegate
    protocol and override some methods if you need, e.g. ```swift extension MyKolodaViewController: KolodaViewDelegate { func kolodaDidRunOutOfCards(_ koloda: KolodaView) { koloda.reloadData() }
    func koloda(_ koloda: KolodaView, didSelectCardAt index: Int) {
        UIApplication.shared.openURL(URL(string: "https://yalantis.com/")!)
    }
    

    } ```

  4. Conform

    MyKolodaViewController
    to
    KolodaViewDataSource
    protocol and implement all the methods , e.g. ```swift extension MyKolodaViewController: KolodaViewDataSource {
    func kolodaNumberOfCards(_ koloda:KolodaView) -> Int {
        return images.count
    }
    
    

    func kolodaSpeedThatCardShouldDrag(_ koloda: KolodaView) -> DragSpeed { return .fast }

    func koloda(_ koloda: KolodaView, viewForCardAt index: Int) -> UIView { return UIImageView(image: images[index]) }

    func koloda(_ koloda: KolodaView, viewForCardOverlayAt index: Int) -> OverlayView? { return Bundle.main.loadNibNamed("OverlayView", owner: self, options: nil)[0] as? OverlayView }

    } ```

  5. KolodaView
    works with default implementation. Override it to customize its behavior

Also check out an example project with carthage.

Properties

The KolodaView has the following properties:

swift
weak var dataSource: KolodaViewDataSource?
An object that supports the KolodaViewDataSource protocol and can provide views to populate the KolodaView.
swift
weak var delegate: KolodaViewDelegate?
An object that supports the KolodaViewDelegate protocol and can respond to KolodaView events.
swift
private(set) public var currentCardIndex
The index of front card in the KolodaView (read only).
swift
private(set) public var countOfCards
The count of cards in the KolodaView (read only). To set this, implement the
kolodaNumberOfCards:
dataSource method.
swift
public var countOfVisibleCards
The count of displayed cards in the KolodaView.

Methods

The KolodaView class has the following methods:

swift
public func reloadData()
This method reloads all KolodaView item views from the dataSource and refreshes the display.
swift
public func resetCurrentCardIndex()
This method resets currentCardIndex and calls reloadData, so KolodaView loads from the beginning.
swift
public func revertAction()
Applies undo animation and decrement currentCardIndex.
swift
public func applyAppearAnimationIfNeeded()
Applies appear animation if needed.
swift
public func swipe(_ direction: SwipeResultDirection, force: Bool = false)
Applies swipe animation and action, increment currentCardIndex.
open func frameForCard(at index: Int) -> CGRect

Calculates frames for cards. Useful for overriding. See example to learn more about it.

Protocols

The KolodaView follows the Apple convention for data-driven views by providing two protocol interfaces, KolodaViewDataSource and KolodaViewDelegate.

The KolodaViewDataSource protocol has the following methods:

func koloda(_ kolodaNumberOfCards koloda: KolodaView) -> Int

Return the number of items (views) in the KolodaView.

swift
func koloda(_ koloda: KolodaView, viewForCardAt index: Int) -> UIView
Return a view to be displayed at the specified index in the KolodaView.
swift
func koloda(_ koloda: KolodaView, viewForCardOverlayAt index: Int) -> OverlayView?
Return a view for card overlay at the specified index. For setting custom overlay action on swiping(left/right), you should override didSet of overlayState property in OverlayView. (See Example)
swift
func kolodaSpeedThatCardShouldDrag(_ koloda: KolodaView) -> DragSpeed
Allow management of the swipe animation duration

The KolodaViewDelegate protocol has the following methods:

func koloda(_ koloda: KolodaView, allowedDirectionsForIndex index: Int) -> [SwipeResultDirection]

Return the allowed directions for a given card, defaults to

[.left, .right]
swift
func koloda(_ koloda: KolodaView, shouldSwipeCardAt index: Int, in direction: SwipeResultDirection) -> Bool
This method is called before the KolodaView swipes card. Return
true
or
false
to allow or deny the swipe.
swift
func koloda(_ koloda: KolodaView, didSwipeCardAt index: Int, in direction: SwipeResultDirection)
This method is called whenever the KolodaView swipes card. It is called regardless of whether the card was swiped programatically or through user interaction.
swift
func kolodaDidRunOutOfCards(_ koloda: KolodaView)
This method is called when the KolodaView has no cards to display.
swift
func koloda(_ koloda: KolodaView, didSelectCardAt index: Int)
This method is called when one of cards is tapped.
swift
func kolodaShouldApplyAppearAnimation(_ koloda: KolodaView) -> Bool
This method is fired on reload, when any cards are displayed. If you return YES from the method or don't implement it, the koloda will apply appear animation.
swift
func kolodaShouldMoveBackgroundCard(_ koloda: KolodaView) -> Bool
This method is fired on start of front card swipping. If you return YES from the method or don't implement it, the koloda will move background card with dragging of front card.
swift
func kolodaShouldTransparentizeNextCard(_ koloda: KolodaView) -> Bool
This method is fired on koloda's layout and after swiping. If you return YES from the method or don't implement it, the koloda will transparentize next card below front card.
swift
func koloda(_ koloda: KolodaView, draggedCardWithPercentage finishPercentage: CGFloat, in direction: SwipeResultDirection)
This method is called whenever the KolodaView recognizes card dragging event.
swift
func kolodaSwipeThresholdRatioMargin(_ koloda: KolodaView) -> CGFloat?
Return the percentage of the distance between the center of the card and the edge at the drag direction that needs to be dragged in order to trigger a swipe. The default behavior (or returning NIL) will set this threshold to half of the distance
swift
func kolodaDidResetCard(_ koloda: KolodaView)
This method is fired after resetting the card.
swift
func koloda(_ koloda: KolodaView, didShowCardAt index: Int)
This method is called after a card has been shown, after animation is complete
swift
func koloda(_ koloda: KolodaView, didRewindTo index: Int)
This method is called after a card was rewound, after animation is complete
func koloda(_ koloda: KolodaView, shouldDragCardAt index: Int) -> Bool

This method is called when the card is beginning to be dragged. If you return YES from the method or don't implement it, the card will move in the direction of the drag. If you return NO the card will not move.

Release Notes

Version 5.0.1 - added posibility to determine index of rewound card - fixed crash after drugging card

Version 5.0 - Swift 5.0 via @maxxfrazer

Version 4.7 - fixed a bug with card responding during swiping via @lixiang1994 - fixed a bug with inappropriate layouting via @soundsmitten

Version 4.6 - update some properties to be publicitly settable via @sroik and @leonardoherbert - Xcode 9 back compatibility via @seriyvolk83 - added posibility to have the card stack at the top or bottom via @lorenzOliveto

Version 4.5 - Swift 4.2 via @evilmint

Version 4.4 - Swift 4.1 via @irace - Added

isLoop
property via @brownsoo - Take into account card's alpha channel via @bwhtmn

Version 4.3 - Swift 4 support - iOS 11 frame bugfix

Version 4.0 - Swift 3 support - Get rid of UInt - Common bugfix

Version 3.1

  • Multiple Direction Support
  • Delegate methods for swipe disabling

Version 3.0

  • Ability to dynamically insert/delete/reload specific cards
  • External animator
  • Major refactoring. More information
  • Swift 2.2 support

Version 2.0

  • Swift 2.0 support

Version 1.1

  • New delegate methods
  • Fixed minor issues

Version 1.0

  • Release version.

Apps using KolodaView

Preview - Storage Space Plus. - Color Dating. - Ao Dispor

Let us know!

We’d be really happy if you sent us links to your projects where you use our component. Just send an email to [email protected] And do let us know if you have any questions or suggestion regarding the animation.

P.S. We’re going to publish more awesomeness wrapped in code and a tutorial on how to make UI for iOS (Android) better than better. Stay tuned!

License

The MIT License (MIT)

Copyright © 2019 Yalantis

Permission is hereby granted free of charge to any person obtaining a copy of this software and associated documentation files (the "Software") to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.