Coil has 9 artifacts published to mavenCentral()
:
io.coil-kt:coil
: The default artifact which depends onio.coil-kt:coil-base
, creates a singletonImageLoader
, and includes theImageView
extension functions.io.coil-kt:coil-base
: A subset ofio.coil-kt:coil
which does not include the singletonImageLoader
and theImageView
extension functions.io.coil-kt:coil-compose
: Includes support for Jetpack Compose.io.coil-kt:coil-compose-base
: A subset ofio.coil-kt:coil-compose
which does not include functions that depend on the singletonImageLoader
.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-test
: Includes classes to support testing withImageLoader
s. See Testing for more details.io.coil-kt:coil-bom
: Includes a bill of materials. Importingcoil-bom
allows you to depend on other Coil artifacts without specifying a version.
ImageLoader
s are service classes that execute ImageRequest
s. ImageLoader
s 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.
ImageRequest
s are value classes that are executed by ImageLoader
s. 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 theImageRequest
to be executed asynchronously on a background thread.execute
: Executes theImageRequest
in the current coroutine and returns anImageResult
.
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://example.com/image.jpg")
.target(imageView)
.build()
val disposable = imageLoader.enqueue(request)
// execute
val request = ImageRequest.Builder(context)
.data("https://example.com/image.jpg")
.build()
val result = imageLoader.execute(request)
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://example.com/image.jpg")
The above call is equivalent to:
val imageLoader = imageView.context.imageLoader
val request = ImageRequest.Builder(imageView.context)
.data("https://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://example.com/image.jpg") {
crossfade(true)
placeholder(R.drawable.image)
transformations(CircleCropTransformation())
}
See the docs here for more information.
The base data types that are supported by all ImageLoader
instances are:
- String
- HttpUrl
- Uri (
android.resource
,content
,file
,http
, andhttps
schemes) - File
- @DrawableRes Int
- Drawable
- Bitmap
- ByteArray
- ByteBuffer
All ImageLoader
s support the following non-animated file types:
- BMP
- JPEG
- PNG
- WebP
- HEIF (Android 8.0+)
- AVIF (Android 12.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
: SVGcoil-video
: Static video frames from any video codec supported by Android
To preload an image into memory, enqueue or execute an ImageRequest
without a Target
:
val request = ImageRequest.Builder(context)
.data("https://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:
val request = ImageRequest.Builder(context)
.data("https://example.com/image.jpg")
// Disable reading from/writing to the memory cache.
.memoryCachePolicy(CachePolicy.DISABLED)
// Set a custom `Decoder.Factory` that skips the decoding step.
.decoderFactory { _, _, _ ->
Decoder { DecodeResult(ColorDrawable(Color.BLACK), false) }
}
.build()
imageLoader.enqueue(request)
ImageRequest
s will be automatically cancelled in the following cases:
request.lifecycle
reaches theDESTROYED
state.request.target
is aViewTarget
and itsView
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://example.com/image.jpg")
// Cancel the request.
disposable.dispose()