Skip to content

Extending the Image Pipeline

Android supports many image formats out of the box, however there are also plenty of formats it does not (e.g. GIF, SVG, TIFF, etc.)

Fortunately, ImageLoaders support pluggable components to add new data types, new fetching behavior, new image encodings, or otherwise overwrite the base image loading behavior. Coil's image pipeline consists of three main parts: Mappers, Fetchers, and Decoders.

Custom components must be added to the ImageLoader when constructing it through its ComponentRegistry:

val imageLoader = ImageLoader(context) {
    componentRegistry {
        add(ItemMapper())
        add(ProtocolBufferFetcher())
        add(GifDecoder())
    }
}

Mappers

Mappers allow you to add support for custom data types. For instance, say we get this model from our server:

data class Item(
    val id: Int,
    val imageUrl: String,
    val price: Int,
    val weight: Double
)

We could write a custom mapper to map it to an HttpUrl:

class ItemMapper : Mapper<Item, HttpUrl> {
    override fun map(data: Item): HttpUrl = HttpUrl.get(data.imageUrl)
}

After registering it when constructing our ImageLoader (see above), we can safely load an Item:

imageView.loadAny(item)

loadAny is the type-unsafe version of load that accepts any data type.

If you want to know a Target's size when mapping an object, you can extend from Measured Mapper.

Note

Extending from Measured Mapper can prevent setting placeholders and or cached drawables synchronously, as they force Coil to wait for the target to be measured. Prefer extending Mapper if you do not need to know the Target's size.

See Mapper and Measured Mapper for more information.

Fetchers

Fetchers translate data into either a BufferedSource or a Drawable.

See Fetcher for more information.

Decoders

Decoders read a BufferedSource as input and return a Drawable. Use this interface to add support for custom file formats (e.g. GIF, SVG, TIFF, etc.).

See Decoder for more information.

Note

Decoders are responsible for closing the BufferedSource when finished. This allows custom decoders to return a Drawable while still reading the source. This can be useful to support file types such as progressive JPEG where there is incremental information to show.