QuickLook Previews for iOS: Getting Started [FREE]

QuickLook is an iOS, macOS and iPadOS framework for presenting documents without the hassle of handling files. It lets users preview commonly used file types, like PDFs, TXTs and more.

QuickLook has been around since iOS 4. Many of Apple’s first-party apps, like Mail, Notes, Files and Message, already use QuickLook. It’s a fast and easy way to show a preview of a file and provide users with basic interactions.

In this tutorial, you’ll learn how to:

• Show a preview of files using QLPreviewController .
• Conform your data model class to QLPreviewItem to make it available for previewing.
• Generate file thumbnails using the QuickLookThumbnailing framework.
• Present QuickLook previews with a smooth zoom transition animation.

Additionally, you’ll learn how to let users make simple edits on PDFs, images and videos. Are you ready to learn how magical QuickLook is?

Getting Started

Download the project materials using the Download Materials button at the top or bottom of this tutorial. Open the project SpellLook.xcodeproj inside the starter folder.

The app, suitably named SpellLook , is all about learning spells. It has a collection of spells every sorcerer should learn and even some dark spells, too. Take a look at the project’s files in the Project navigator.

The project consist of the following key files and folders:

• Resources : A folder containing many spell files, each written in different types, like PDF, DOCX, HTML, TXT and ZIP.
• File.swift : A class representation of a spell file used by the app.
• ViewController.swift : The main view of the app which displays a collection of spell tutorials with a UICollectionView .
• FileCell.swift : A UICollectionViewCell that displays a file on the collection view.
• Main.storyboard : The app’s main storyboard.

Build and run your project in Xcode. You’ll see a collection of spell tutorials, one for each file in the resources folder.

Right now, nothing happens when you tap any of the spells. Hence, you can’t preview anything.

However, soon you’ll use QuickLook to start previewing the magic. Before you go spell-wild, take a quick look at what the QuickLook framework has to offer.

Understanding the QuickLook Framework

QuickLook is a framework that helps solve a common challenge many developers face: showing files to the user.

When it comes to previewing files, QuickLook is a great first choice. It comes with several common features every user expects, like pinch-to-zoom, audio playback and PDF pages. You can even let users add markups on images and PDFs, as well as simple video edits.

Here are some of the supported file types:

• Images
• Audio and video files
• PDFs
• HTML documents
• iWork and Microsoft Office documents
• ZIP files
• Augmented reality objects that use the USDZ file format, iOS and iPadOS only

That’s quite a few supported types. Even better, QuickLook also lets you provide custom previews for your own custom type. How cool is that?

Working with QuickLook Scenarios

Use QuickLook when you need to quickly show previews of files. The framework removes the hassle of handling files and implementing features and views for each type. It lets you focus on what’s important in your app while providing great flexibility and functionality.

QuickLook gives users an experience they know from other first-party iOS apps, with many of the features they already expect. For example, when previewing a collection of images, users can swipe left and right to flick through them.

QuickLook comes with built-in gestures like pinch-to-zoom, swipe to dismiss and scroll through PDF pages. You get these simple interactions for free!

The framework shows previews and provides simple editing support of commonly used files. However, it doesn’t support more advanced features and complex view hierarchies. In those cases, you may want to explore other approaches, like building your own views.

Since the goal of SpellLook is to let users learn spells written in many different file types, QuickLook is a perfect fit.

Previewing Files With QLPreviewController

To preview files, you’ll use a specialized view controller type called QLPreviewController . In ViewController.swift , import QuickLook by adding the following line at the top of the file:

import QuickLook

Then, add the following code at the end of collectionView(_:didSelectItemAt:) :

// 1
let quickLookViewController = QLPreviewController()
// 2
quickLookViewController.dataSource = self
// 3
quickLookViewController.currentPreviewItemIndex = indexPath.row
// 4
present(quickLookViewController, animated: true)

The code above:

1. Instantiates an instance of QLPreviewController , which can display previews for common file types.
2. Sets the data source property to self. QLPreviewController uses the classic data source pattern you already know from UIKit to provide items to the controller. The data source works a lot like UITableViewDatasource and UICollectionViewDataSource .
3. Sets the current preview index to the selected index path’s row. When previewing more than one file, you need set the index of the current previewing file on the controller.
4. Presents the QLPreviewController instance like any other alert or view controller.

Xcode recognizes ViewController doesn’t implement a data source for QLPreviewController and therefore can’t set it to self . To fix the issue, add the following extension to the bottom of ViewController :

// MARK: - QLPreviewControllerDataSource
extension ViewController: QLPreviewControllerDataSource {
  func numberOfPreviewItems(in controller: QLPreviewController) -> Int {
    files.count
  }

