Coil has 8 artifacts published to
io.coil-kt:coil: The default artifact which depends on
io.coil-kt:coil-base, creates a singleton
ImageLoader, and includes the
io.coil-kt:coil-base: A subset of
io.coil-kt:coilwhich does not include the singleton
io.coil-kt:coil-compose: Includes support for Jetpack Compose.
io.coil-kt:coil-compose-base: A subset of
io.coil-kt:coil-composewhich does not include functions that depend on the singleton
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-bomallows you to depend on other Coil artifacts without specifying a version.
The default Coil artifact (
io.coil-kt:coil) includes the singleton
ImageLoader, which can be accessed using an extension function:
ImageLoader can be configured by implementing
ImageLoaderFactory on your
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.
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
ImageRequestto be executed asynchronously on a background thread.
execute: Executes the
ImageRequestin the current coroutine and returns an
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
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¶
io.coil-kt:coil artifact provides a set of
ImageView extension functions. Here's an example for loading a URL into an
The above call is equivalent to:
ImageView.load calls can be configured with an optional trailing lambda parameter:
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)
- Uri (
- @DrawableRes Int
Supported Image Formats¶
ImageLoaders support the following non-animated file types:
- 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-video: Static video frames from any video codec supported by Android
To preload an image into memory, enqueue or execute an
ImageRequest without a
To preload a network image only into the disk cache, disable the memory cache for the request:
ImageRequests will be automatically cancelled in the following cases:
ImageLoader.enqueue returns a Disposable, which can be used to dispose the request (which cancels it and frees its associated resources):