Upgrading to Coil 3.x¶
Coil 3 is currently in alpha and its API and behaviour may change between releases. Coil 3 alphas are not guaranteed to be binary or source compatible with each other.
Coil 3 is the next major version of Coil that supports Compose Multiplatform and includes performance and API improvements. This document provides a high-level overview of the main changes from Coil 2 to Coil 3 and highlights any breaking or important changes. It does not cover every binary incompatible change or small behaviour change.
Using Coil 3 in a Compose Multiplatform project? Check out the
samples repository for examples.
Maven Coordinates and Package Name¶
Coil's Maven coordinates were updated to
io.coil-kt.coil3 and its package name was updated to
coil3. This allows Coil 3 to run side by side with Coil 2 without binary compatibility issues. For example,
io.coil-kt:coil:2.5.0 is now
coil-compose-base artifacts were renamed to
coil-compose-core respectively to align with the naming conventions used by Coroutines, Ktor, and AndroidX.
On Android, Coil uses the standard graphics classes to render images. On non-Android platforms, Coil uses Skiko to render images. Skiko is a set of Kotlin bindings that wrap the Skia graphics engine developed by Google.
As part of decoupling from the Android SDK, a number of API changes were made. Notably:
Drawablewas replaced with a custom
Image.asDrawable()to convert between the classes on Android. On non-Android platforms use
ImageAPI is experimental (especially on non-Android platforms) and is likely to change.
android.net.Uriclass was replaced a multiplatform
coil3.Uriclass. Any instances of
android.net.Urithat are used as
ImageRequest.datawill be mapped to
coil3.Uribefore being fetched/decoded.
- Usages of
Contextwere replaced with
PlatformContextis a type alias for
Contexton Android and can be accessed using
PlatformContext.INSTANCEon non-Android platforms.
Coilclass was renamed to
coil-video artifacts continue to be Android-only as they rely on specific Android decoders and libraries.
coil-compose artifact's APIs are mostly unchanged. You can continue using
rememberAsyncImagePainter the same way as with Coil 2.x. Additionally, this methods have been updated to be restartable and skippable which should improve their performance.
If you use Coil on a JVM (non-Android) platform, you'll need to add a dependency on a coroutines main dispatcher. On desktop you likely want to import
IMPORTANT Coil's network image support was extracted out of
coil-core. To load images from a network URL in Coil 3.0 you'll need to import a separate artifact, either:
coil-network-okhttpif you prefer using OkHttp. OkHttp is Android/JVM-only.
Check out the
samples repository for examples.
Cache-Control header support is no longer enabled by default. In subsequent alphas, it will be possible to re-enable it, but it will be opt-in.
NetworkFetcher.Factory now also supports custom
CacheStrategy implementations to allow custom cache resolution behaviour.
Parameters API was replaced by
Extras don't require a string key and instead rely on identity equality.
Extras don't support modifying the memory cache key. Instead, use
ImageRequest.memoryCacheKeyExtra if your extra affects the memory cache key.