  func previewController(
    _ controller: QLPreviewController,
    previewItemAt index: Int
  ) -> QLPreviewItem {
    files[index].url as NSURL
  }
}

QLPreviewControllerDataSource requires you to implement two methods, numberOfPreviewItems(in:) and previewController(_:previewItemAt:) . These protocols provide the controller with items to preview and how many items it needs to include in the previewing list.

The files these protocols pull from are loaded by the default FileManager . You’ll find that code in File.swift .

Build and run. Select Light Charm and QuickLook will open a view previewing that file.

Note : You may see a number of Auto Layout messages in the debug console. These are all coming from Apple’s code and can be safely ignored.

When previewing many files, QLPreviewController adds a list button icon at the bottom-right of the preview to open a navigation list. There, you’ll see a list of items the controller is currently previewing. You can even swipe left and right to flick through the files.

QuickLook also provides a button for opening the default share sheet. You can save the file in the Files app or even share it with a friend. Also, you can pinch-to-zoom and scroll a PDF page if it doesn’t fit the screen.

You can use QuickLook to preview files inside a ZIP file, too, even if they’re password protected. With this small amount of code, you can preview a variety of files.

Isn’t QuickLook magical ? PS: The password is a secret . Be careful not to go to the dark side.

Conforming to QLPreviewItem

You may have noticed previewController(_:previewItemAt:) requires you to return a QLPreviewItem . QLPreviewController uses this protocol as an abstraction of your files. Conforming your data models to it enables QLPreviewController to preview them.

The protocol defines two required properties: previewItemURL and previewItemTitle . The first is a URL on disk — where the file is — and the second is the title QLPreviewController uses in the item navigation list.

Open File.swift and import QuickLook by adding the following line at the top of the file:

import QuickLook

Then, add this code at the end of the file:

// MARK: - QLPreviewItem
extension File: QLPreviewItem {
  var previewItemURL: URL? {
    url
  }
}

Conforming this class to QLPreviewItem lets you return an instance of File to the delegate method. If you don’t return a value to previewItemTitle , QLPreviewController uses the last path component of the URL as a title.

Note : NSURL already conforms to QLPreviewItem . If you don’t have a class representation of your files you may use an instance of NSURL as a QLPreviewItem .

Go back to ViewController.swift and replace the code inside previewController(_:previewItemAt:) with:

files[index]

Build and run. Open a spell to make sure everything is working.

The app continues to open tutorials as expected, but now all you have to do is return an instance of File for the selected index.

Generating Thumbnails for Each Document

The app looks pretty good so far, but it would be so much better if you could see a thumbnail of the document you want to preview. Fortunately, generating thumbnails is easy with the QuickLookThumbnailing framework.

Open File.swift and add this code below the QLPreviewItem class extension:

// MARK: - QuickLookThumbnailing
extension File {
  func generateThumbnail(completion: @escaping (UIImage) -> Void) {
    // 1
    let size = CGSize(width: 128, height: 102)
    let scale = UIScreen.main.scale
    // 2
    let request = QLThumbnailGenerator.Request(
      fileAt: url,
      size: size,
      scale: scale,
      representationTypes: .all)
    
    // 3
    let generator = QLThumbnailGenerator.shared
    generator.generateBestRepresentation(for: request) { thumbnail, error in
      if let thumbnail = thumbnail {
        completion(thumbnail.uiImage)
      } else if let error = error {
        // Handle error
        print(error)
      }
    }
  }
}

Here’s a breakdown of what’s happening:

1. You define a size and scale. The framework uses them to generate a thumbnail of that size and scale.
2. Then you create a thumbnail request using the file’s URL, size, scale and representation type.
3. Finally you use QLThumbnailGenerator to generate the thumbnail for that request. By calling generateBestRepresentation(for:completion:) , the framework generates the best possible thumbnail representation for the file or returns an error.

Open FileCell.swift and add the following at the end of update(with:) :

file.generateThumbnail { [weak self] image in
  DispatchQueue.main.async {
    self?.thumbnailImageView.image = image
  }
}

This updates the thumbnail image on the main thread when the collection view loads. Build and run to see the results.

When dequeuing a cell, the file generates a thumbnail and assigns it to the cell’s UIImageView . Now you can see what you’re previewing even before opening the file. When QuickLook can’t generate a thumbnail, it generates an icon representation of the type.

When generating high quality thumbnails for big files, QLThumbnailGenerator can take some time. Fortunately, there’s another method that can solve this: generateRepresentations(request:update:) .

Open File.swift . Inside generateThumbnail(completion:) , replace:

