Image loading with Coil: real-world lessons and examples

Introduction

By day 37 of your Modern Android journey, you've likely built Compose UIs that need to display images from network sources. Coil has become the de facto standard for image loading in the Kotlin ecosystem because it's lightweight, coroutine-native, and integrates seamlessly with Compose. In this article, we'll explore image loading with Coil: real-world lessons and examples drawn from production apps handling everything from e-commerce product catalogs to user avatars in social feeds.

We won't just show you the basics—we'll dig into the performance tradeoffs, caching strategies, and the subtle bugs that surface when you ship to millions of users.

AsyncImage Composable

The AsyncImage composable is Coil's primary tool in Compose. It handles the entire lifecycle: loading, caching, decoding, and rendering. Unlike Image, which requires a pre-loaded ImageBitmap, AsyncImage manages background work automatically.

Here's the simplest form:

AsyncImage(
    model = "https://api.example.com/images/product-123.jpg",
    contentDescription = "Product image",
    modifier = Modifier
        .size(200.dp)
        .clip(RoundedCornerShape(8.dp))
)

This works, but it's incomplete for production. Let's add lifecycle awareness:

AsyncImage(
    model = ImageRequest.Builder(LocalContext.current)
        .data("https://api.example.com/images/product-123.jpg")
        .crossfade(durationMillis = 300)
        .build(),
    contentDescription = "Product image",
    modifier = Modifier.size(200.dp),
    contentScale = ContentScale.Crop
)

The ImageRequest builder gives you fine-grained control. crossfade creates a smooth transition when the image loads—critical for perceived performance. ContentScale.Crop ensures the image fills the bounds without letterboxing.

A real-world scenario: in an e-commerce app, you're rendering a grid of 20 product images. Users scroll quickly. Without crossfade, each image pops in abruptly, creating visual jank. With it, the UX feels polished. The 300ms duration balances smoothness against delay.

One often-overlooked detail: AsyncImage recomposes when the model URL changes. If you're reusing a composable for different items, ensure your state management prevents unnecessary recompositions. Use a key:

LazyColumn {
    items(products, key = { it.id }) { product ->
        AsyncImage(
            model = product.imageUrl,
            contentDescription = product.name,
            modifier = Modifier.size(200.dp)
        )
    }
}

Memory and Disk Caching

Coil's caching is three-tiered: memory cache, disk cache, and network. Understanding when and why each layer activates is essential for controlling memory usage and reducing network calls.

By default, Coil caches everything in memory (for the app lifetime) and on disk (persistent across app restarts). For a typical app, this is sensible. But we've seen crashes in production where memory pressure forced OOM errors because caches weren't sized appropriately.

Configure the singleton ImageLoader at app startup:

val imageLoader = ImageLoader.Builder(context)
    .memoryCache {
        MemoryCache.Builder(context)
            .maxSizePercent(0.25)  // 25% of available heap
            .build()
    }
    .diskCache {
        DiskCache.Builder()
            .directory(context.cacheDir.resolve("image_cache"))
            .maxSizeBytes(100 * 1024 * 1024)  // 100 MB
            .build()
    }
    .build()

Coil.setImageLoader(imageLoader)

The 25% memory limit is a starting point. In a product-heavy e-commerce app we worked on, we reduced it to 15% after observing memory churn. Monitor your app's total memory footprint under realistic scroll patterns.

For disk cache, 100 MB accommodates hundreds of high-quality images. If your app serves thousands of images (like a travel platform), bump this to 500 MB or 1 GB—but verify disk space availability on target devices.

Sometimes you need to disable caching for specific requests—for example, when displaying time-sensitive data like inventory counts or live user locations:

AsyncImage(
    model = ImageRequest.Builder(context)
        .data(url)
        .memoryCachePolicy(CachePolicy.DISABLED)
        .diskCachePolicy(CachePolicy.DISABLED)
        .build(),
    contentDescription = "Live inventory status",
    modifier = Modifier.size(100.dp)
)

This forces a fresh network fetch every time, which is expensive—use sparingly.

Placeholders and Error Images

Users don't enjoy blank screens while images load. Placeholders bridge that gap. Error images handle network failures gracefully.

The lambda overload of AsyncImage gives you direct control:

AsyncImage(
    model = imageUrl,
    contentDescription = "User avatar",
    modifier = Modifier
        .size(48.dp)
        .clip(CircleShape),
    contentScale = ContentScale.Crop,
    painter = rememberAsyncImagePainter(
        model = ImageRequest.Builder(LocalContext.current)
            .data(imageUrl)
            .crossfade(enable = true)
            .placeholder(R.drawable.ic_placeholder_avatar)
            .error(R.drawable.ic_error_avatar)
            .build()
    )
)

