Sketch Image Loader

Translations: 简体中文

Sketch is an image loading library specially designed for Compose Multiplatform and Android View. It has the following features:

• Multiple sources: Supports loading images from multiple sources such as http, file, compose resource, android asset/content/resource, etc.
• Powerful functions: Supports three-level caching, automatically cancels requests, automatically adjusts image size, automatically rotates images according to Exif Orientation, etc.
• Rich functions: Supports Animated image, SVG images, Base64 images, and video frames
• Easy to expand: Supports expansion of various aspects such as caching, decoding, transformation, transition, placeholder, etc.
• Extended functions: Practical extensions such as pausing downloads when cellular data is provided, pausing loading during list scrolling, image type badges, download progress indicators, etc.
• Modern: Completely based on Kotlin and Kotlin coroutine design

Sample App

• For Android, iOS, desktop version, and web deployable packages, please go to the Releases page to download.
• Web example：https://panpf.github.io/sketch/app

Install

Published to mavenCentral

${LAST_VERSION}: (Not included 'v')

Compose Multiplatform:

Import the required Compose and network modules:

// Provides the core functions of Sketch as well as singletons and extension 
// functions that rely on singleton implementations
implementation("io.github.panpf.sketch4:sketch-compose:${LAST_VERSION}")

// Provides the ability to load network images
implementation("io.github.panpf.sketch4:sketch-http:${LAST_VERSION}")

Important

To improve the performance of compose, please copy compose_compiler_config.conf under the sketch-core module file to your project and configure it according to the Compose Stability Configuration documentation

Android View:

Import the required View and network modules:

// Provides the core functions of Sketch as well as singletons and extension 
// functions that rely on singleton implementations
implementation("io.github.panpf.sketch4:sketch-view:${LAST_VERSION}")

// Provides the ability to load network images
implementation("io.github.panpf.sketch4:sketch-http:${LAST_VERSION}")

Optional modules:

// Use Android or Skia's built-in decoder to decode gif animations and play them
implementation("io.github.panpf.sketch4:sketch-animated-gif:${LAST_VERSION}")

// [Android only] Use the GifDrawable of the android-gif-drawable library to decode and play gif animations
implementation("io.github.panpf.sketch4:sketch-animated-gif-koral:${LAST_VERSION}")

// [Android only] Android or Skia's built-in decoder decodes heif animations and plays them
implementation("io.github.panpf.sketch4:sketch-animated-heif:${LAST_VERSION}")

// Use Android or Skia's built-in decoder to decode webp animations and play them
implementation("io.github.panpf.sketch4:sketch-animated-webp:${LAST_VERSION}")

// Support accessing compose resources through uri or placeholder, fallback, error, etc.
implementation("io.github.panpf.sketch4:sketch-compose-resources:${LAST_VERSION}")
implementation("io.github.panpf.sketch4:sketch-extensions-compose-resources:${LAST_VERSION}")

// Provides practical functions such as download progress, image type icons, 
//  pausing loading during list scrolling, and saving cellular traffic.
implementation("io.github.panpf.sketch4:sketch-extensions-compose:${LAST_VERSION}")
implementation("io.github.panpf.sketch4:sketch-extensions-view:${LAST_VERSION}")

// [Android only] Support icon loading of apk files via file path 
implementation("io.github.panpf.sketch4:sketch-extensions-apkicon:${LAST_VERSION}")

// [Android only] Support loading icons of installed apps by package name and version code
implementation("io.github.panpf.sketch4:sketch-extensions-appicon:${LAST_VERSION}")

// [JVM only] Support using HttpURLConnection to access network images
implementation("io.github.panpf.sketch4:sketch-http-hurl:${LAST_VERSION}")

// [JVM only] Support using OkHttp to access network images
implementation("io.github.panpf.sketch4:sketch-http-okhttp:${LAST_VERSION}")

// Supports using ktor version 2.x to access network images
implementation("io.github.panpf.sketch4:sketch-http-ktor2:${LAST_VERSION}")

// Supports using ktor version 3.x to access network images
implementation("io.github.panpf.sketch4:sketch-http-ktor3:${LAST_VERSION}")

// Support SVG images
implementation("io.github.panpf.sketch4:sketch-svg:${LAST_VERSION}")

// [Android only] Use Android's built-in MediaMetadataRetriever class to decode video frames
implementation("io.github.panpf.sketch4:sketch-video:${LAST_VERSION}")

// [Android only] Decoding video frames using wseemann's FFmpegMediaMetadataRetriever library
implementation("io.github.panpf.sketch4:sketch-video-ffmpeg:${LAST_VERSION}")

Tip

• sketch-compose, sketch-view Modules all depend on the singleton provided by the sketch-singleton module. If you don’t need the singleton, you can directly rely on their *-core version.
• The sketch-http module depends on sketch-http-hurl on jvm platforms and sketch-http-ktor3 on non-jvm platforms.

Register component

Sketch supports automatic discovery and registration of Fetcher and Decoder components, which are implemented through ServiceLoader on the JVM platform and through the @EagerInitialization annotation on non-JVM platforms.

All built-in modules support automatic registration. If you want to disable automatic registration, please refer to the documentation for manual registration: 《Register component》

R8 / Proguard

1. Android, iOS, Web and other platforms do not need to configure any obfuscation rules
2. The following obfuscation rules are required for desktop platforms:

   # -------------------------- Sketch Privider ---------------------------- #
   -keep class * implements com.github.panpf.sketch.util.DecoderProvider { *; }
   -keep class * implements com.github.panpf.sketch.util.FetcherProvider { *; }
   