generator.generateBestRepresentation(for: request) { thumbnail, error in

With the following:

generator.generateRepresentations(for: request) { thumbnail, _, error in

This method quickly generates a file icon or a low-quality thumbnail and calls the updateHandler . Once a higher quality thumbnail is available, the framework calls the updateHandler again. If this thumbnail is available before the lower one, it may skip the first call entirely.

Build and run to make sure everything’s working fine.

Adding the Default Zoom Transition

Animations are an important part of iOS user interfaces. They give a polished feeling and sense of continuity to your app. Introduced in iOS 10 , QuickLook provides an easy way to add animations with a modern method that does all the heavy lifting for you.

Open ViewController.swift and add a new property at the top of the class:

weak var tappedCell: FileCell?

Then, inside collectionView(_:didSelectItemAt:) , add the following under quickLookViewController.dataSource = self :

tappedCell = collectionView.cellForItem(at: indexPath) as? FileCell
quickLookViewController.delegate = self

This code stores the tapped cell and sets the delegate property to self . But, since ViewController doesn’t conform to QLPreviewControllerDelegate , it can’t set self as the delegate. To fix this, create a class extension at the bottom of the file conforming to QLPreviewControllerDelegate :

// MARK: - QLPreviewControllerDelegate
extension ViewController: QLPreviewControllerDelegate {
  func previewController(
    _ controller: QLPreviewController,
    transitionViewFor item: QLPreviewItem
  ) -> UIView? {
    tappedCell?.thumbnailImageView
  }
}

By returning any UIView to previewController(_:transitionViewFor:) , the framework creates a smooth zoom transition from this view to the preview. Here, you return the tapped cell’s UIImageView to create this transition.

When presenting or dismissing the preview, QuickLook uses the cell thumbnail to create a smooth zoom transition.

Build and run. Select a spell to see the transition in action.

QuickLook Editing Tools

iOS 13 brings users a cool new feature: simple editing support for images, PDFs and videos via QuickLook. This lets users preview and edit files from the QLPreviewController . The tools are the same ones you use when previewing a file in Files or editing an attachment in Mail.

QLPreviewController also provides simple support for trimming and rotating videos. This is quite handy when you need to take some notes on a PDF tutorial, for example.

Note : Bundle files are read only , meaning you cannot edit them unless you save a copy with the edits somewhere else. For simplicity, the app makes a copy of each file to its documents folder the first time it launches. The app uses those copies to display the collection of spells.

Enabling PDF Editing

In ViewController.swift , add the following code to the QLPreviewControllerDelegate extension at the bottom of the file:

func previewController(
  _ controller: QLPreviewController,
  editingModeFor previewItem: QLPreviewItem
) -> QLPreviewItemEditingMode {
  .updateContents
}

Here you return a value that indicates how the preview controller edits the file’s content. QuickLook handles editing by either overwriting the original file, .updateContent , or by creating an edited copy of it, .createCopy . If you don’t want the user to edit that file, you can return .disabled and QuickLook won’t show the edit button.

Build and run. Select the Light Charm tutorial and tap the new edit button at the top right. When a markup panel appears, highlight its light description with your favorite color.

QuickLook saves your changes in the original file, but you may notice those changes aren’t reflected on the thumbnail. That’s because you must generate a new thumbnail for that file with the edited file.

To fix this, update the UI after QuickLook saves the changes. Add this code inside the QLPreviewControllerDelegate extension block:

func previewController(
  _ controller: QLPreviewController,
  didUpdateContentsOf previewItem: QLPreviewItem
) {
  guard let file = previewItem as? File else { return }
  DispatchQueue.main.async {
    self.tappedCell?.update(with: file)
  }
}

QLPreviewController calls previewController(_:editUpdateContentsOf:) after the preview controller overwrites the contents of the original file. You can update the UI by reloading the contents of that cell.

When creating a copy for your edited file, QLPreviewController calls another method, previewController(_:didSaveEditedCopyOf:at:) , when saving. Here, the framework gives you a temporary URL where the edited file is. You can use this URL to save the file anywhere you’d like in the app’s folders.

Build and run again. Make another edit on the file. When saving, the cell updates with a new thumbnail.

Great job! This is the end of the tutorial, but that doesn’t mean you have to stop learning! Why don’t you learn some spells? Just be careful with dark magic. :]

Where to Go From Here?

You can download the final project by clicking the Download Materials button at the top or bottom of the tutorial.

In this tutorial you learned how to preview commonly used files with QuickLook, generate thumbnails and even enable simple PDF editing. But you can learn even more on the subject. For example, you can provide custom previews for your custom file type using Preview extensions or even provide custom thumbnails for your custom file format using Quick Look thumbnails extensions.

To learn more about Quick Look , checkout WWDC 2018’s Quick look Previews from the ground up session as well as WWDC 2019’s What’s New in File Management and Quick Look session.

I hope you enjoyed this tutorial. If you have any questions or comments, please feel free to join the discussion below.