Getting Started¶

Compose UI¶

A typical Compose UI project will want to import:

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

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

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:

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

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

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.

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

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

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.

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:

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:

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:

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.