Kingfisher 101
The simplest use-case is setting an image to an image view with the UIImageView
extension:
import Kingfisher
let url = URL(string: "https://example.com/image.png")
imageView.kf.setImage(with: url)
Kingfisher will download the image from url
, send it to both memory cache and disk cache, and display it in imageView
.
When you set it with the same URL later, the image will be retrieved from the cache and shown immediately.
It also works if you use SwiftUI:
var body: some View {
KFImage(URL(string: "https://example.com/image.png")!)
}
A More Advanced Example
With the powerful options, you can do hard tasks with Kingfisher in a simple way. For example, the code below:
- Downloads a high-resolution image.
- Downsamples it to match the image view size.
- Makes it round cornered with a given radius.
- Shows a system indicator and a placeholder image while downloading.
- When prepared, it animates the small thumbnail image with a “fade in” effect.
- The original large image is also cached to disk for later use, to get rid of downloading it again in a detail view.
- A console log is printed when the task finishes, either for success or failure.
let url = URL(string: "https://example.com/high_resolution_image.png")
let processor = DownsamplingImageProcessor(size: imageView.bounds.size)
|> RoundCornerImageProcessor(cornerRadius: 20)
imageView.kf.indicatorType = .activity
imageView.kf.setImage(
with: url,
placeholder: UIImage(named: "placeholderImage"),
options: [
.processor(processor),
.scaleFactor(UIScreen.main.scale),
.transition(.fade(1)),
.cacheOriginalImage
])
{
result in
switch result {
case .success(let value):
print("Task done for: \(value.source.url?.absoluteString ?? "")")
case .failure(let error):
print("Job failed: \(error.localizedDescription)")
}
}
It is a common situation I can meet in my daily work. Think about how many lines you need to write without Kingfisher!
Method Chaining
If you are not a fan of the kf
extension, you can also prefer to use the KF
builder and chained the method
invocations. The code below is doing the same thing:
// Use `kf` extension
imageView.kf.setImage(
with: url,
placeholder: placeholderImage,
options: [
.processor(processor),
.loadDiskFileSynchronously,
.cacheOriginalImage,
.transition(.fade(0.25)),
.lowDataMode(.network(lowResolutionURL))
],
progressBlock: { receivedSize, totalSize in
// Progress updated
},
completionHandler: { result in
// Done
}
)
// Use `KF` builder
KF.url(url)
.placeholder(placeholderImage)
.setProcessor(processor)
.loadDiskFileSynchronously()
.cacheMemoryOnly()
.fade(duration: 0.25)
.lowDataModeSource(.network(lowResolutionURL))
.onProgress { receivedSize, totalSize in }
.onSuccess { result in }
.onFailure { error in }
.set(to: imageView)
And even better, if later you want to switch to SwiftUI, just change the KF
above to KFImage
, and you’ve done:
struct ContentView: View {
var body: some View {
KFImage.url(url)
.placeholder(placeholderImage)
.setProcessor(processor)
.loadDiskFileSynchronously()
.cacheMemoryOnly()
.fade(duration: 0.25)
.lowDataModeSource(.network(lowResolutionURL))
.onProgress { receivedSize, totalSize in }
.onSuccess { result in }
.onFailure { error in }
}
}
Requirements
Kingfisher 8.0
- (UIKit/AppKit) iOS 13.0+ / macOS 10.15+ / tvOS 13.0+ / watchOS 6.0+ / visionOS 1.0+
- (SwiftUI) iOS 14.0+ / macOS 11.0+ / tvOS 14.0+ / watchOS 7.0+ / visionOS 1.0+
- Swift 5.0+
Kingfisher 7.0
- (UIKit/AppKit) iOS 12.0+ / macOS 10.14+ / tvOS 12.0+ / watchOS 5.0+ / visionOS 1.0+
- (SwiftUI) iOS 14.0+ / macOS 11.0+ / tvOS 14.0+ / watchOS 7.0+ / visionOS 1.0+
- Swift 5.0+
Swift Package Manager
- File > Swift Packages > Add Package Dependency
- Add
https://github.com/onevcat/Kingfisher.git
- Select “Up to Next Major” with “7.0.0”
CocoaPods
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '12.0'
use_frameworks!
target 'MyApp' do
pod 'Kingfisher', '~> 7.0'
end
Pre-built Framework
- Open the release page, download the latest version of Kingfisher from the assets section.
- Drag the
Kingfisher.xcframework
into your project and add it to the target (usually the app target). - Select your target, in the “General” Tab, find the “Frameworks, Libraries, and Embedded Content” section, set the
Embed Without Signing
to Kingfisher.
Migrating
Kingfisher 8.0 Migration Kingfisher 7.0 Migration
If you are using an even earlier version, see the guides below to know the steps for migrating.
Next Steps
Check the documentation and tutorials:
Other
Future of Kingfisher
I want to keep Kingfisher lightweight. This framework focuses on providing a simple solution for downloading and caching images. This doesn’t mean the framework can’t be improved. Kingfisher is far from perfect, so necessary and useful updates will be made to make it better.
About the logo
The logo of Kingfisher is inspired by Tangram (七巧板), a dissection puzzle consisting of seven flat shapes from China. I believe she’s a kingfisher bird instead of a swift, but someone insists that she is a pigeon. I guess I should give her a name. Hi, guys, do you have any suggestions?