ColorScheme


A color scheme holds all the named color parameters for a MaterialTheme.

Color schemes are designed to be harmonious, ensure accessible text, and distinguish UI elements and surfaces from one another. There are two built-in baseline schemes, lightColorScheme and a darkColorScheme, that can be used as-is or customized.

The Material color system and custom schemes provide default values for color as a starting point for customization.

Example of extending color scheme, including implementing Fixed Accent colors:

import androidx.compose.foundation.isSystemInDarkTheme
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.darkColorScheme
import androidx.compose.material3.lightColorScheme
import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.compositionLocalOf
import androidx.compose.ui.graphics.Color

data class FixedAccentColors(
    val primaryFixed: Color,
    val onPrimaryFixed: Color,
    val secondaryFixed: Color,
    val onSecondaryFixed: Color,
    val tertiaryFixed: Color,
    val onTertiaryFixed: Color,
    val primaryFixedDim: Color,
    val secondaryFixedDim: Color,
    val tertiaryFixedDim: Color,
)
val material3LightColors = lightColorScheme()
val material3DarkColors = darkColorScheme()
fun getFixedAccentColors() = FixedAccentColors(
    primaryFixed = material3LightColors.primaryContainer,
    onPrimaryFixed = material3LightColors.onPrimaryContainer,
    secondaryFixed = material3LightColors.secondaryContainer,
    onSecondaryFixed = material3LightColors.onSecondaryContainer,
    tertiaryFixed = material3LightColors.tertiaryContainer,
    onTertiaryFixed = material3LightColors.onTertiaryContainer,
    primaryFixedDim = material3DarkColors.primary,
    secondaryFixedDim = material3DarkColors.secondary,
    tertiaryFixedDim = material3DarkColors.tertiary
)
val LocalFixedAccentColors = compositionLocalOf { getFixedAccentColors() }

@Composable
fun MyMaterialTheme(
    fixedAccentColors: FixedAccentColors = LocalFixedAccentColors.current,
    content: @Composable () -> Unit
) {
    MaterialTheme(
        colorScheme = if (isSystemInDarkTheme()) material3DarkColors else material3LightColors
    ) {
        CompositionLocalProvider(LocalFixedAccentColors provides fixedAccentColors) {
            // Content has access to fixedAccentColors in both light and dark theme.
            content()
        }
    }
}

To learn more about colors, see Material Design colors.

Summary

Public constructors

ColorScheme(
    primary: Color,
    onPrimary: Color,
    primaryContainer: Color,
    onPrimaryContainer: Color,
    inversePrimary: Color,
    secondary: Color,
    onSecondary: Color,
    secondaryContainer: Color,
    onSecondaryContainer: Color,
    tertiary: Color,
    onTertiary: Color,
    tertiaryContainer: Color,
    onTertiaryContainer: Color,
    background: Color,
    onBackground: Color,
    surface: Color,
    onSurface: Color,
    surfaceVariant: Color,
    onSurfaceVariant: Color,
    surfaceTint: Color,
    inverseSurface: Color,
    inverseOnSurface: Color,
    error: Color,
    onError: Color,
    errorContainer: Color,
    onErrorContainer: Color,
    outline: Color,
    outlineVariant: Color,
    scrim: Color
)
Cmn
ColorScheme(
    primary: Color,
    onPrimary: Color,
    primaryContainer: Color,
    onPrimaryContainer: Color,
    inversePrimary: Color,
    secondary: Color,
    onSecondary: Color,
    secondaryContainer: Color,
    onSecondaryContainer: Color,
    tertiary: Color,
    onTertiary: Color,
    tertiaryContainer: Color,
    onTertiaryContainer: Color,
    background: Color,
    onBackground: Color,
    surface: Color,
    onSurface: Color,
    surfaceVariant: Color,
    onSurfaceVariant: Color,
    surfaceTint: Color,
    inverseSurface: Color,
    inverseOnSurface: Color,
    error: Color,
    onError: Color,
    errorContainer: Color,
    onErrorContainer: Color,
    outline: Color,
    outlineVariant: Color,
    scrim: Color,
    surfaceBright: Color,
    surfaceDim: Color,
    surfaceContainer: Color,
    surfaceContainerHigh: Color,
    surfaceContainerHighest: Color,
    surfaceContainerLow: Color,
    surfaceContainerLowest: Color
)
Cmn

Public functions

