Getting Started

Compose UI

A typical Compose UI project will want to import:

kotlin

implementation("io.coil-kt.coil3:coil-compose:3.4.0")
implementation("io.coil-kt.coil3:coil-network-okhttp:3.4.0")

After that's imported you can load images from the network using AsyncImage:

kotlin

AsyncImage(
    model = "https://example.com/image.jpg",
    contentDescription = null,
)

!!! Note If you use Compose Multiplatform, you'll need to use Ktor instead of OkHttp. See here for how to do that.

Android Views

If you use Android Views instead of Compose UI import:

kotlin

implementation("io.coil-kt.coil3:coil:3.4.0")
implementation("io.coil-kt.coil3:coil-network-okhttp:3.4.0")

After that's imported you can load images from the network using the ImageView.load extension function:

kotlin

imageView.load("https://example.com/image.jpg")

Configuring the singleton ImageLoader

By default, Coil includes a singleton ImageLoader. The ImageLoader executes incoming ImageRequests by fetching, decoding, caching, and returning the result. You don't need to configure your ImageLoader; if you don't Coil will create the singleton ImageLoader with the default configuration.

You can configure it a number of ways (choose only one):

Call setSingletonImageLoaderFactory near the entrypoint to your app (the root @Composable of your app). This works best for Compose Multiplatform apps.

kotlin

setSingletonImageLoaderFactory { context ->
    ImageLoader.Builder(context)
        .crossfade(true)
        .build()
}

Implement SingletonImageLoader.Factory on your Application in Android. This works best for Android apps.

kotlin

class CustomApplication : Application(), SingletonImageLoader.Factory {
    override fun newImageLoader(context: Context): ImageLoader {
        return ImageLoader.Builder(context)
            .crossfade(true)
            .build()
    }
}

Call SingletonImageLoader.setSafe near the entrypoint to your app (e.g. in Application.onCreate on Android). This is the most flexible.

kotlin

SingletonImageLoader.setSafe { context ->
    ImageLoader.Builder(context)
        .crossfade(true)
        .build()
}

!!! Note If you are writing a library that depends on Coil you should NOT get/set the singleton ImageLoader. Instead, you should depend on io.coil-kt.coil3:coil-core, create your own ImageLoader, and pass it around manually. If you set the singleton ImageLoader in your library you could be overwriting the ImageLoader set by the app using your library if they also use Coil.

Images

To support multiplatform rendering, Coil 3.x uses a custom coil3.Image class. It replaces Android's Drawable, but is fully interoperable with it:

kotlin

val drawable = image.asDrawable(resources)
val image = drawable.asImage()

Coil also defines a coil3.Bitmap class, which is a type alias for android.graphics.Bitmap on Android or org.jetbrains.skia.Bitmap on non-Android platforms:

kotlin

val bitmap = image.toBitmap()
val image = bitmap.asImage()

It's also interoperable with Compose UI's Painter class. This extension function requires importing the coil-compose-core artifact:

kotlin

val painter = image.asPainter()

!!! Note Painters can't be converted to Images as painters can only be rendered inside a composition whereas Images must be able to be rendered on any Canvas.

Artifacts

Here's a list of the main artifacts Coil has published to mavenCentral():

io.coil-kt.coil3:coil: The default artifact which depends on io.coil-kt.coil3:coil-core. It includes a singleton ImageLoader and related extension functions.
io.coil-kt.coil3:coil-core: A subset of io.coil-kt.coil3:coil which does not include the singleton ImageLoader and related extension functions.
io.coil-kt.coil3:coil-compose: The default Compose UI artifact which depends on io.coil-kt.coil3:coil and io.coil-kt.coil3:coil-compose-core. It includes overloads for AsyncImage, rememberAsyncImagePainter, and SubcomposeAsyncImage that use the singleton ImageLoader.
io.coil-kt.coil3:coil-compose-core: A subset of io.coil-kt.coil3:coil-compose which does not include functions that depend on the singleton ImageLoader.
io.coil-kt.coil3:coil-network-okhttp: Includes support for fetching images from the network using OkHttp.
io.coil-kt.coil3:coil-network-ktor2: Includes support for fetching images from the network using Ktor 2.
io.coil-kt.coil3:coil-network-ktor3: Includes support for fetching images from the network using Ktor 3.
io.coil-kt.coil3:coil-network-cache-control: Includes support for respecting Cache-Control headers when fetching images from the network.
io.coil-kt.coil3:coil-gif: Includes two decoders to support decoding GIFs. See GIFs for more details.
io.coil-kt.coil3:coil-svg: Includes a decoder to support decoding SVGs. See SVGs for more details.
io.coil-kt.coil3:coil-video: Includes a decoder to support decoding frames from any of Android's supported video formats. See videos for more details.
io.coil-kt.coil3:coil-test: Includes classes to support testing. See testing for more details.
io.coil-kt.coil3:coil-bom: Includes a bill of materials. Importing coil-bom allows you to depend on other Coil artifacts without specifying a version.