How to add custom swipe actions to a UICollectionViewListCell?

Published by donnywals on

This article covers beta technology and it's up to date for Xcode 12 beta 1

In iOS 14 Apple added the ability for developers to create collection views that look and feel like table views, except they are far, far more powerful. To do this, Apple introduced a new UICollectionViewCell subclass called UICollectionViewListCell. This new cell class allows us to implement several tableviewcell-like principles, including swipe actions.

You can add both leading and trailing swipe actions to a cell by assigning a UISwipeActionsConfiguration instance to the cell's leadingSwipeActionsConfiguration and trailingSwipeActionsConfiguration properties. A UISwipeActionsConfiguration is created using an array of one or more UIContextualAction instances.

You can customize the icon, title, and background color of a contextual icon as needed. Setting an image and background is optional but you are required to pass a title to the UIContextualAction initializer.

Let's look at an example of how you can add a simple trailing swipe action to a UICollectionViewListCell instance:

lazy var listItemConfig = UICollectionView.CellRegistration<UICollectionViewListCell, TodoItem> { (cell, indexPath, model) in
  var content = cell.defaultContentConfiguration()
  content.text = "\( (done: \(model.isDone))"
  cell.contentConfiguration = content

  let actionHandler: UIContextualAction.Handler = { action, view, completion in
    model.isDone = true
    self.collectionView.reloadItems(at: [indexPath])

  let action = UIContextualAction(style: .normal, title: "Done!", handler: actionHandler)
  action.image = UIImage(systemName: "checkmark")
  action.backgroundColor = .systemGreen

  cell.trailingSwipeActionsConfiguration = .init(actions: [action])

Note that this example uses the new UICollectionView.CellRegistration way of registering and dequeueing cells. Read more about iOS 14's Cell Registration here.

This is a very simple configuration that adds a single trailing action to a cell. The action is configured to have a green background and has a checkmark icon. Note that when you set an image on the action, the tite is hidden from view on iOS. It's still used for accessibillity so make sure to set a good title, even if you plan on using an image in the UI.

Note that I created a .normal contextual action. The other option here is .desctructive to indicate that an action might destruct data.

The action handler that's passed to UIContextualAction receives a reference to the action that triggered it, the view that this occured in and a completion handler that you must call.

You also receive a completion handler in the action handler. You must call this handler when you're done handling the action and pass true if you handled the action successfully. If you failed to successfully handle the action, you must pass false. This allows the system to perform any tasks (if needed) related to whether you were able to handle the action or not.

25% off Practical Combine until June 30th!

Learn everything you need to know about Combine and how you can use it in your projects with my new book Practical Combine. You'll get eleven chapters, a Playground and a handful of sample projects to help you get up and running with Combine as soon as possible.

The book is available as a digital download for just $18.74!

Get Practical Combine

Receive weekly updates about my posts