UIKit and AppKit

How to use Nuke with UI components

Nuke provides convenience extension for image views with multiple options to control the image view extensions behavior.

Check out LazyImageView component from NukeUI.

Image View #

Download and display an image in an image view with a single line of code:

Nuke.loadImage(with: url, into: imageView)

If the image is stored in the memory cache, it is displayed immediately with no animations. If not, the image is first loaded using an image pipeline.

See Image Pipeline Guide to learn how images are downloaded and processed.

Table View #

Before loading a new image, the view is prepared for reuse by canceling any outstanding requests and removing a previously displayed image, making it perfect for table views.

func tableView(_ tableView: UITableView, cellForItemAt indexPath: IndexPaths) -> UITableViewCell {
    // ...
    Nuke.loadImage(with: url, into: cell.imageView)

What works for UITableView, also does for a UICollectionView. You can see UICollectionView in action in the demo project.

When the view is deallocated, an associated request also gets canceled automatically. To manually cancel the request, call Nuke.cancelRequest(for: imageView).

ImageLoadingOptions #

ImageLoadingOptions offers multiple options to control the image view extensions behavior.

let options = ImageLoadingOptions(
    placeholder: UIImage(named: "placeholder"),
    transition: .fadeIn(duration: 0.33)
Nuke.loadImage(with: url, options: options, into: imageView)

The extensions have a limited set of options. If you need more, check out LazyImageView in NukeUI.

Placeholder #

Placeholder to be displayed while the image is loading. nil by default.

options.placeholder = UIImage(named: "placeholder")

Failure Image #

Image to be displayed when the request fails. nil by default.

option.failureImage = UIImage(named: "oopsie")

Transitions #

The image transition animation performed when displaying a loaded image. Only runs when the image was not found in the memory cache (use alwaysTransition to always run the animation). nil by default.

options.transition = .fadeIn(duration: 0.33))

For a complete list of available transitions see ImageLoadingOptions.Transitions. Use failureImageTransition to failure image.

Content Modes #

You can change content mode for each of the image types: placeholder, success, failure. This is useful when a placeholder image needs to be displas with .center, but image with .scaleAspectFill. By default, nil – don’t change the content mode.

options.contentModes = .init(success: .scaleAspectFill, failure: .center, placeholder: .center)

Tint Colors #

You can also specify a custom content modes to be used for each image type: placeholder, success, failure.

options.tintColors = .init(success: .green, failure: .red, placeholder: .yellow)

Shared Options #

If you want to modify the default options, set ImageLoadingOptions.shared.

ImageLoadingOptions.shared.transition = .fadeIn(duration: 0.33))

Other Options #

For a complete list of options, see ImageLoadingOptions. Some options, such as isProgressiveRenderingEnabled will be covered later.

Built-in extensions for image views are designed to get you up and running as quickly as possible. But if you want to have more control, or use some of the advanced features, like animated images, it is recommended to use ImagePipeline directly.

Progressive Decoding #

Enable progressive decoding with a single line of code. Nuke supports progressive JPEG out of the box, and WebP via a plugin built by the community.

Nuke supports progressive JPEG out of the box.

See “Image Formats” to learn about other image formats supported by Nuke.

Custom Views #

You can use image view extensions with custom views by implementing Nuke_ImageDisplaying protocol1.

extension UIImageView: Nuke_ImageDisplaying {
    open func nuke_display(image: UIImage?, data: Data?) {
        self.image = image

Nuke provides built-in implementations for UIImageView, NSImageView, and WKInterfaceImage.

Customizing Requests #

All the examples from this guide used Nuke.load​Image(with:​​into:​) with a URL. But you can have even more control over the image download by using ImageRequest. To learn more, see “Customizing Requests”.

  1. The name of the protocol has a prefix because it’s an Objective-C protocol. Objective-C runtime allows you to override methods declared in extensions in subclasses.