SwipeCellKit

Build Status Version Status Swift 3.0 license MIT Platform Carthage compatible Twitter

Swipeable UITableViewCell based on the stock Mail.app, implemented in Swift.

About

A swipeable UITableViewCell with support for:

  • Left and right swipe actions
  • Action buttons with: text only, text + image, image only
  • Haptic Feedback
  • Customizable transitions: Border, Drag, and Reveal
  • Customizable action button behavior during swipe
  • Animated expansion when dragging past threshold
  • Customizable expansion animations
  • Accessibility

Background

Check out my blog post on how SwipeCellKit came to be.

Demo

Transition Styles

The transition style describes how the action buttons are exposed during the swipe.

Border

Drag

Reveal

Customized

Expansion Styles

The expansion style describes the behavior when the cell is swiped past a defined threshold.

None

Selection

Destructive

Customized

Requirements

  • Swift 3.0
  • Xcode 8
  • iOS 10.0+

Installation

use_frameworks!

# Latest release in CocoaPods
pod 'SwipeCellKit'

# Get the latest on develop
pod 'SwipeCellKit', :git => 'https://github.com/jerkoch/SwipeCellKit.git', :branch => 'develop'

Carthage

github "jerkoch/SwipeCellKit"

Documentation

Read the docs. Generated with jazzy. Hosted by GitHub Pages.

Usage

Set the delegate property on SwipeTableViewCell:

override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
    let cell = tableView.dequeueReusableCell(withIdentifier: "Cell") as! SwipeTableViewCell
    cell.delegate = self
    return cell
}

Adopt the SwipeTableViewCellDelegate protocol:

func tableView(_ tableView: UITableView, editActionsForRowAt indexPath: IndexPath, for orientation: SwipeActionsOrientation) -> [SwipeAction]? {
    guard orientation == .right else { return nil }

    let deleteAction = SwipeAction(style: .destructive, title: "Delete") { action, indexPath in
        // handle action by updating model with deletion
    }

    // customize the action appearance
    deleteAction.image = UIImage(named: "delete")

    return [deleteAction]
}

Optionally, you can implement the editActionsOptionsForRowAt method to customize the behavior of the swipe actions:

func tableView(_ tableView: UITableView, editActionsOptionsForRowAt indexPath: IndexPath, for orientation: SwipeActionsOrientation) -> SwipeTableOptions {
    var options = SwipeTableOptions()
    options.expansionStyle = .destructive
    options.transitionStyle = .border
    return options
}

Transitions

Three built-in transition styles are provided by SwipeTransitionStyle:

  • .border: The visible action area is equally divide between all action buttons.
  • .drag: The visible action area is dragged, pinned to the cell, with each action button fully sized as it is exposed.
  • .reveal: The visible action area sits behind the cell, pinned to the edge of the table view, and is revealed as the cell is dragged aside.

See Customizing Transitions for more details on customizing button appearance as the swipe is performed.

Expansion

Four built-in expansion styles are provided by SwipeExpansionStyle:

  • .selection
  • .destructive (like Mail.app)
  • .destructiveAfterFill (like Mailbox/Tweetbot)
  • .fill

Much effort has gone into making SwipeExpansionStyle extremely customizable. If these built-in styles do not meet your needs, see Customizing Expansion for more details on creating custom styles.

The built-in .fill expansion style requires manual action fulfillment. This means your action handler must call SwipeAction.fulfill(style:) at some point during or after invocation to resolve the fill expansion. The supplied ExpansionFulfillmentStyle allows you to delete or reset the cell at some later point (possibly after further user interaction).

The built-in .destructive, and .destructiveAfterFill expansion styles are configured to automatically perform row deletion when the action handler is invoked (automatic fulfillment). Your deletion behavior may require coordination with other row animations (eg. inside beginUpdates and endUpdates). In this case, you can easily create a custom SwipeExpansionStyle which requires manual fulfillment to trigger deletion:

var options = SwipeTableOptions()
options.expansionStyle = .destructive(automaticallyDelete: false)

NOTE: You must call SwipeAction.fulfill(with style:) at some point while/after your action handler is invoked to trigger deletion. Do not call deleteRows directly.

let delete = SwipeAction(style: .destructive, title: nil) { action, indexPath in
    // Update model
    self.emails.remove(at: indexPath.row)

    // Coordinate table view update animations
    self.tableView.beginUpdates()
    self.tableView.insertRows(at: [IndexPath(row: 0, section: 1)], with: .automatic)
    action.fulfill(with: .delete)
    self.tableView.endUpdates()
}

Customizing Transitions

You can customize the transition behavior of individual actions by assigning a transitionDelegate to the SwipeAction type.

The provided ScaleTransition type monitors the action button’s visibility as it crosses the threshold, and animates between initialScale and identity. This provides a pop-like effect as the action buttons are exposed more than 50% of their target width.

