Image Pipeline

How to use ImagePipeline

At the core of Nuke is the ImagePipeline class that you can use to load images directly. While built-in UI extensions have a rich set of APIs, they still can’t cover all scenarios. And this is where the pipeline comes in.

ImagePipeline #

You can start by using a shared pipeline and configure a custom one later if needed.

ImagePipeline.shared.loadImage(with: url) { result in
   print("task completed")
)

Load Image #

Use loadImage() method to load an image for the given request.

let task = ImagePipeline.shared.loadImage(
    with: url,
    progress: { preview, completed, total in
        print("progress updated")
    },
    completion: { result in
        print("task completed")
    }
)

If you look at the method signature, you’ll see that it accepts ImageRequestConvertible as a request. Every time you see it, it means that the method works with the following types: ImageRequest, URL, String, and URLRequest.

When you call this method, the pipeline checks if the image exists in any of the cache layers, prioritizing the fastest caches (memory cache). If there is no cached data, the pipeline starts the download. When the data is loaded, it decodes the data, applies the processors, and decompresses the image in the background.

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

The completion closure always gets called asynchronously. By default, it gets called on the main thread, but you can customize it using an optional queue parameter or setting a global callbackQueue for the pipeline. To check if the image is stored in a memory cache synchronously, use pipeline.cache[url].

Load Data #

Use loadData() method to load image data.

ImagePipeline.shared.loadData(with: url) { result in
   print("task completed")
)

Image Publisher #

ImagePipeline also has Combine support with imagePublisher(with:) method.

public extension ImagePipeline {
    func imagePublisher(with request: ImageRequestConvertible) -> ImagePublisher
}

Learn more about Combine support in a dedicated guide.

ImageTask #

When you start the request, the pipeline returns an ImageTask object, which can be used for cancellation and more.

let task = ImagePipeline.shared.loadData(with: url) { result in
   print("task completed")
)

The pipeline maintains a strong reference to the task until the request finishes or fails; you do not need to maintain a reference to the task unless it is useful to do so for your app’s internal bookkeeping purposes.

Cancellation #

Mark task for cancellation.

task.cancel()

Priority #

Change the priority of the outstanding task.

task.priority = .high

Progress #

In addition to the progress closure, you can observe the progress of the download using Foundation.Progress.

let progress = task.progress

Builder Extension #

Nuke is easy to learn because it uses only the basic Swift language features and is written in an idiomatic way. NukeBuilder 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)
    .options([.reloadIgnoringCachedData])
    .load { result in
        print(result)
    }
    
// Returns a discardable `ImageTask`.

Starting with Nuke 10, instead of loading an image right away, you can also create a Combine publisher.

import NukeBuilder

ImagePipeline.image(with: "https://example.com/image.jpeg")
    .resize(width: 320)
    ...
    .publisher

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.