Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .scripts/generate-llms.py
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@
ARTICLE_ORDER = [
"Essentials/getting-started.md",
"Essentials/swiftui.md",
"Essentials/replacing-async-image.md",
"Essentials/uikit.md",
"AnimatedImages.md",
"Essentials/troubleshooting.md",
Expand Down
148 changes: 148 additions & 0 deletions Documentation/Nuke.docc/Essentials/replacing-async-image.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,148 @@
# Replacing AsyncImage

Move from SwiftUI's `AsyncImage` to `LazyImage`, and learn what changes.

## Overview

`LazyImage` is shaped like `AsyncImage`: it takes a URL or a request, and a closure that builds the view for each state. The difference is where the image comes from. `AsyncImage` loads it with a `URLSession`. `LazyImage` loads it with an ``ImagePipeline``, so the image is cached in memory, a download that is already running is shared, the decoding happens off the main thread, and the request is canceled when the view goes away.

Most of the move is mechanical. Add `import NukeUI`, rename the view, and replace the `switch` on the phase with a check of the state.

## The Common Case

`AsyncImage` passes the closure a phase. `LazyImage` passes it the state, which has the same three outcomes as properties: `image` for `.success`, `error` for `.failure`, and neither for `.empty`.

```swift
// AsyncImage
AsyncImage(url: url) { phase in
switch phase {
case .success(let image):
image.resizable().scaledToFill()
case .failure:
Image(systemName: "photo")
case .empty:
ProgressView()
@unknown default:
EmptyView()
}
}

// LazyImage
LazyImage(url: url) { state in
if let image = state.image {
image.resizable().scaledToFill()
} else if state.error != nil {
Image(systemName: "photo")
} else {
ProgressView()
}
}
```

The same goes for the form with a separate placeholder. There is no `placeholder` closure, so the `else` branch is the placeholder.

```swift
// AsyncImage
AsyncImage(url: url) { image in
image.resizable()
} placeholder: {
ProgressView()
}

// LazyImage
LazyImage(url: url) { state in
if let image = state.image {
image.resizable()
} else {
ProgressView()
}
}
```

## Initializers

| AsyncImage | LazyImage |
|---|---|
| `AsyncImage(url:)` | `LazyImage(url:)` |
| `AsyncImage(url:scale:)` | Set `scale` on an ``ImageRequest``, as shown below |
| `AsyncImage(url:scale:content:placeholder:)` | `LazyImage(url:content:)`, with the placeholder in the `else` branch |
| `AsyncImage(url:scale:transaction:content:)` | `LazyImage(url:transaction:content:)` |
| `AsyncImage(request:)` and the other `request:` forms, on iOS 27 | `LazyImage(request:)` with ``ImageRequest/init(urlRequest:processors:priority:options:)``, from iOS 16 |
| `.asyncImageURLSession(_:)` | `.imagePipeline(_:)`, as shown below |
| `phase.image` | `state.image` |
| `phase.error` | `state.error` |

`AsyncImage` takes a `scale` because `Image` needs to know how many pixels make a point. `LazyImage` takes it from the request, and it is `1` by default, like the `scale` of `AsyncImage`.

```swift
var request = ImageRequest(url: url)
request.scale = 3

LazyImage(request: request) { state in
if let image = state.image {
image
}
}
```

To load with the headers, the cache policy, or the timeout of a `URLRequest`, pass it to the request.

```swift
LazyImage(request: ImageRequest(urlRequest: urlRequest)) { state in
if let image = state.image {
image
}
}
```

## Setting the Session

`asyncImageURLSession(_:)` sets the session that every `AsyncImage` below it loads with. `imagePipeline(_:)` does the same for `LazyImage`. Nuke builds the session itself, from the configuration of a ``DataLoader``, so that's where you put the headers, the timeouts, and the cache.

```swift
let configuration = DataLoader.defaultConfiguration
configuration.httpAdditionalHeaders = ["Authorization": "Bearer \(token)"]

let pipeline = ImagePipeline {
$0.dataLoader = DataLoader(configuration: configuration)
}

ContentView()
.imagePipeline(pipeline)
```

A pipeline set on a single view with `pipeline(_:)` takes precedence over the one in the environment. Without either, `LazyImage` loads with ``ImagePipeline/shared``. See <doc:loading-data> for the ways to customize how the data is loaded, including authentication challenges.

## Where the Behavior Differs

A view that is moved over compiles, but a few things work differently.

- **A missing URL is an error.** `LazyImage(url: nil)` doesn't stay in its loading state. It fails with ``ImagePipeline/Error/imageRequestMissing``, so `state.error` isn't `nil`. If a missing URL means that there is no image to show, check for it before you create the view.
- **The error has a type.** `state.error` is an ``ImagePipeline/Error``, and `AsyncImagePhase.failure` carries an `any Error`. Use the `dataLoadingFailed(error:)` case to get the error that `URLSession` reported.
- **Disappearing cancels the load.** The request is canceled when the view disappears, and it starts again when the view comes back. To change that, use `onDisappear(_:)`.

## Code That Takes a Phase

If your views take an `AsyncImagePhase`, for example a shared helper that draws every state in the same way, you don't have to rewrite them. Make a phase from the state.

```swift
extension LazyImageState {
var phase: AsyncImagePhase {
if let image {
.success(image)
} else if let error {
.failure(error)
} else {
.empty
}
}
}

LazyImage(url: url) { state in
AvatarContent(phase: state.phase)
}
```

## What You Get in Return

The phase has no room for most of what the pipeline knows, which is why the closure gets the state. Once you're on `LazyImage`, you can read `progress` and `isLoading`, set the `processors` and the `priority`, and play animated images. See <doc:swiftui> for the rest of `LazyImage`, <doc:image-processing> to resize an image to the size it is displayed at, and <doc:performance-guide> for the settings that matter in a list.
2 changes: 1 addition & 1 deletion Documentation/Nuke.docc/Essentials/swiftui.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ LazyImage(url: url) { state in
.clipped()
```

> Note: Unlike `AsyncImage`, `LazyImage` doesn't pass a phase enum to the closure – it passes the state itself, so you can read the download progress or the underlying ``ImageResponse`` while the view is on screen.
> Note: Unlike `AsyncImage`, `LazyImage` doesn't pass a phase enum to the closure – it passes the state itself, so you can read the download progress or the underlying ``ImageResponse`` while the view is on screen. See <doc:replacing-async-image> if you're moving from `AsyncImage`.

## Transitions

Expand Down
1 change: 1 addition & 0 deletions Documentation/Nuke.docc/Nuke.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ To install Nuke, use Swift Package Manager.

- <doc:getting-started>
- <doc:swiftui>
- <doc:replacing-async-image>
- <doc:uikit>
- <doc:objective-c>
- <doc:troubleshooting>
Expand Down
152 changes: 152 additions & 0 deletions Tests/DocumentationSnippets/Snippets/ReplacingAsyncImageSnippets.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
// The MIT License (MIT)
//
// Copyright (c) 2015-2026 Alexander Grebenyuk (github.com/kean).

// Snippets from `Documentation/Nuke.docc/Essentials/replacing-async-image.md`.
//
// This target exists only to make the hand-written samples in the articles
// compile. If a snippet here stops building, the article is out of date.

import SwiftUI
import NukeUI

// MARK: - The Common Case

private struct CommonCaseViews: View {
let url: URL

var body: some View {
// AsyncImage
AsyncImage(url: url) { phase in
switch phase {
case .success(let image):
image.resizable().scaledToFill()
case .failure:
Image(systemName: "photo")
case .empty:
ProgressView()
@unknown default:
EmptyView()
}
}

// LazyImage
LazyImage(url: url) { state in
if let image = state.image {
image.resizable().scaledToFill()
} else if state.error != nil {
Image(systemName: "photo")
} else {
ProgressView()
}
}
}
}

private struct PlaceholderViews: View {
let url: URL

var body: some View {
// AsyncImage
AsyncImage(url: url) { image in
image.resizable()
} placeholder: {
ProgressView()
}

// LazyImage
LazyImage(url: url) { state in
if let image = state.image {
image.resizable()
} else {
ProgressView()
}
}
}
}

// MARK: - Initializers

private struct ScaleView: View {
let url: URL

var body: some View {
let request = {
var request = ImageRequest(url: url)
request.scale = 3
return request
}()

LazyImage(request: request) { state in
if let image = state.image {
image
}
}
}
}

private struct URLRequestView: View {
let urlRequest: URLRequest

var body: some View {
LazyImage(request: ImageRequest(urlRequest: urlRequest)) { state in
if let image = state.image {
image
}
}
}
}

// MARK: - Setting the Session

private struct SessionView: View {
let token: String

var body: some View {
let configuration = DataLoader.defaultConfiguration
configuration.httpAdditionalHeaders = ["Authorization": "Bearer \(token)"]

let pipeline = ImagePipeline {
$0.dataLoader = DataLoader(configuration: configuration)
}

return ContentView()
.imagePipeline(pipeline)
}
}

private struct ContentView: View {
var body: some View { EmptyView() }
}

// MARK: - Code That Takes a Phase

extension LazyImageState {
var phase: AsyncImagePhase {
if let image {
.success(image)
} else if let error {
.failure(error)
} else {
.empty
}
}
}

private struct PhaseView: View {
let url: URL

var body: some View {
LazyImage(url: url) { state in
AvatarContent(phase: state.phase)
}
}
}

private struct AvatarContent: View {
let phase: AsyncImagePhase

var body: some View {
phase.image ?? Image(systemName: "person")
}
}
Loading