README.md

Jetpack Compose + Coil

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

CoilImage()

The primary API is via the CoilImage() functions. There are a number of function versions available.

The simplest usage is like so:

CoilImage(
    data = "https://picsum.photos/300/300"
)

This loads the data passed in with Coil, and then displays the resulting image using the standard Image composable.

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

CoilImage(
    data = "https://picsum.photos/300/300",
    requestBuilder = {
        transformations(CircleCropTransformation())
    },
)

It also provides optional content 'slots', allowing you to provide custom content to be displayed when the request is loading, and/or if the image request failed:

CoilImage(
    data = "https://picsum.photos/300/300",
    loading = {
        Box(Modifier.matchParentSize()) {
            CircularProgressIndicator(Modifier.align(Alignment.Center))
        }
    },
    error = {
        Image(asset = imageResource(R.drawable.ic_error))
    }
)

Fade-in animation

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

There are two ways to enable the animation:

fadeIn parameter

A fadeIn: Boolean parameter has been added to CoilImage (default: false). When enabled, a default fade-in animation will be used when the image is successfully loaded:

CoilImage(
    data = "https://picsum.photos/300/300",
    fadeIn = true
)

Custom content

If you need more control over the animation, or you want to provide custom layout for the loaded image, you can use the content composable version of CoilImage:

CoilImage(
    data = "https://picsum.photos/300/300",
) { imageState ->
    when (imageState) {
        is ImageLoadState.Success -> {
            MaterialLoadingImage(
                result = imageState,
                fadeInEnabled = true,
                fadeInDurationMs = 600,
            )
        }
        is ImageLoadState.Error -> /* TODO */
        ImageLoadState.Loading -> /* TODO */
        ImageLoadState.Empty -> /* TODO */
    }
}

GIFs

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

Custom ImageLoader

If you wish to provide a default ImageLoader to use across all of your CoilImage calls, we provide the AmbientImageLoader ambient. You can see it like so:

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

Providers(AmbientImageLoader provides imageLoader) {
    // This will automatically use the value of AmbientImageLoader
    CoilImage(
        data = ...
    )
}

Download

repositories {
    mavenCentral()
}

dependencies {
    implementation "dev.chrisbanes.accompanist:accompanist-coil:<version>"
}

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

What's the goal of the library?

Eventually the goal is to upstream all of this functionality back to Coil. Jetpack Compose's development is currently moving very fast, which means that there are frequent API changes between releases. For now, it makes sense to keep this as a seperately released library to track the latest Compose release.