Image Requests

How to change request priority, cache policy, processors, and more

ImageRequest allows you to set image processors, change the request priority, and more.

let request = ImageRequest(
    url: URL(string: "http://example.com/image.jpeg"),
    processors: [.resize(size: imageView.bounds.size)],
    priority: .high,
    options: [.reloadIgnoringCacheData]
)
Nuke.loadImage(with: url, into: imageView)

Processors #

Set processors to apply one of the built-in processors that can be found in ImageProcessors namespace or a custom one.

var request = ImageRequest(url: URL(string: "http://..."))
request.processors = [.resize(size: imageView.bounds.size)]

Another way to apply processors is by setting the default processors on ImagePipeline.Configuration.

See “Image Processing” for more information on image processing.

Thumbnails #

To load a thumbnail instead of a full image, pass ImageRequest.ThumbnailOptions in the request userInfo using .thumbnailKey.

let thumbnail = ImageRequest.ThumbnailOptions(maxPixelSize: 400)
let request = ImageRequest(url: URL(string: "http://..."), userInfo: [.thumbnailKey: thumbnail])

This operation generates the thumbnail directly from the image data using CGImageSourceCreateThumbnailAtIndex API. It is more efficient and uses significantly less memory than ImageProcessors.Resize, especially when generating thumbnails for large images.

By default, it always generates a thumbnail. To use the thumbnail embedded in the image, see create​Thumbnail​From​Image​Always and createThumbnailFromImageIfAbsent.

Priority #

The execution priority of the request. The priority affects the order in which the image requests are executed. By default, .normal1.

You can change the priority of a running task using ImageTask.priority.

var request = ImageRequest(url: URL(string: "http://..."))
request.priority = .high

Options #

By default, the pipeline makes full use of all of its caching layers. You can change this behavior using ImageRequest.Options. For example, you can ignore local caches using .reloadIgnoringCachedData option.

var request = ImageRequest(url: URL(string: "http://..."))
request.options = [.reloadIgnoringCachedData]

Another useful cache policy is .returnCacheDataDontLoad that allows you to existing cache data and fail if no cached data is available.

See “Caching” for more information on caching.

User Info #

You can also provide custom options to the request via userInfo. There are also some rarely used built-in options that are passed via userInfo.

By default, a pipeline uses URLs as unique image identifiers for caching and task coalescing. You can override this behavior by providing an .imageIdKey instead. For example, you can use it to remove transient query parameters from the request.

let request = ImageRequest(
    url: URL(string: "http://example.com/image.jpeg?token=123"),
    userInfo: [.imageIdKey: "http://example.com/image.jpeg"]
)

There also a key that you can use to override the image scale (another option is to provide a custom decoder via the pipeline configuration).

let request = ImageRequest(
    url: URL(string: "http://example.com/image.jpeg"),
    userInfo: [.scaleKey: 3] // 3.0 also works
)

Sources #

The request can be instantiated either with a URL or with a URLRequest.

let urlRequest = URLRequest(url: imageUrl, cachePolicy: .returnCacheDataDontLoad)
let request = ImageRequest(urlRequest: urlRequest)

If you have a custom data source or want to process image data from memory, you can also use a special Combine-based initializer.

let request = ImageRequest(
    id: "image-01",
    data: Just(data),
    processors: [ImageProcessors.Resize(width: 44)]
)

  1. The priority management is key for Nuke performance. ImagePrefetcher uses .low priority to avoid interfering with .normal requests. ↩