ColorScheme
copy(
    primary: Color,
    onPrimary: Color,
    primaryContainer: Color,
    onPrimaryContainer: Color,
    inversePrimary: Color,
    secondary: Color,
    onSecondary: Color,
    secondaryContainer: Color,
    onSecondaryContainer: Color,
    tertiary: Color,
    onTertiary: Color,
    tertiaryContainer: Color,
    onTertiaryContainer: Color,
    background: Color,
    onBackground: Color,
    surface: Color,
    onSurface: Color,
    surfaceVariant: Color,
    onSurfaceVariant: Color,
    surfaceTint: Color,
    inverseSurface: Color,
    inverseOnSurface: Color,
    error: Color,
    onError: Color,
    errorContainer: Color,
    onErrorContainer: Color,
    outline: Color,
    outlineVariant: Color,
    scrim: Color,
    surfaceBright: Color,
    surfaceDim: Color,
    surfaceContainer: Color,
    surfaceContainerHigh: Color,
    surfaceContainerHighest: Color,
    surfaceContainerLow: Color,
    surfaceContainerLowest: Color
)

Returns a copy of this ColorScheme, optionally overriding some of the values.

Cmn
open String
Cmn

Public properties

Color

The background color that appears behind scrollable content.

Cmn
Color

The error color is used to indicate errors in components, such as invalid text in a text field.

Cmn
Color

The preferred tonal color of error containers.

Cmn
Color

A color that contrasts well with inverseSurface.

Cmn
Color

Color to be used as a "primary" color in places where the inverse color scheme is needed, such as the button on a SnackBar.

Cmn
Color

A color that contrasts sharply with surface.

Cmn
Color

Color used for text and icons displayed on top of the background color.

Cmn
Color

Color used for text and icons displayed on top of the error color.

Cmn
Color

The color (and state variants) that should be used for content on top of errorContainer.

Cmn
Color

Color used for text and icons displayed on top of the primary color.

Cmn
Color

The color (and state variants) that should be used for content on top of primaryContainer.

Cmn
Color

Color used for text and icons displayed on top of the secondary color.

Cmn
Color

The color (and state variants) that should be used for content on top of secondaryContainer.

Cmn
Color

Color used for text and icons displayed on top of the surface color.

Cmn
Color

The color (and state variants) that can be used for content on top of surface.

Cmn
Color

Color used for text and icons displayed on top of the tertiary color.

Cmn
Color

The color (and state variants) that should be used for content on top of tertiaryContainer.

Cmn
Color

Subtle color used for boundaries.

Cmn
Color

Utility color used for boundaries for decorative elements when strong contrast is not required.

Cmn
Color

The primary color is the color displayed most frequently across your app’s screens and components.

Cmn
Color

The preferred tonal color of containers.

Cmn
Color

Color of a scrim that obscures content.

Cmn
Color

The secondary color provides more ways to accent and distinguish your product.

Cmn
Color

A tonal color to be used in containers.

Cmn
Color

The surface color that affect surfaces of components, such as cards, sheets, and menus.

Cmn
Color

A surface variant that is always brighter than surface, whether in light or dark mode.

Cmn
Color

A surface variant that affects containers of components, such as cards, sheets, and menus.

Cmn
Color

A surface variant for containers with higher emphasis than surfaceContainer.

Cmn
Color

A surface variant for containers with higher emphasis than surfaceContainerHigh.

Cmn
Color

A surface variant for containers with lower emphasis than surfaceContainer.

Cmn
Color

A surface variant for containers with lower emphasis than surfaceContainerLow.

Cmn
Color

A surface variant that is always dimmer than surface, whether in light or dark mode.

Cmn
Color

This color will be used by components that apply tonal elevation and is applied on top of surface.

Cmn
Color

Another option for a color with similar uses of surface.

Cmn
Color

The tertiary color that can be used to balance primary and secondary colors, or bring heightened attention to an element such as an input field.

Cmn
Color

A tonal color to be used in containers.

Cmn

Extension functions

Color
ColorScheme.contentColorFor(backgroundColor: Color)

The Material color system contains pairs of colors that are typically used for the background and content color inside a component.

Cmn
Color

Computes the surface tonal color at different elevation levels e.g. surface1 through surface5.

Cmn

Public constructors

ColorScheme

