Skip to content

Getting Started

Artifacts

Coil has 8 artifacts published to mavenCentral():

  • io.coil-kt:coil: The default artifact which depends on io.coil-kt:coil-base, creates a singleton ImageLoader, and includes the ImageView extension functions.
  • io.coil-kt:coil-base: A subset of io.coil-kt:coil which does not include the singleton ImageLoader and the ImageView extension functions.
  • io.coil-kt:coil-compose: Includes support for Jetpack Compose.
  • io.coil-kt:coil-compose-base: A subset of io.coil-kt:coil-compose which does not include functions that depend on the singleton ImageLoader.
  • io.coil-kt:coil-gif: Includes two decoders to support decoding GIFs. See GIFs for more details.
  • io.coil-kt:coil-svg: Includes a decoder to support decoding SVGs. See SVGs for more details.
  • io.coil-kt: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:coil-bom: Includes a bill of materials. Importing coil-bom allows you to depend on other Coil artifacts without specifying a version.

Image Loaders

ImageLoaders are service classes that execute ImageRequests. ImageLoaders handle caching, data fetching, image decoding, request management, bitmap pooling, memory management, and more.

The default Coil artifact (io.coil-kt:coil) includes the singleton ImageLoader, which can be accessed using an extension function: context.imageLoader.

The singleton ImageLoader can be configured by implementing ImageLoaderFactory on your Application class:

class MyApplication : Application(), ImageLoaderFactory {

    override fun newImageLoader(): ImageLoader {
        return ImageLoader.Builder(this)
            .crossfade(true)
            .build()
    }
}

Implementing ImageLoaderFactory is optional. If you don't, Coil will lazily create an ImageLoader with the default values.

Check out the full documentation for more info.

Image Requests

ImageRequests are value classes that are executed by ImageLoaders. They describe where an image should be loaded from, how it should be loaded, and any extra parameters. An ImageLoader has two methods that can execute a request:

  • enqueue: Enqueues the ImageRequest to be executed asynchronously on a background thread.
  • execute: Executes the ImageRequest in the current coroutine and returns an ImageResult.

All requests should set data (i.e. url, uri, file, drawable resource, etc.). This is what the ImageLoader will use to decide where to fetch the image data from. If you do not set data, it will default to NullRequestData.

Additionally, you likely want to set a target when enqueuing a request. It's optional, but the target is what will receive the loaded placeholder/success/error drawables. Executed requests return an ImageResult which has the success/error drawable.

Here's an example:

// enqueue
val request = ImageRequest.Builder(context)
    .data("https://www.example.com/image.jpg")
    .target(imageView)
    .build()
val disposable = imageLoader.enqueue(request)

// execute
val request = ImageRequest.Builder(context)
    .data("https://www.example.com/image.jpg")
    .build()
val result = imageLoader.execute(request)

ImageView Extension Functions

The io.coil-kt:coil artifact provides a set of ImageView extension functions. Here's an example for loading a URL into an ImageView:

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

The above call is equivalent to:

val imageLoader = imageView.context.imageLoader
val request = ImageRequest.Builder(imageView.context)
    .data("https://www.example.com/image.jpg")
    .target(imageView)
    .build()
imageLoader.enqueue(request)

ImageView.load calls can be configured with an optional trailing lambda parameter:

imageView.load("https://www.example.com/image.jpg") {
    crossfade(true)
    placeholder(R.drawable.image)
    transformations(CircleCropTransformation())
}

See the docs here for more information.

Supported Data Types

The base data types that are supported by all ImageLoader instances are:

  • String (mapped to a Uri)
  • HttpUrl
  • Uri (android.resource, content, file, http, and https schemes)
  • File
  • @DrawableRes Int
  • Drawable
  • Bitmap
  • ByteArray
  • ByteBuffer

Supported Image Formats

All ImageLoaders support the following non-animated file types:

  • BMP
  • JPEG
  • PNG
  • WebP
  • HEIF (Android 8.0+)

Additionally, Coil has extension libraries for the following file types:

  • coil-gif: GIF, animated WebP (Android 9.0+), animated HEIF (Android 11.0+)
  • coil-svg: SVG
  • coil-video: Static video frames from any video codec supported by Android

Preloading

To preload an image into memory, enqueue or execute an ImageRequest without a Target:

val request = ImageRequest.Builder(context)
    .data("https://www.example.com/image.jpg")
    // Optional, but setting a ViewSizeResolver will conserve memory by limiting the size the image should be preloaded into memory at.
    .size(ViewSizeResolver(imageView))
    .build()
imageLoader.enqueue(request)

To preload a network image only into the disk cache, disable the memory cache for the request:

val request = ImageRequest.Builder(context)
    .data("https://www.example.com/image.jpg")
    .memoryCachePolicy(CachePolicy.DISABLED)
    .build()
imageLoader.enqueue(request)

Cancelling Requests

ImageRequests will be automatically cancelled in the following cases:

  • request.lifecycle reaches the DESTROYED state.
  • request.target is a ViewTarget and its View is detached.

Additionally, ImageLoader.enqueue returns a Disposable, which can be used to dispose the request (which cancels it and frees its associated resources):

val disposable = imageView.load("https://www.example.com/image.jpg")

// Cancel the request.
disposable.dispose()