Skip to content

Coil for Jetpack Compose

Maven Central

This library provides easy-to-use Painter which can fetch and display images from external sources, such as network, using the Coil image loading library.

Coil logo

Info

If you're migrating from Accompanist 0.7.x or before, please read the migration documentation after reading this document.

rememberCoilPainter()

The primary API is via the rememberCoilPainter() function. The simplest usage is like so:

import androidx.compose.foundation.Image
import com.google.accompanist.coil.rememberCoilPainter

Image(
    painter = rememberCoilPainter("https://picsum.photos/300/300"),
    contentDescription = stringResource(R.string.image_content_desc),
    previewPlaceholder = R.drawable.placeholder,
)

This painter loads the data passed in, using Coil, and then draws the resulting image.

You can also customize the Coil ImageRequest through the requestBuilder parameter. This allows usage of things like (but not limited to) transformations:

import androidx.compose.foundation.Image
import com.google.accompanist.coil.rememberCoilPainter

Image(
    painter = rememberCoilPainter(
        request = "https://picsum.photos/300/300",
        requestBuilder = {
            transformations(CircleCropTransformation())
        },
    ),
    contentDescription = stringResource(R.string.image_content_desc),
)

Fade-in animation

This library has built-in support for animating loaded images in, using a fade-in animation.

A fadeIn: Boolean parameter is available on rememberCoilPainter() (default: false). When enabled, a default fade-in animation will be used when the image is successfully loaded:

import androidx.compose.foundation.Image
import com.google.accompanist.coil.rememberCoilPainter

Image(
    painter = rememberCoilPainter(
        "https://picsum.photos/300/300",
        fadeIn = true
    ),
    contentDescription = stringResource(R.string.image_content_desc),
)

Custom content

Some times you may wish to display alternative content whilst the image is loading, or an error has occurred. The painter returned from rememberCoilPainter() is an instance of LoadPainter, which is stateful and allows you to display different content as required:

val painter = rememberCoilPainter("https://picsum.photos/300/300")

Box {
    Image(
        painter = painter,
        contentDescription = stringResource(R.string.image_content_desc),
    )

    when (painter.loadState) {
        ImageLoadState.Loading -> {
            // Display a circular progress indicator whilst loading
            CircularProgressIndicator(Modifier.align(Alignment.Center))
        }
        is ImageLoadState.Error -> {
            // If you wish to display some content if the request fails
        }
    }
}

ImageLoadState has a number of different states, so tweak your logic to suit. You could also use a Crossfade() or any other custom animation.

Previews

To support Android Studio Composable Previews, you can provide a drawable resource ID via the previewPlaceholder parameter. That drawable will then be displayed when your content is displayed as a preview:

Image(
    painter = rememberCoilPainter(
        request = "https://picsum.photos/300/300",
        previewPlaceholder = R.drawable.placeholder,
    ),
    contentDescription = stringResource(R.string.image_content_desc),
)

If the referenced drawable is only used for the purposes of previewPlaceholders, it can be placed in the resources of your debug build variant For example: app/debug/res/drawable/. This allows the drawable to be only bundled in your debug builds, and not shipped to users of your release build.

GIFs

Accompanist Coil supports GIFs through Coil's own GIF support. Follow the setup instructions and it should just work.

Observing load state changes

To observe changes to the load state you can use snapshotFlow() to observe changes to painter.loadState, and then call your logic as necessary:

val painter = rememberCoilPainter("https://image.url")

LaunchedEffect(painter) {
    snapshotFlow { painter.loadState }
        .filter { it.isFinalState() }
        .collect { result ->
            // TODO do something with result
        }
}

Image(painter = painter)

Custom ImageLoader

If you wish to provide a default ImageLoader to use across all of your rememberCoilPainter() calls, we provide the LocalImageLoader composition local.

You can use it like so:

val imageLoader = ImageLoader.Builder(context)
    // customize the ImageLoader as needed
    .build()

CompositionLocalProvider(LocalImageLoader provides imageLoader) {
    // This will automatically use the value of LocalImageLoader
    Image(
        painter = rememberCoilPainter(...)
    )
}

For more information on composition locals, see here.

Download

Maven Central

repositories {
    mavenCentral()
}

dependencies {
    implementation "com.google.accompanist:accompanist-coil:<version>"
}

Snapshots of the development version are available in Sonatype's snapshots repository. These are updated on every commit.