let action = SwipeAction(style: .default, title: "More") { action, indexPath in return }
action.transitionDelegate = ScaleTransition.default

The ScaleTransition type provides a static default configuration, but it can also be initiantiated with custom parameters to suit your needs.

You can also easily provide your own completely custom transition behavior by adopting the SwipeActionTransitioning protocol. The supplied SwipeActionTransitioningContext to the delegate methods reflect the current swipe state as the gesture is performed.

Customizing Expansion

Expansion behavior is defined by four components: a target, triggers, elastic overscroll, and the completion animation.

Target

The target describes the location to which the cell will scroll when expansion is triggered. The SwipeExpansionStyle.Target enumeration defines the following options:

  1. .percentage: Percentage of superview’s width (0.0 to 1.0).
  2. .edgeInset: Inset from superview’s opposite edge (in points).

Triggers

By default, expansion will automatically trigger after the actions view is completely exposed. It may be desirable to customize this trigger point, or define addtional triggers to complement the default behavior. The SwipeExpansionStyle.Trigger enumeration defines the following options:

  1. .touchThreshold: The trigger a specified by a touch occuring past the supplied percentage in the superview (0.0 to 1.0). The action view must also be fully exposed for this trigger to activate.
  2. .overscroll: The trigger is specified by the distance past the fully exposed action view (in points).

Elastic Overscroll

When elasticOverscroll is enabled, the action buttons will only fill 25% percent of the additional space provided to the actions view.

Completion Animations

The completion animation occurs on touch up if expansion is actively triggered. The SwipeExpansionStyle.CompletionAnimation enumeration defines the following expansion animation completion style options:

  1. .fill(FillOptions): The default expansion button will completely expand to fill the previous place of the cell.
  2. .bounce: The expansion will bounce back from the trigger point and hide the action view, resetting the cell.

For fill expansions, you can use the FillOptions type to configure the behavior of the fill completion animation along with the timing of the invocation of the action handler. These options are defined by the ExpansionFulfillmentStyle and HandlerInvocationTiming.

The ExpansionFulfillmentStyle allows you to configure how to resolve the actively filled state . The built-in .destructive, and .destructiveAfterFill expansion styles configure the ExpansionFulfillmentStyle to automatically perform the .delete when the action handler is invoked. This is done by created a FillOptions instance using the static automatic(_ style:timing:) method. When you need to determine this behavior at runtime or coordinate deletion with other animations, you can create a FillOptions instance using the static manual(timing:) function and call action.fulfull(style:) asynchronously after your action handler is invoked.

You can use the HandlerInvocationTiming to configure if the action handler should be invoked .with the fill animation, or .after the fill animation completes. Using the .with option behaves like the stock Mail.app, while the .after option behaves more like the 3rd party Mailbox and Tweetbot apps.

Built-in Styles

The framework provides four built-in SwipeExpansionStyle instances which configure the above components accordingly:

  1. .selection
target: .percentage(0.5)
elasticOverscroll: true
addditionalTriggers: []
completionAnimation: .bounce
  1. .destructive
target: .edgeInset(30)
elasticOverscroll: false
addditionalTriggers: [.touchThreshold(0.8)]
completionAnimation: .fill(.automatic(.delete, timing: .with))
  1. .destructiveAfterFill
target: .edgeInset(30)
elasticOverscroll: false
addditionalTriggers: [.touchThreshold(0.8)]
completionAnimation: .fill(.automatic(.delete, timing: .after))
  1. .fill
target: .edgeInset(30)
elasticOverscroll: false
addditionalTriggers: [.overscroll(30)]
completionAnimation: .fill(.manual(timing: .after))

Button Behavior

It is also possible to customize the button expansion behavior by assigning a expansionDelegate to the SwipeTableOptions type. The delegate is invoked during the (un)expansion process and allows you to customize the display of the action being expanded, as well as the other actions in the view.

The provided ScaleAndAlphaExpansion type is useful for actions with clear backgrounds. When expansion occurs, the ScaleAndAlphaExpansion type automatically scales and fades the remaining actions in and out of the view. By default, if the expanded action has a clear background, the default ScaleAndAlphaExpansion will be automatically applied by the system.

var options = SwipeTableOptions()
options.expansionDelegate = ScaleAndAlphaExpansion.default

The ScaleAndAlphaExpansion type provides a static default configuration, but it can also be instantiated with custom parameters to suit your needs.

You can also provide your own completely custom expansion behavior by adopting the SwipeExpanding protocol. The protocol allows you to customize the animation timing parameters prior to initiating the (un)expansion animation, as well as customizing the action during (un)expansion.

Credits

Created and maintained by @jerkoch.

Showcase

We’re interested in knowing who’s using SwipeCellKit in their app. Please submit a pull request to add your app!

License

SwipeCellKit is released under an MIT License. See LICENSE for details.

Please provide attribution, it is greatly appreciated.