Image View Extensions

How to use Nuke with UI components

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

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)

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.

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?) {
        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”.

Task Builder #

Nuke is easy to learn because it uses only the basic Swift language features and is written in an idiomatic way. ImageTaskBuilder package provides a different way to use it.

Load Image #

Downloading an image and applying processors.

ImagePipeline.shared.image(with: URL(string: "https://")!)
    .resize(width: 320)
    .blur(radius: 10)
    .priority(.high)
    .load { result in
        print(result)
    }
    
// Returns a discardable `ImageTask`.

Display in Image View #

You can take the same image that you described previously and automatically display it in an image view.

let image = ImagePipeline.shared.image(with: URL(string: "https://")!)
    .resize(width: 320)
    .blur(radius: 10)
    .priority(.high)
    
let imageView: UIImageView

image.display(in: imageView)
    .transition(.fadeIn(duration: 0.33))
    .placeholder(UIImage.placeholder)
    .contentMode(.center, for: .placeholder)
    .load()

When you use display(in:) method, the returned object has options specific to the image view display: transition, placeholder, etc. These options match available options provided by ImageLoadingOptions.

  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.