Compose ImageLoader

The ImageLoader is the primary entry point for image loading. It provides an async method that takes an ImageRequest and returns a Flow<ImageAction>.

ImageAction is a sealed interface representing the lifecycle of an image load request. It is divided into three main states:

1. Loading: Indicates the request is in progress. This includes ImageEvent subtypes like Start, StartWithMemory, StartWithDisk, and StartWithFetch.
2. Success: Indicates the image was loaded successfully. Common implementations include ImageResult.OfBitmap, ImageResult.OfImage, and ImageResult.OfPainter.
3. Failure: Indicates an error occurred. It contains a Throwable via the error property. Common implementations include ImageResult.OfError and ImageResult.OfSource.

interface ImageLoader {
    fun async(request: ImageRequest): Flow<ImageAction>
}

sealed interface ImageAction {
    sealed interface Loading : ImageAction
    sealed interface Success : ImageAction
    sealed interface Failure : ImageAction {
        val error: Throwable
    }
}

Compose ImageLoader provides several ways to display images in Kotlin Multiplatform Compose applications. Depending on your version and desired level of control, you can use high-level components like AutoSizeImage and AutoSizeBox, or the lower-level rememberImagePainter API.

Option 1: Using AutoSizeImage (Recommended for 1.7.0+)

A high-level, convenient component for displaying images with automatic sizing.

Option 2: Using AutoSizeBox (Recommended for 1.7.0+)

A component that provides lifecycle actions (Success, Loading, Failure), allowing you to render custom UI (like loading spinners or error icons) based on the image state.

Option 3: Using rememberImagePainter

A lower-level approach for retrieving a Painter from a URL or resource, suitable for use with the standard Compose Image component.

@Composeable
fun Content() {
    // Option 1 on 1.7.0+
    AutoSizeImage(
        "https://...",
        contentDescription = "image",
    )

    // Option 2 on 1.7.0+
    AutoSizeBox("https://...") { action ->
        when (action) {
            is ImageAction.Success -> {
                Image(
                    rememberImageSuccessPainter(action),
                    contentDescription = "image",
                )
            }
            is ImageAction.Loading -> {}
            is ImageAction.Failure -> {}
        }
    }

    // Option 3
    Image(
        painter = rememberImagePainter("https://.."),
        contentDescription = "image",
    )
}

Add the core dependency to your commonMain sourceSet in build.gradle.kts. You can also add optional extensions for specific resource decoders or effects.

Core Dependency:

• io.github.qdsfdhvh:image-loader:1.10.0

Optional Extensions:

• Compose Multiplatform Resources Decoder: io.github.qdsfdhvh:image-loader-extension-compose-resources:1.10.0
• Moko Resources Decoder: io.github.qdsfdhvh:image-loader-extension-moko-resources:1.10.0
• Blur Interceptor (Bitmap only): io.github.qdsfdhvh:image-loader-extension-blur:1.10.0
• JVM ImageIO Decoder: io.github.qdsfdhvh:image-loader-extension-imageio:1.10.0 (add to jvmMain)

kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                api("io.github.qdsfdhvh:image-loader:1.10.0")
                // optional extensions
                api("io.github.qdsfdhvh:image-loader-extension-compose-resources:1.10.0")
                api("io.github.qdsfdhvh:image-loader-extension-moko-resources:1.10.0")
                api("io.github.qdsfdhvh:image-loader-extension-blur:1.10.0")
            }
        }
        val jvmMain by getting {
            dependencies {
                api("io.github.qdsfdhvh:image-loader-extension-imageio:1.10.0")
            }
        }
    }
}

To avoid unnecessary reloads and manage caching, create a custom ImageLoader and provide it to your UI tree using CompositionLocalProvider with LocalImageLoader.

There are three main ways to consume images, listed in order of recommended priority:

1. AutoSizeImage: High-level component (based on Modifier.Node).
2. AutoSizeBox: Provides lifecycle actions (Success, Loading, Failure).
3. rememberImagePainter: The standard painter-based approach.

Configuration is typically done per-platform (Android, JVM, iOS) to handle platform-specific contexts or file paths.

@Composable
fun Content() {
    CompositionLocalProvider(
        LocalImageLoader provides remember { generateImageLoader() },
    ) {
        // Option 1: Recommended
        AutoSizeImage(
            "https://...",
            contentDescription = "image",
        )

        // Option 2: For lifecycle handling
        AutoSizeBox("https://...") { action ->
            when (action) {
                is ImageAction.Success -> {
                    Image(
                        rememberImageSuccessPainter(action),
                        contentDescription = "image",
                    )
                }
                is ImageAction.Loading -> { /* Show loader */ }
                is ImageAction.Failure -> { /* Show error */ }
            }
        }

        // Option 3: Standard
        Image(
            painter = rememberImagePainter("https://.."),
            contentDescription = "image",
        )
    }
}

Compose ImageLoader provides several ways to display images depending on your Compose version and required level of control.

Recommended Priority:

1. AutoSizeImage: The simplest high-level component (available on 1.7.0+).
2. AutoSizeBox: Provides lifecycle hooks for Success, Loading, and Failure states (available on 1.7.0+).
3. rememberImagePainter: The standard painter-based approach.

Note: AutoSizeBox and AutoSizeImage are built using Modifier.Node for better performance. AutoSizeImage is essentially a convenience wrapper around AutoSizeBox + Painter.

// Option 1: Simplest (1.7.0+)
AutoSizeImage(
    "https://...",
    contentDescription = "image",
)

// Option 2: With state handling (1.7.0+)
AutoSizeBox("https://...") { action ->
    when (action) {
        is ImageAction.Success -> {
            Image(
                rememberImageSuccessPainter(action),
                contentDescription = "image",
            )
        }
        is ImageAction.Loading -> { /* Show loader */ }
        is ImageAction.Failure -> { /* Show error */ }
    }
}

// Option 3: Standard Painter
Image(
    painter = rememberImagePainter("https://.."),
    contentDescription = "image",
)