But this approach mixes concerns—it's verbose and hard to reuse. Instead, extract into a custom composable:

@Composable
fun UserAvatar(
    imageUrl: String?,
    modifier: Modifier = Modifier,
    contentDescription: String? = null
) {
    if (imageUrl == null) {
        // No image URL provided; show default
        Box(
            modifier = modifier
                .clip(CircleShape)
                .background(Color.LightGray),
            contentAlignment = Alignment.Center
        ) {
            Icon(
                imageVector = Icons.Default.Person,
                contentDescription = contentDescription
            )
        }
    } else {
        AsyncImage(
            model = ImageRequest.Builder(LocalContext.current)
                .data(imageUrl)
                .crossfade(durationMillis = 300)
                .placeholder(colorResource(R.color.placeholder_gray))
                .error(R.drawable.ic_error_avatar)
                .build(),
            contentDescription = contentDescription,
            modifier = modifier
                .clip(CircleShape),
            contentScale = ContentScale.Crop
        )
    }
}

This approach centralizes avatar logic. A placeholder can be a simple color (lightweight, fast) or a drawable. We typically use a solid color to minimize APK size.

In a ride-hailing app we built, missing driver avatars were handled gracefully: the placeholder circle with an icon prevented layout thrashing. Error images kicked in only after a timeout, avoiding the impression that something is broken when the network is slow.

Resize to the Displayed Size

This is where many teams leave performance on the table. Coil can resize images before decoding, reducing memory overhead significantly. If your UI displays a 200×200 dp image, there's no point loading a 2000×2000 px image into memory.

Specify size in the ImageRequest:

AsyncImage(
    model = ImageRequest.Builder(context)
        .data(url)
        .size(Size.ORIGINAL)  // or Size(200, 200)
        .build(),
    contentDescription = "Product",
    modifier = Modifier.size(200.dp)
)

Size.ORIGINAL loads the full resolution—only use this for full-screen images or detail views. For grid items, be explicit:

val gridItemSizePx = with(LocalDensity.current) { 200.dp.toPx().toInt() }

AsyncImage(
    model = ImageRequest.Builder(context)
        .data(url)
        .size(gridItemSizePx, gridItemSizePx)
        .build(),
    contentDescription = "Grid item",
    modifier = Modifier.size(200.dp)
)

Better yet, use Coil's automatic sizing by omitting the size call entirely when the composable has fixed dimensions—Coil infers them:

AsyncImage(
    model = url,
    contentDescription = "Product",
    modifier = Modifier
        .width(200.dp)
        .heightIn(max = 300.dp),
    contentScale = ContentScale.Crop
)

In a travel app with hundreds of destination photos, explicit sizing cut memory consumption by 60% during scrolling. Network bandwidth also dropped because servers could serve appropriately-sized thumbnails.

Common Mistakes

• Creating a new ImageLoader per request: The singleton pattern is essential. Creating multiple ImageLoader instances defeats caching. Always use Coil.imageLoader or inject via dependency injection.
• Ignoring memory cache pressure: Setting cache limits too high causes OOM crashes. Monitor heap usage under realistic load (scrolling 100+ items) before shipping.
• Not disabling caching for dynamic content: If your app shows live data (prices, availability, user counts), failing to disable the disk cache means stale data persists across sessions.
• Oversized requests: Specifying Size.ORIGINAL for thumbnail grids wastes memory and bandwidth. Always resize to displayed size.
• Missing error handling: Users see "broken image" icons without context. Provide meaningful error images and consider retry logic for transient failures.
• Unconditional crossfade: Crossfade is visual candy, but it adds latency perception. Use it selectively—it's worth the 300ms for grids, less so for splash screens.

Key Takeaways

• AsyncImage with ImageRequest builder provides the control needed for production apps; always use it over the basic form.
• Configure memory and disk cache sizes at app startup based on your content volume and target device constraints.
• Disable caching explicitly for time-sensitive data; otherwise, Coil's defaults work well.
• Extract avatar, thumbnail, and detail image loading into reusable composables to centralize placeholder and error logic.
• Always resize images to their displayed size in the UI; Coil does this efficiently, and it's often the single biggest memory win.
• Use crossfade judiciously for visual polish without sacrificing perceived performance.
• Monitor actual memory and network usage under realistic scroll patterns; cache tuning is app-specific.