1# SwiftUI Image Optimization Reference
2 
3## Table of Contents
4 
5- [AsyncImage Best Practices](#asyncimage-best-practices)
6- [Image Decoding and Downsampling (Optional Optimization)](#image-decoding-and-downsampling-optional-optimization)
7- [UIImage Loading and Memory](#uiimage-loading-and-memory)
8- [SF Symbols](#sf-symbols)
9- [Summary Checklist](#summary-checklist)
10 
11## AsyncImage Best Practices
12 
13### Basic AsyncImage with Phase Handling
14 
15```swift
16// Good - handles loading and error states
17AsyncImage(url: imageURL) { phase in
18    switch phase {
19    case .empty:
20        ProgressView()
21    case .success(let image):
22        image
23            .resizable()
24            .aspectRatio(contentMode: .fit)
25    case .failure:
26        Image(systemName: "photo")
27            .foregroundStyle(.secondary)
28    @unknown default:
29        EmptyView()
30    }
31}
32.frame(width: 200, height: 200)
33```
34 
35For custom placeholders, replace `ProgressView()` in the `.empty` case with your placeholder view. Add `.transition(.opacity)` to the success case and `.animation(.easeInOut, value: imageURL)` to the container for fade-in transitions.
36 
37## Image Decoding and Downsampling (Optional Optimization)
38 
39**When you encounter `UIImage(data:)` usage, consider suggesting image downsampling as a potential performance improvement**, especially for large images in lists or grids.
40 
41### Current Pattern That Could Be Optimized
42 
43```swift
44// Current pattern - decodes full image on main thread
45// Unsafe - force unwrap can crash if imageData is invalid
46Image(uiImage: UIImage(data: imageData)!)
47    .resizable()
48    .aspectRatio(contentMode: .fit)
49    .frame(width: 200, height: 200)
50```
51 
52### Suggested Optimization Pattern
53 
54```swift
55// Suggested optimization - decode and downsample off main thread
56struct OptimizedImageView: View {
57    let imageData: Data
58    let targetSize: CGSize
59    @State private var processedImage: UIImage?
60    
61    var body: some View {
62        Group {
63            if let processedImage {
64                Image(uiImage: processedImage)
65                    .resizable()
66                    .aspectRatio(contentMode: .fit)
67            } else {
68                ProgressView()
69            }
70        }
71        .task {
72            processedImage = await decodeAndDownsample(imageData, targetSize: targetSize)
73        }
74    }
75    
76    private func decodeAndDownsample(_ data: Data, targetSize: CGSize) async -> UIImage? {
77        await Task.detached {
78            guard let source = CGImageSourceCreateWithData(data as CFData, nil) else {
79                return nil
80            }
81            
82            let options: [CFString: Any] = [
83                kCGImageSourceThumbnailMaxPixelSize: max(targetSize.width, targetSize.height),
84                kCGImageSourceCreateThumbnailFromImageAlways: true,
85                kCGImageSourceCreateThumbnailWithTransform: true
86            ]
87            
88            guard let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, options as CFDictionary) else {
89                return nil
90            }
91            
92            return UIImage(cgImage: cgImage)
93        }.value
94    }
95}
96 
97// Usage
98OptimizedImageView(
99    imageData: imageData,
100    targetSize: CGSize(width: 200, height: 200)
101)
102```
103 
104### Reusable Downsampling Actor
105 
106For production use, wrap the logic in an `actor` with scale-aware sizing and cache-disabled source options:
107 
108```swift
109actor ImageProcessor {
110    func downsample(data: Data, targetSize: CGSize) -> UIImage? {
111        let scale = await UIScreen.main.scale
112        let maxPixel = max(targetSize.width, targetSize.height) * scale
113        let sourceOptions: [CFString: Any] = [kCGImageSourceShouldCache: false]
114        guard let source = CGImageSourceCreateWithData(data as CFData, sourceOptions as CFDictionary) else { return nil }
115        let downsampleOptions: [CFString: Any] = [
116            kCGImageSourceCreateThumbnailFromImageAlways: true,
117            kCGImageSourceThumbnailMaxPixelSize: maxPixel,
118            kCGImageSourceCreateThumbnailWithTransform: true,
119            kCGImageSourceShouldCacheImmediately: true
120        ]
121        guard let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, downsampleOptions as CFDictionary) else { return nil }
122        return UIImage(cgImage: cgImage)
123    }
124}
125```
126 
127Key details: `kCGImageSourceShouldCache: false` on the source prevents the full-resolution image from being cached in memory. Multiplying `targetSize` by `UIScreen.main.scale` ensures the thumbnail is sharp on Retina displays. `kCGImageSourceShouldCacheImmediately: true` on the thumbnail forces decoding at creation time rather than at first render.
128 
129### When to Suggest This Optimization
130 
131Mention this optimization when you see `UIImage(data:)` usage, particularly in:
132- Scrollable content (List, ScrollView with LazyVStack/LazyHStack)
133- Grid layouts with many images
134- Image galleries or carousels
135- Any scenario where large images are displayed at smaller sizes
136 
137**Don't automatically apply it**—present it as an optional improvement for performance-sensitive scenarios.
138 
139## UIImage Loading and Memory
140 
141### UIImage(named:) Caches in System Cache
142 
143`UIImage(named:)` adds images to the system cache, which can cause memory spikes when loading many images (e.g., in a slider or gallery). For single-use or frequently-rotated images, use `UIImage(contentsOfFile:)` to bypass the cache:
144 
145```swift
146// Caches in system cache -- memory builds up
147let image = UIImage(named: "Wallpapers/image_001.jpg")
148 
149// No system caching -- memory stays flat
150guard let path = Bundle.main.path(forResource: "Wallpapers/image_001.jpg", ofType: nil) else { return nil }
151let image = UIImage(contentsOfFile: path)
152```
153 
154### NSCache for Controlled Image Caching
155 
156When image processing (resizing, filtering) is needed, use `NSCache` with a `countLimit` to bound memory instead of relying on system caching:
157 
158```swift
159struct ImageCache {
160    private let cache = NSCache<NSString, UIImage>()
161 
162    init(countLimit: Int = 50) {
163        cache.countLimit = countLimit
164    }
165 
166    subscript(key: String) -> UIImage? {
167        get { cache.object(forKey: key as NSString) }
168        nonmutating set {
169            if let newValue {
170                cache.setObject(newValue, forKey: key as NSString)
171            } else {
172                cache.removeObject(forKey: key as NSString)
173            }
174        }
175    }
176}
177```
178 
179## SF Symbols
180 
181```swift
182Image(systemName: "star.fill")
183    .foregroundStyle(.yellow)
184    .symbolRenderingMode(.multicolor)     // or .hierarchical, .palette, .monochrome
185 
186// Animated symbols (iOS 17+)
187Image(systemName: "antenna.radiowaves.left.and.right")
188    .symbolEffect(.variableColor)
189```
190 
191Variants are available via naming convention: `star.circle.fill`, `star.square.fill`, `folder.badge.plus`.
192 
193## Summary Checklist
194 
195- [ ] Use `AsyncImage` with proper phase handling
196- [ ] Handle empty, success, and failure states
197- [ ] Consider downsampling for `UIImage(data:)` in performance-sensitive scenarios
198- [ ] Decode and downsample images off the main thread
199- [ ] Use appropriate target sizes for downsampling
200- [ ] Consider image caching for frequently accessed images
201- [ ] Use SF Symbols with appropriate rendering modes
202 
203**Performance Note**: Image downsampling is an optional optimization. Only suggest it when you encounter `UIImage(data:)` usage in performance-sensitive contexts like scrollable lists or grids.
204