SDWebImageSwiftUI

If you support iOS 15+/macOS 12+ only and don't care about animated image format, try SwiftUI's AsyncImage

What's for

SDWebImageSwiftUI is a SwiftUI image loading framework, which based on SDWebImage.

It brings all your favorite features from SDWebImage, like async image loading, memory/disk caching, animated image playback and performances.

The framework provide the different View structs, which API match the SwiftUI framework guideline. If you're familiar with Image, you'll find it easy to use WebImage and AnimatedImage.

Apple VisionOS

From v3.0.0, SDWebImageSwiftUI can be compiled for visionOS platform. However, due to the lacking package manager support (need tools update), we don't support CocoaPods/SPM yet.

You can only use the Xcode's built-in package manager dependency to build on visionOS.

To run the visionOS example, you need to clone and add both SDWebImage and SDWebImageSwiftUI, open the SDWebImageSwiftUI.xcworkspace and drag those folders to become local package dependency, see: Editing a package dependency as a local package

If you really want to build framework instead of using Xcode's package dependency, following the manual steps below:

1. Clone SDWebImage, open SDWebImage.xcodeproj and build SDWebImage target for visionOS platform (Change MACH_O_TYPE to static library if you need)
2. Clone SDWebImageSwiftUI, create directory at Carthage/Build/visionOS and copy SDWebImage.framework into it
3. Open SDWebImageSwiftUI.xcodeproj and build SDWebImageSwiftUI visionOS target

Features

Since SDWebImageSwiftUI is built on top of SDWebImage, it provide both the out-of-box features as well as advanced powerful features you may want in real world Apps. Check our Wiki when you need:

• [x] Animated Image full-stack solution, with balance of CPU && RAM
• [x] Progressive image loading, with animation support
• [x] Reusable download, never request single URL twice
• [x] URL Request / Response Modifier, provide custom HTTP Header
• [x] Image Transformer, apply corner radius or CIFilter
• [x] Multiple caches system, query from different source
• [x] Multiple loaders system, load from different resource

You can also get all benefits from the existing community around with SDWebImage. You can have massive image format support (GIF/APNG/WebP/HEIF/AVIF/SVG/PDF) via Coder Plugins, PhotoKit support via SDWebImagePhotosPlugin, Firebase integration via FirebaseUI, etc.

Besides all these features, we do optimization for SwiftUI, like Binding, View Modifier, using the same design pattern to become a good SwiftUI citizen.

Version

This framework is under heavily development, it's recommended to use the latest release as much as possible (including SDWebImage dependency).

This framework follows Semantic Versioning. Each source-break API changes will bump to a major version.

Changelog

This project use keep a changelog format to record the changes. Check the CHANGELOG.md about the changes between versions. The changes will also be updated in Release page.

Contribution

All issue reports, feature requests, contributions, and GitHub stars are welcomed. Hope for active feedback and promotion if you find this framework useful.

Requirements

• Xcode 14+
• iOS 14+
• macOS 11+
• tvOS 14+
• watchOS 7+
• visionOS 1+

for SwiftUI 1.0 (iOS 13)

iOS 14(macOS 11) introduce the SwiftUI 2.0, which keep the most API compatible, but changes many internal behaviors, which breaks the SDWebImageSwiftUI's function.

From v3.0.0, SDWebImageSwiftUI drop iOS 13 support. To use on iOS 13, checkout the latest v2.x version (or using 2.x branch) instead.

for future transition

Since SDWebImage 6.0 will introduce mixed Swift/Objc codebase, this repo will migrate into SDWebImage Core Repo.

But don't worry, we will use the automatic cross module overlay, whic means, you can use:

import SwiftUI
import SDWebImage

to works like:

import SwiftUI
import SDWebImage
import SDWebImageSwiftUI // <-- Automatic infer this

You will automatically link the SDWebImageSwiftUI, and this library's naming will still be preserved in SPM target. So the transition is smooth for most of you, I don't want to bump another major version. The 3.x is the final version for SDWebImageSwiftUI dedicated repo

Note: For super advanced user, if you using some custom Swift toolchain, be sure to pass -Xfrontend -enable-cross-import-overlays

Installation

Swift Package Manager

SDWebImageSwiftUI is available through Swift Package Manager.

• For App integration

For App integration, you should using Xcode 12 or higher, to add this package to your App target. To do this, check Adding Package Dependencies to Your App about the step by step tutorial using Xcode.

• For downstream framework

For downstream framework author, you should create a Package.swift file into your git repo, then add the following line to mark your framework dependent our SDWebImageSwiftUI.

let package = Package(
    dependencies: [
        .package(url: "https://github.com/SDWebImage/SDWebImageSwiftUI.git", from: "3.0.0")
    ],
)

CocoaPods

SDWebImageSwiftUI is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'SDWebImageSwiftUI'

Carthage

SDWebImageSwiftUI is available through Carthage.

github "SDWebImage/SDWebImageSwiftUI"

Usage

Using WebImage to load network image

• [x] Supports placeholder and detail options control for image loading as SDWebImage
• [x] Supports progressive image loading (like baseline)
• [x] Supports success/failure/progress changes event for custom handling
• [x] Supports indicator with activity/progress indicator and customization
• [x] Supports built-in animation and transition, powered by SwiftUI
• [x] Supports animated image as well!

var body: some View {
    WebImage(url: URL(string: "https://nokiatech.github.io/heif/content/images/ski_jump_1440x960.heic")) { image in
        image.resizable() // Control layout like SwiftUI.AsyncImage, you must use this modifier or the view will use the image bitmap size
    } placeholder: {
            Rectangle().foregroundColor(.gray)
    }
    // Supports options and context, like `.delayPlaceholder` to show placeholder only when error
    .onSuccess { image, data, cacheType in
        // Success
        // Note: Data exist only when queried from disk cache or network. Use `.queryMemoryData` if you really need data
    }
    .indicator(.activity) // Activity Indicator
    .transition(.fade(duration: 0.5)) // Fade Transition with duration
    .scaledToFit()
    .frame(width: 300, height: 300, alignment: .center)
}

Note: This WebImage using Image for internal implementation, which is the best compatible for SwiftUI layout and animation system. But unlike SwiftUI's Image which does not support animated image or vector image, WebImage supports animated image as well (by defaults from v2.0.0).

However, The WebImage animation provide simple common use case, so it's still recommend to use AnimatedImage for advanced controls like progressive animation rendering, or vector image rendering.

@State var isAnimating: Bool = true
var body: some View {
    WebImage(url: URL(string: "https://raw.githubusercontent.com/liyong03/YLGIFImage/master/YLGIFImageDemo/YLGIFImageDemo/joy.gif"), isAnimating: $isAnimating)) // Animation Control, supports dynamic changes
    // The initial value of binding should be true
    .customLoopCount(1) // Custom loop count
    .playbackRate(2.0) // Playback speed rate
    .playbackMode(.bounce) // Playback normally to the end, then reversely back to the start
    // `WebImage` supports advanced control just like `AnimatedImage`, but without the progressive animation support
}

Note: For indicator, you can custom your own as well. For example, iOS 14/watchOS 7 introduce the new ProgressView, which can be easily used via:

WebImage(url: url)
.indicator(.activity)

or you can just write like:

WebImage(url: url)
.indicator {
    Indi