MaterialKolor Documentation

You can extract suitable colors from an ImageBitmap to use as seed colors for your theme. This is useful for generating themes based on user profile pictures or background images.

Using ImageBitmap extensions

fun calculateSeedColor(bitmap: ImageBitmap): Color {
    val suitableColors = bitmap.themeColors(fallback = Color.Blue)
    return suitableColors.first()
}

Using Compose functions

@Composable
fun DynamicTheme(image: ImageBitmap, content: @Composable () -> Unit) {
  val seedColor = rememberThemeColor(image, fallback = MaterialTheme.colorScheme.primary)

  DynamicMaterialTheme(
        seedColor = seedColor,
        content = content
    )
}

Warning: Extracting colors from an image can be slow. It is recommended to perform this eagerly or during a loading state rather than directly in the main UI loop to avoid performance issues.

You can add MaterialKolor to your project using Gradle. Depending on your project type, use one of the following configurations.

Multiplatform

Add the dependency to the commonMain source-set:

kotlin {
    sourceSets {
        commonMain {
            dependencies {
              implementation("com.materialkolor:material-kolor:5.0.0")
            }
        }
    }
}

Single Platform (Android)

Add the dependency to your app-level build.gradle.kts:

dependencies {
  implementation("com.materialkolor:material-kolor:5.0.0")
}

If you use Gradle Version Catalogs, add the following to your libs.versions.toml file:

[versions]
materialKolor = "5.0.0"

[libraries]
materialKolor = { module = "com.materialkolor:material-kolor", version.ref = "materialKolor" }

If you do not use Compose and do not need the extension functions, you can use the material-color-utilities artifact. This is a Kotlin Multiplatform port of Google's Material Color Utilities.

Add this to your Version Catalog:

[versions]
materialKolor = "5.0.0"

[libraries]
materialKolor-utilities = { module = "com.materialkolor:material-color-utilities", version.ref = "materialKolor" }

You can determine if a Color is warm or cold using the following extension functions:

val isWarm = MaterialTheme.colorScheme.primary.isWarm()
val isCold = MaterialTheme.colorScheme.primary.isCold()

Use lighten() and darken() to adjust the brightness of a color.

val newColor = MaterialTheme.colorScheme.primary.lighten(0.2f)

DynamicMaterialTheme is a Composable wrapper around MaterialTheme that automatically generates a ColorScheme using dynamicColorScheme(). You can enable animations by setting animate = true.

@Composable
fun MyTheme(
    seedColor: Color,
    isDark: Boolean = isSystemInDarkTheme(),
    content: @Composable () -> Unit
) {
    DynamicMaterialTheme(
        seedColor = seedColor,
        isDark = isDark,
        animate = true,
        content = content,
    )
}

DynamicMaterialExpressiveTheme is designed for the Material 3 Expressive design system. It defaults to PaletteStyle.Expressive and ColorSpec.SpecVersion.SPEC_2025 to create vibrant, playful color palettes where the source color's hue may not directly appear in the final theme.

Note: It is recommended to use SPEC_2025 and PaletteStyle.Expressive for optimal results.

@OptIn(ExperimentalMaterial3ExpressiveApi::class)
@Composable
fun MyExpressiveTheme(
  seedColor: Color,
  isDark: Boolean = isSystemInDarkTheme(),
  content: @Composable () -> Unit
) {
  DynamicMaterialExpressiveTheme(
    seedColor = seedColor,
    motionScheme = MotionScheme.expressive(),
    isDark = isDark,
    animate = true,
    content = content,
  )
}

To generate a custom ColorScheme from a seed color, use rememberDynamicColorScheme. You can customize the palette using PaletteStyle.

@Composable
fun MyTheme(
    seedColor: Color,
    isDark: Boolean = isSystemInDarkTheme(),
    content: @Composable () -> Unit
) {
    val colorScheme = rememberDynamicColorScheme(seedColor = seedColor, isDark = isDark)

    MaterialTheme(
        colors = colorScheme,
        content = content,
    )
}

To use a specific PaletteStyle (e.g., PaletteStyle.Expressive):

dynamicColorScheme(
    seedColor = seedColor,
    isDark = isDark,
  style = PaletteStyle.Expressive,
)

MaterialKolor provides extensions to harmonize colors with other colors or with the primary color of the current theme.

• Color.harmonize(otherColor: Color, matchSaturation: Boolean = false): Adjusts the color to harmonize with otherColor.
• Color.harmonizeWithPrimary(): A convenience function to harmonize with the theme's primary color.

// Harmonize with a specific color
val newColor = MaterialTheme.colorScheme.primary.harmonize(Color.Blue)

// Harmonize with the primary color
val newColor = Color.Blue.harmonizeWithPrimary()