![logo_image] Sketch Image Loader

![Platform][platform_image] [![License][license_image]][license_link] [![version_icon]][version_link] ![QQ Group][qq_group_image]

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}: [![Download][version_icon]][version_link] (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][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}")

// Supports BlurHash format image
implementation("io.github.panpf.sketch4:sketch-blurhash:${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}")

// Provides koin integration support, instead of sketch-compose and sketch-view, 
// and obtains Sketch instances from koin by default
implementation("io.github.panpf.sketch4:sketch-compose-koin:${LAST_VERSION}")
implementation("io.github.panpf.sketch4:sketch-view-koin:${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》][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][getting_started]
• [Register component][register_component]
• [Compose][compose]
• [Http: Load network images][http]
• [AnimatedImage: GIF、WEBP、HEIF][animated_image]
• [Resize: Modify the image size][resize]
• [Transformation: Transformation image][transformation]
• [Transition: Display images in cool transitions][transition]
• [StateImage: Placeholder and error images][state_image]
• [Thumbnail: Load low-resolution thumbnails first][thumbnail]
• [Listener: Listen for request status and download progress][listener]
• [DownloadCache: Understand download caching to avoid repeated downloads][download_cache]
• [ResultCache: Understand result caching to avoid duplicate conversions][result_cache]
• [MemoryCache: Understand memory caching to avoid repeated loading][memory_cache]
• [Fetcher: Learn about Fetcher and extend new URI types][fetcher]
• [Decoder: Understand the decoding process of Sketch][decoder]
• [Target: Apply the load results to the target][target]
• [SVG: Decode SVG still images][svg]
• [VideoFrames: Decode video fr