ColorScheme(
    primary: Color,
    onPrimary: Color,
    primaryContainer: Color,
    onPrimaryContainer: Color,
    inversePrimary: Color,
    secondary: Color,
    onSecondary: Color,
    secondaryContainer: Color,
    onSecondaryContainer: Color,
    tertiary: Color,
    onTertiary: Color,
    tertiaryContainer: Color,
    onTertiaryContainer: Color,
    background: Color,
    onBackground: Color,
    surface: Color,
    onSurface: Color,
    surfaceVariant: Color,
    onSurfaceVariant: Color,
    surfaceTint: Color,
    inverseSurface: Color,
    inverseOnSurface: Color,
    error: Color,
    onError: Color,
    errorContainer: Color,
    onErrorContainer: Color,
    outline: Color,
    outlineVariant: Color,
    scrim: Color
)

ColorScheme

ColorScheme(
    primary: Color,
    onPrimary: Color,
    primaryContainer: Color,
    onPrimaryContainer: Color,
    inversePrimary: Color,
    secondary: Color,
    onSecondary: Color,
    secondaryContainer: Color,
    onSecondaryContainer: Color,
    tertiary: Color,
    onTertiary: Color,
    tertiaryContainer: Color,
    onTertiaryContainer: Color,
    background: Color,
    onBackground: Color,
    surface: Color,
    onSurface: Color,
    surfaceVariant: Color,
    onSurfaceVariant: Color,
    surfaceTint: Color,
    inverseSurface: Color,
    inverseOnSurface: Color,
    error: Color,
    onError: Color,
    errorContainer: Color,
    onErrorContainer: Color,
    outline: Color,
    outlineVariant: Color,
    scrim: Color,
    surfaceBright: Color,
    surfaceDim: Color,
    surfaceContainer: Color,
    surfaceContainerHigh: Color,
    surfaceContainerHighest: Color,
    surfaceContainerLow: Color,
    surfaceContainerLowest: Color
)

Public functions

copy

fun copy(
    primary: Color = this.primary,
    onPrimary: Color = this.onPrimary,
    primaryContainer: Color = this.primaryContainer,
    onPrimaryContainer: Color = this.onPrimaryContainer,
    inversePrimary: Color = this.inversePrimary,
    secondary: Color = this.secondary,
    onSecondary: Color = this.onSecondary,
    secondaryContainer: Color = this.secondaryContainer,
    onSecondaryContainer: Color = this.onSecondaryContainer,
    tertiary: Color = this.tertiary,
    onTertiary: Color = this.onTertiary,
    tertiaryContainer: Color = this.tertiaryContainer,
    onTertiaryContainer: Color = this.onTertiaryContainer,
    background: Color = this.background,
    onBackground: Color = this.onBackground,
    surface: Color = this.surface,
    onSurface: Color = this.onSurface,
    surfaceVariant: Color = this.surfaceVariant,
    onSurfaceVariant: Color = this.onSurfaceVariant,
    surfaceTint: Color = this.surfaceTint,
    inverseSurface: Color = this.inverseSurface,
    inverseOnSurface: Color = this.inverseOnSurface,
    error: Color = this.error,
    onError: Color = this.onError,
    errorContainer: Color = this.errorContainer,
    onErrorContainer: Color = this.onErrorContainer,
    outline: Color = this.outline,
    outlineVariant: Color = this.outlineVariant,
    scrim: Color = this.scrim,
    surfaceBright: Color = this.surfaceBright,
    surfaceDim: Color = this.surfaceDim,
    surfaceContainer: Color = this.surfaceContainer,
    surfaceContainerHigh: Color = this.surfaceContainerHigh,
    surfaceContainerHighest: Color = this.surfaceContainerHighest,
    surfaceContainerLow: Color = this.surfaceContainerLow,
    surfaceContainerLowest: Color = this.surfaceContainerLowest
): ColorScheme

Returns a copy of this ColorScheme, optionally overriding some of the values.

toString

open fun toString(): String

Public properties

background

val backgroundColor

The background color that appears behind scrollable content.

error

val errorColor

The error color is used to indicate errors in components, such as invalid text in a text field.

errorContainer

val errorContainerColor

The preferred tonal color of error containers.

inverseOnSurface

val inverseOnSurfaceColor

A color that contrasts well with inverseSurface. Useful for content that sits on top of containers that are inverseSurface.

inversePrimary

val inversePrimaryColor

Color to be used as a "primary" color in places where the inverse color scheme is needed, such as the button on a SnackBar.

inverseSurface

val inverseSurfaceColor

A color that contrasts sharply with surface. Useful for surfaces that sit on top of other surfaces with surface color.

onBackground

val onBackgroundColor

Color used for text and icons displayed on top of the background color.

onError

val onErrorColor

Color used for text and icons displayed on top of the error color.

