Kingfisher README

The project's README from github.com/onevcat/Kingfisher. As one markdown file: README.md.

Kingfisher

Kingfisher is a powerful, pure-Swift library for downloading and caching images from the web. It provides you a chance to use a pure-Swift way to work with remote images in your next app.

Features

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:

  1. Downloads a high-resolution image.
  2. Downsamples it to match the image view size.
  3. Makes it round cornered with a given radius.
  4. Shows a system indicator and a placeholder image while downloading.
  5. When prepared, it animates the small thumbnail image with a "fade in" effect.
  6. The original large image is also cached to disk for later use, to get rid of downloading it again in a detail view.
  7. 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

Kingfisher 7.0

Installation

Refer to one of the following tutorials to install and use the framework:

Alternatively, you can follow either of the methods below.

Swift Package Manager

CocoaPods

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '13.0'
use_frameworks!

target 'MyApp' do
  pod 'Kingfisher', '~> 8.0'
end

Pre-built Framework

  1. Open the release page, download the latest version of Kingfisher from the assets section.
  2. Drag the Kingfisher.xcframework into your project and add it to the target (usually the app target).
  3. Select your target, in the "General" Tab, find the "Frameworks, Libraries, and Embedded Content" section, set the Embed Without Signing to Kingfisher.

Documentation

Check the documentation and tutorials:

Migrating

If you are using an even earlier version, see the guides below to know the steps for migrating.

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.

Developments and Tests

Any contributing and pull requests are warmly welcome. However, before you plan to implement some features or try to fix an uncertain issue, it is recommended to open a discussion first. It would be appreciated if your pull requests could build with all tests green. :)

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?

Contact

Follow and contact me on Twitter or Sina Weibo. If you find an issue, open a ticket. Pull requests are warmly welcome as well.

Backers & Sponsors

Open-source projects cannot live long without your help. If you find Kingfisher to be useful, please consider supporting this project by becoming a sponsor. Your user icon or company logo shows up on my blog with a link to your home page.

Become a sponsor through GitHub Sponsors. :heart:

Special thanks to:

imgly

emergetools

License

Kingfisher is released under the MIT license. See LICENSE for details.

Kingfisher (onevcat/Kingfisher)

Searching Database…

24.4K ·GitHub
Kingfisher
What is this?A lightweight, pure-Swift library for downloading and caching images from the web in iOS, macOS, tvOS, watchOS and visionOS apps — you give it a URL and it fetches, caches and displays the image.
Is it a library I add to my Xcode project, or a separate app?It's a library you embed in your own app, nothing to run by itself. It hooks into views like UIImageView, NSImageView, UIButton and SwiftUI, so a remote image can be set with one line of code.
How do I add it to a project?Via Swift Package Manager in Xcode (File > Swift Packages > Add Package Dependency, choose 'Up to Next Major' at 8.0.0) or via CocoaPods. A pre-built Kingfisher.xcframework you drag into your target is also on the releases page.
Which OS and Swift versions does it need?Kingfisher 8.0 needs iOS 13+, macOS 10.15+, tvOS 13+, watchOS 6+ or visionOS 1+, with Swift 5.9+. SwiftUI use starts a bit higher, at iOS 14+ / macOS 11+.
Any pitfalls when installing the pre-built framework?One: after dragging Kingfisher.xcframework into your target, you must set it to 'Embed Without Signing' in the General tab, otherwise it won't be bundled with the app correctly.
Does it work with SwiftUI, or is it UIKit-only?Both. UIKit and AppKit views get a kf.setImage extension, SwiftUI gets KFImage, and the KF builder syntax carries over between them almost unchanged.
Is it free to use in my app?Yes — it's released under the MIT license, so it's free to use, including in commercial apps.
What happens the second time I load the same image?It's served instantly from cache. Kingfisher keeps downloads in a multi-layer hybrid cache — memory plus disk — and auto-reuses previously downloaded content to skip repeat network calls.
Can it do more than just download and show an image?Yes: it ships image processors and filters (downsampling to view size, rounding corners), placeholders and loading indicators, transition animations, prefetching, Low Data Mode support, and even downloading and caching of Live Photos.
Do I have to use the whole thing, or can I take just the caching part?The components are independent — you can use the downloader, the caching system and the image processors separately, and tune cache behavior with custom expiration dates and size limits.
Why the name Kingfisher?The logo is inspired by Tangram, the Chinese seven-piece dissection puzzle. The author insists the bird is a kingfisher rather than a swift — though some readers swear it's a pigeon.
What are similar projects?SDWebImage, AFNetworking, chameleon, FSCalendar, YYKit, SwiftyJSON, Hero, Spring
Which topics is it in?cache, cocoapods, swiftui, image, caching, xcode, apple, image-processing, swift, mobile, ios, framework
Creator
onevcat
Size
7.9 MB
Stars
24.4K
Updated
CommitOct 17Release8.14.0Oct 17
Age
11y
Commits · 90 Days