3. It may also be necessary to add obfuscation configurations to the indirect dependencies of three-party libraries such as Kotlin Coroutines, OkHttp, Okio

Quickly Started

Compose Multiplatform:

// val imageUri = "/Users/my/Downloads/image.jpg"
// val imageUri = file:///compose_resource/composeResources/com.github.panpf.sketch.sample.resources/files/sample.png
val imageUri = "https://www.sample.com/image.jpg"

AsyncImage(
    uri = imageUri,
    contentDescription = "photo"
)

AsyncImage(
    uri = imageUri,
    state = rememberAsyncImageState(ComposableImageOptions {
        placeholder(Res.drawable.placeholder)
        error(Res.drawable.error)
        crossfade()
        // There is a lot more...
    }),
    contentDescription = "photo"
)

AsyncImage(
    rqeuest = ComposableImageRequest(imageUri) {
        placeholder(Res.drawable.placeholder)
        error(Res.drawable.error)
        crossfade()
        // There is a lot more...
    },
    contentDescription = "photo"
)

Image(
    painter = rememberAsyncImagePainter(
        request = ComposableImageRequest(imageUri) {
            placeholder(Res.drawable.placeholder)
            error(Res.drawable.error)
            crossfade()
            // There is a lot more...
        }
    ),
    contentDescription = "photo"
)

Tip

placeholder(Res.drawable.placeholder) needs to import the sketch-compose-resources module

Android View:

// val imageUri = "/sdcard/download/image.jpg"
// val imageUri = "file:///android_asset/image.jpg"
// val imageUri = "content://media/external/images/media/88484"
val imageUri = "https://www.sample.com/image.jpg"

imageView.loadImage(imageUri)

imageView.loadImage(imageUri) {
    placeholder(R.drawable.placeholder)
    error(R.drawable.error)
    crossfade()
    // There is a lot more...
}

val request = ImageRequest(context, imageUri) {
    placeholder(R.drawable.placeholder)
    error(R.drawable.error)
    crossfade()
    target(imageView)
    // There is a lot more...
}
context.sketch.enqueue(request)

Documents

Basic functions:

• Get Started
• Register component
• Compose
• Http: Load network images
• AnimatedImage: GIF、WEBP、HEIF
• Resize: Modify the image size
• Transformation: Transformation image
• Transition: Display images in cool transitions
• StateImage: Placeholder and error images
• Listener: Listen for request status and download progress
• DownloadCache: Understand download caching to avoid repeated downloads
• ResultCache: Understand result caching to avoid duplicate conversions
• MemoryCache: Understand memory caching to avoid repeated loading
• Fetcher: Learn about Fetcher and extend new URI types
• Decoder: Understand the decoding process of Sketch
• Target: Apply the load results to the target
• SVG: Decode SVG still images
• VideoFrames: Decode video frames
• ExifOrientation: Correct the image orientation
• ImageOptions: Manage image configurations in a unified manner
• RequestInterceptor: Intercept ImageRequest
• DecodeInterceptor: Intercept the decoding process
• Preload images into memory
• Download images
• Lifecycle
• Log
• Migrate

Featured functions:

• SketchImageView: Configure the request through XML attributes
• Improve the clarity of long images in grid lists
• Displays the download progress
• Displays the image type corner
• Pause image downloads on cellular data to save data
• The list slides to pause the loading of images
• Displays an icon for an apk file or installed app

Change log

Please review the CHANGELOG.md file

Test Platform

• Android: Emulator; Arm64; API 21-34
• Desktop: macOS; 14.6.1; JDK 17
• iOS: iphone 16 simulator; iOS 18.1
• Web: Chrome; 130

Run Sample App

Prepare the environment:

1. Android Studio: Norwhal+ (2025.1.1+)
2. JDK: 17+
3. Use kdoctor to check the running environment and follow the prompts to install the required software
4. Android Studio installs the Kotlin Multiplatform plugin

Run the sample app:

1. Clone the project and open it using Android Studio
2. After synchronization is completed, the Kotlin Multiplatform plug-in will automatically create a running configuration for each platform.
3. Select the corresponding platform's running configuration, and then click Run

About version 4.0

• The maven groupId is upgraded to io.github.panpf.sketch4, so versions 2.* and 3.* will not prompt for upgrade
• Version 4.0 is specially built for Compose Multiplatform, so there are many breaking changes in the API, please upgrade with caution
• Version 4.0 has made a lot of simplifications and is much simpler than version 3.0, please check the update log for details
• Android minimum API raised to API 21
• Kotlin version upgraded to 2.0.0

Special thanks

• coil-kt/coil: Sketch uses some code from Coil, including framework, compose and sketch-animated movie part
• koral--/android-gif-drawable: animated-koralgif
• wseemann/FFmpegMediaMetadataRetriever: video-ffmpeg
• BigBadaboom/androidsvg: svg

My Projects

The following are my other open source projects. If you are interested, you can learn about them:

• zoomimage: Library for zoom images, supported Android View, Compose and Compose Multiplatform; supported double-click zoom, One or two fingers gesture zoom, single-finger drag, inertial sliding, positioning, rotation, super-large image subsampling and other functions.
• assembly-adapter: A library on Android that provides multi-type Item implementations for various adapters. Incidentally, it also provides the most powerful divider for RecyclerView.
• sticky-item-decoration: RecyclerView sticky item implementation

License

Apache 2.0. See the LICENSE file for details.