onErrorContainer

val onErrorContainerColor

The color (and state variants) that should be used for content on top of errorContainer.

onPrimary

val onPrimaryColor

Color used for text and icons displayed on top of the primary color.

onPrimaryContainer

val onPrimaryContainerColor

The color (and state variants) that should be used for content on top of primaryContainer.

onSecondary

val onSecondaryColor

Color used for text and icons displayed on top of the secondary color.

onSecondaryContainer

val onSecondaryContainerColor

The color (and state variants) that should be used for content on top of secondaryContainer.

onSurface

val onSurfaceColor

Color used for text and icons displayed on top of the surface color.

onSurfaceVariant

val onSurfaceVariantColor

The color (and state variants) that can be used for content on top of surface.

onTertiary

val onTertiaryColor

Color used for text and icons displayed on top of the tertiary color.

onTertiaryContainer

val onTertiaryContainerColor

The color (and state variants) that should be used for content on top of tertiaryContainer.

outline

val outlineColor

Subtle color used for boundaries. Outline color role adds contrast for accessibility purposes.

outlineVariant

val outlineVariantColor

Utility color used for boundaries for decorative elements when strong contrast is not required.

primary

val primaryColor

The primary color is the color displayed most frequently across your app’s screens and components.

primaryContainer

val primaryContainerColor

The preferred tonal color of containers.

scrim

val scrimColor

Color of a scrim that obscures content.

secondary

val secondaryColor

The secondary color provides more ways to accent and distinguish your product. Secondary colors are best for:

  • Floating action buttons

  • Selection controls, like checkboxes and radio buttons

  • Highlighting selected text

  • Links and headlines

secondaryContainer

val secondaryContainerColor

A tonal color to be used in containers.

surface

val surfaceColor

The surface color that affect surfaces of components, such as cards, sheets, and menus.

surfaceBright

val surfaceBrightColor

A surface variant that is always brighter than surface, whether in light or dark mode.

surfaceContainer

val surfaceContainerColor

A surface variant that affects containers of components, such as cards, sheets, and menus.

surfaceContainerHigh

val surfaceContainerHighColor

A surface variant for containers with higher emphasis than surfaceContainer. Use this role for content which requires more emphasis than surfaceContainer.

surfaceContainerHighest

val surfaceContainerHighestColor

A surface variant for containers with higher emphasis than surfaceContainerHigh. Use this role for content which requires more emphasis than surfaceContainerHigh.

surfaceContainerLow

val surfaceContainerLowColor

A surface variant for containers with lower emphasis than surfaceContainer. Use this role for content which requires less emphasis than surfaceContainer.

surfaceContainerLowest

val surfaceContainerLowestColor

A surface variant for containers with lower emphasis than surfaceContainerLow. Use this role for content which requires less emphasis than surfaceContainerLow.

surfaceDim

val surfaceDimColor

A surface variant that is always dimmer than surface, whether in light or dark mode.

surfaceTint

val surfaceTintColor

This color will be used by components that apply tonal elevation and is applied on top of surface. The higher the elevation the more this color is used.

surfaceVariant

val surfaceVariantColor

Another option for a color with similar uses of surface.

tertiary

val tertiaryColor

The tertiary color that can be used to balance primary and secondary colors, or bring heightened attention to an element such as an input field.

tertiaryContainer

val tertiaryContainerColor

A tonal color to be used in containers.

Extension functions

contentColorFor

fun ColorScheme.contentColorFor(backgroundColor: Color): Color

The Material color system contains pairs of colors that are typically used for the background and content color inside a component. For example, a Button typically uses primary for its background, and onPrimary for the color of its content (usually text or iconography).

This function tries to match the provided backgroundColor to a 'background' color in this ColorScheme, and then will return the corresponding color used for content. For example, when backgroundColor is ColorScheme.primary, this will return ColorScheme.onPrimary.

If backgroundColor does not match a background color in the theme, this will return Color.Unspecified.

Returns
Color

the matching content color for backgroundColor. If backgroundColor is not present in the theme's ColorScheme, then returns Color.Unspecified.

See also
contentColorFor

surfaceColorAtElevation

fun ColorScheme.surfaceColorAtElevation(elevation: Dp): Color

Computes the surface tonal color at different elevation levels e.g. surface1 through surface5.

Parameters
elevation: Dp

Elevation value used to compute alpha of the color overlay layer.

Returns
Color

the ColorScheme.surface color with an alpha of the ColorScheme.surfaceTint color overlaid on top of it.