UICollectionView Tutorial: Getting Started

Get hands-on experience with UICollectionView by creating your own grid-based photo browsing app using the Flickr API. By Owen L Brown.

Leave a rating/review
Download materials
Save for later
Update note: Owen Brown updated this tutorial for iOS 14, Xcode 12 and Swift 5. Brandon Trebitowski wrote the original.

The iOS Photos app has a stylish way of displaying photos via a multitude of layouts. You can view your photos in a grid view:

iOS Photos App with UICollectionView

Or you can view your albums as stacks:

iOS Photos app in album view with UICollectionView

You can even transition between the two layouts with a cool pinch gesture. You’re probably thinking, “Wow, I want my app to do that!”

It can with UICollectionView. UICollectionView makes adding custom layouts and layout transitions, like those in Photos, simple to build.

You’re not limited to stacks and grids because collection views are customizable. You can use them to make circle layouts, cover-flow style layouts, Pulse news style layouts and almost anything you can dream up!

In this tutorial, you’ll get hands-on experience with UICollectionView by creating a grid-based photo browsing app. Along the way, you’ll learn how to:

  • Add custom headers to collection views.
  • Easily move cells by dragging them.
  • Implement single cell selection to bring up a detail view.
  • Implement multi-cell selection.

By the time you finish this tutorial, you’ll be ready to use this amazing technology in your apps!

Anatomy of a UICollectionView

First, look at the finished project. UICollectionView contains several key components, as you can see below:

UICollectionView Components of the finished app

Take a look at these components one-by-one:

  1. UICollectionView: The main view where the content is displayed, similar to a UITableView. Like a table view, a collection view is a UIScrollView subclass.
  2. UICollectionViewCell: This is similar to a UITableViewCell in a table view. These cells make up the view’s content and are subviews to the collection view. You can create cells programmatically or inside Interface Builder.
  3. Supplementary Views: Use supplementary views when you have extra information to display that should be in the collection view but not in the cells. Developers commonly used them for headers or footers.
Note: Collection views can also have Decoration Views. Use decoration views to add extra views that don’t contain useful data but enhance the collection view’s appearance. Background images or other visual embellishments are good examples of decoration views. You won’t use decoration views in this tutorial since they require you to write a custom layout class.

Using the UICollectionViewLayout

In addition to the visual components described above, a collection view has a layout object responsible for the content’s size, position and other attributes.

Layout objects are subclasses of UICollectionViewLayout. You can swap layouts out during runtime. The collection view can even automatically animate switching from one layout to another!

You can subclass UICollectionViewLayout to create your own custom layouts, but Apple has graciously provided a basic flow-based layout called UICollectionViewFlowLayout. Elements lay out one after another based on their size, like a grid view. You can use this layout class out of the box or subclass it to get some interesting behavior and visual effects.

You’ll learn more about these elements in-depth throughout this tutorial. Now, it’s time to get your hands into the mix with a project!

Introducing FlickrSearch

In this tutorial, you’ll create a cool photo-browsing app called FlickrSearch. It lets you search for a term on the popular photo-sharing site Flickr then download and display any matching photos in a grid view, as you saw in the screenshot above.

Download the project files by clicking the Download Materials button at the top or bottom of the tutorial. Open the FlickrSearch starter project.

Inside, you’ll find an empty Main.storyboard and some files for interfacing with Flickr. Have a look around before you go any further.

Starting Your Collection

Open Main.storyboard and drag in a Collection View Controller. Go to Editor ▸ Embed in ▸ Navigation Controller to create a navigation controller and automatically set the collection view controller as the root.

You now have a layout like this in the storyboard:

Storyboard with navigation controller and UICollectionViewController having a UICollectionView

Next, select the Navigation Controller you installed and make it the initial view controller in the Attributes inspector:

Setting UINavigationController as initial view controller

Focus on the collection view controller. First, select the UICollectionView inside. Then change the background color to White Color:

Setting UICollectionView of UICollectionViewController background to white

Note: Wondering what Scroll Direction does? This property is specific to UICollectionViewFlowLayout and defaults to Vertical.

A vertical flow layout means the layout class places items from left to right across the top of the view until it reaches the view’s right edge. At which point, it moves down to the next line. If there are too many elements to fit in the view, the user can scroll vertically to see more.

Conversely, a horizontal flow layout places items from top to bottom across the left edge of the view until it reaches the bottom edge. Users scroll horizontally to see items that don’t fit on the screen. In this tutorial, you’ll stick with the more common Vertical collection view.

Select the single cell in the collection view. Use the Attributes inspector to set the Reuse Identifier to FlickrCell.

This process might also be familiar from table views. The data source uses this identifier to dequeue or create new cells.

Set the reuse identifier string of UICollectionView cell to FlickrCell

Next, you’ll add a search box.

Adding Search

Drag a text field into the center of the navigation bar above the collection view. This is where users enter their search text. In the Attributes inspector, set the search field’s Placeholder Text to Search (with a few spaces after “Search” to help pad the field a little bit) and the Return Key to Search:

Adding a text field for searching

Now, control-drag from the text field to the collection view controller and choose delegate:

Connecting the text field delegate

Next, you’ll subclass your UICollectionViewController.

Subclassing Your UICollectionViewController

While UICollectionViewController does a lot, you generally need to make a subclass so you can add additional behavior beyond what UIKit provides for free.

Go to File ▸ New ▸ File. Choose iOS ▸ Source ▸ Cocoa Touch Class template and click Next. Name the new class FlickrPhotosViewController, making it a subclass of UICollectionViewController.

The template has a lot of code. The best way to understand what it does is to start from scratch.

Open FlickrPhotosViewController.swift and replace the code in the file with:

import UIKit

final class FlickrPhotosViewController: UICollectionViewController {
  // MARK: - Properties
  private let reuseIdentifier = "FlickrCell"

Next, add a constant for section insets, which you’ll use later, right below reuseIdentifier:

private let sectionInsets = UIEdgeInsets(
  top: 50.0,
  left: 20.0,
  bottom: 50.0,
  right: 20.0)

You’ll fill in the rest of the gaps as you progress through the tutorial.

Go back to Main.storyboard. Then, select the collection view controller. In the Identity inspector, set the Class to FlickrPhotosViewController to match your new class:

Set the UICollectionViewController subclass

Now it’s time to fetch Flickr photos to show in the collection view.