kmPalette

The Maven group has changed from com.kmpalette to com.materialkolor.palette. Update your libs.versions.toml or build.gradle.kts using the following mapping:

// Example: Updating Core dependency
implementation("com.materialkolor.palette:core:4.x.x")

For cross-platform support (Android, iOS, macOS (Apple Silicon), Desktop, JS, WASM), use PlatformFile from FileKit along with the provided composables.

Dominant Color

Use rememberPlatformFileDominantColorState to extract a single dominant color. You must provide defaultColor and defaultOnColor which are used until generation succeeds or if it fails.

Palette Generation

Use rememberPlatformFilePaletteState to generate a full palette. You can access swatches like vibrantSwatch from the palette property.

Error Handling

Monitor paletteState.state to handle the loading lifecycle and errors. The state can be null (nothing generated yet), PaletteResult.Loading, PaletteResult.Error (contains the cause), or PaletteResult.Success (contains the palette).

@Composable
fun MyComposable(file: PlatformFile) {
    val paletteState = rememberPlatformFilePaletteState()

    LaunchedEffect(file) {
        paletteState.generate(file)
    }

    val vibrant = paletteState.palette?.vibrantSwatch

    when (val state = paletteState.state) {
        null -> Unit // nothing generated yet
        PaletteResult.Loading -> CircularProgressIndicator()
        is PaletteResult.Error -> Text("Failed to read file: ${state.cause.message}")
        is PaletteResult.Success -> PaletteDisplay(state.palette)
    }
}

The library provides specialized composables for different input types. Each input type has a corresponding pair of Dominant Color and Palette composables.

¹ In com.kmpalette.extensions.painter.

Example: Using Network URL

@Composable
fun SomeComposable(url: Url) {
    val dominantColorState = rememberNetworkDominantColorState(
        defaultColor = MaterialTheme.colorScheme.primary,
        defaultOnColor = MaterialTheme.colorScheme.onPrimary,
    )
    LaunchedEffect(url) {
        dominantColorState.updateFrom(url)
    }

    Box(
        modifier = Modifier
            .width(200.dp)
            .height(100.dp)
            .background(dominantColorState.color)
    ) {
        Text("Some Text", color = dominantColorState.onColor)
    }
}

Version 4.0 introduces dedicated composable functions for different loader types, removing the need to manually create and pass loaders.

Note: Every dominant-color composable requires defaultColor and defaultOnColor parameters. Palette-state equivalents do not require these parameters.

Painter (Core)

Use rememberPainterPaletteState() and rememberPainterDominantColorState(). These are located in com.kmpalette.extensions.painter.

Compose Multiplatform Resources

Use rememberResourcePaletteState() and rememberResourceDominantColorState(). These are located in com.kmpalette.extensions.resource.

Base64

Use rememberBase64PaletteState() and rememberBase64DominantColorState().

Network

Use rememberNetworkPaletteState() and rememberNetworkDominantColorState(). The latter allows passing a custom httpClient.

// Painter Example
val paletteState = rememberPainterPaletteState()
LaunchedEffect(painter) {
    paletteState.generate(painter)
}

// Resource Example
val paletteState = rememberResourcePaletteState()
LaunchedEffect(Res.drawable.my_image) {
    paletteState.generate(Res.drawable.my_image)
}

// Network Example
val dominantColorState = rememberNetworkDominantColorState(
    defaultColor = Color.Black,
    defaultOnColor = Color.White,
    httpClient = myHttpClient
)
LaunchedEffect(url) {
    dominantColorState.updateFrom(url)
}

To extract a single dominant color and a contrasting text color (onColor), use rememberDominantColorState (for ImageBitmap) or rememberPainterDominantColorState (for Painter).

Important: These composables require defaultColor and defaultOnColor. These values are displayed while the generation is loading or if it fails. The library does not provide defaults to avoid making assumptions about your design system.

To filter which color is chosen as dominant, use the isSwatchValid lambda. Swatches are checked in descending population order; the first one satisfying the predicate is used.

@Composable
fun SomeComposable(bitmap: ImageBitmap) {
    val dominantColorState = rememberDominantColorState(
        defaultColor = Color.Black,
        defaultOnColor = Color.White,
        isSwatchValid = { swatch -> swatch.population > 100 },
    )
    LaunchedEffect(bitmap) {
        dominantColorState.updateFrom(bitmap)
    }

    Box(
        modifier = Modifier
            .width(200.dp)
            .height(100.dp)
            .background(dominantColorState.color)
    ) {
        Text("Some Text", color = dominantColorState.onColor)
    }
}