{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

ColorScheme

public final class 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.

To learn more about colors, see Material Design colors.

Summary

Public constructors

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

Public methods

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

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

final @NonNull Color

The background color that appears behind scrollable content.

final @NonNull Color

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

final @NonNull Color

The preferred tonal color of error containers.

final @NonNull Color

A color that contrasts well with inverseSurface.

final @NonNull 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.

final @NonNull Color

A color that contrasts sharply with surface.

final @NonNull Color

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

final @NonNull Color

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

final @NonNull Color

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

final @NonNull Color

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

final @NonNull Color

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

final @NonNull Color

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

final @NonNull Color

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

final @NonNull Color

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

final @NonNull Color

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

final @NonNull Color

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

final @NonNull Color

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

final @NonNull Color

Subtle color used for boundaries.

final @NonNull Color

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

final @NonNull Color

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

final @NonNull Color

The preferred tonal color of containers.

final @NonNull Color

Color of a scrim that obscures content.

final @NonNull Color

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

final @NonNull Color

A tonal color to be used in containers.

final @NonNull Color

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

final @NonNull Color

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

final @NonNull Color

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

final @NonNull Color

A surface variant for containers with higher emphasis than surfaceContainer.

final @NonNull Color

A surface variant for containers with higher emphasis than surfaceContainerHigh.

final @NonNull Color

A surface variant for containers with lower emphasis than surfaceContainer.

final @NonNull Color

A surface variant for containers with lower emphasis than surfaceContainerLow.

final @NonNull Color

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

final @NonNull Color

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

final @NonNull Color

Another option for a color with similar uses of surface.

final @NonNull 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.

final @NonNull Color

A tonal color to be used in containers.

@NonNull String

Extension functions

final @NonNull Color
ColorSchemeKt.contentColorFor(
    @NonNull ColorScheme receiver,
    @NonNull Color backgroundColor
)

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

final @NonNull Color
ColorSchemeKt.surfaceColorAtElevation(
    @NonNull ColorScheme receiver,
    @NonNull Dp elevation
)

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

Public constructors

ColorScheme

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

ColorScheme

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

Public methods

copy

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

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

getBackground

public final @NonNull Color getBackground()

The background color that appears behind scrollable content.

getError

public final @NonNull Color getError()

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

getErrorContainer

public final @NonNull Color getErrorContainer()

The preferred tonal color of error containers.

getInverseOnSurface

public final @NonNull Color getInverseOnSurface()

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

getInversePrimary

public final @NonNull Color getInversePrimary()

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

getInverseSurface

public final @NonNull Color getInverseSurface()

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

getOnBackground

public final @NonNull Color getOnBackground()

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

getOnError

public final @NonNull Color getOnError()

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

getOnErrorContainer

public final @NonNull Color getOnErrorContainer()

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

getOnPrimary

public final @NonNull Color getOnPrimary()

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

getOnPrimaryContainer

public final @NonNull Color getOnPrimaryContainer()

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

getOnSecondary

public final @NonNull Color getOnSecondary()

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

getOnSecondaryContainer

public final @NonNull Color getOnSecondaryContainer()

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

getOnSurface

public final @NonNull Color getOnSurface()

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

getOnSurfaceVariant

public final @NonNull Color getOnSurfaceVariant()

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

getOnTertiary

public final @NonNull Color getOnTertiary()

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

getOnTertiaryContainer

public final @NonNull Color getOnTertiaryContainer()

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

getOutline

public final @NonNull Color getOutline()

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

getOutlineVariant

public final @NonNull Color getOutlineVariant()

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

getPrimary

public final @NonNull Color getPrimary()

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

getPrimaryContainer

public final @NonNull Color getPrimaryContainer()

The preferred tonal color of containers.

getScrim

public final @NonNull Color getScrim()

Color of a scrim that obscures content.

getSecondary

public final @NonNull Color getSecondary()

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

getSecondaryContainer

public final @NonNull Color getSecondaryContainer()

A tonal color to be used in containers.

getSurface

public final @NonNull Color getSurface()

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

getSurfaceBright

public final @NonNull Color getSurfaceBright()

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

getSurfaceContainer

public final @NonNull Color getSurfaceContainer()

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

getSurfaceContainerHigh

public final @NonNull Color getSurfaceContainerHigh()

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

getSurfaceContainerHighest

public final @NonNull Color getSurfaceContainerHighest()

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

getSurfaceContainerLow

public final @NonNull Color getSurfaceContainerLow()

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

getSurfaceContainerLowest

public final @NonNull Color getSurfaceContainerLowest()

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

getSurfaceDim

public final @NonNull Color getSurfaceDim()

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

getSurfaceTint

public final @NonNull Color getSurfaceTint()

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.

getSurfaceVariant

public final @NonNull Color getSurfaceVariant()

Another option for a color with similar uses of surface.

getTertiary

public final @NonNull Color getTertiary()

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.

getTertiaryContainer

public final @NonNull Color getTertiaryContainer()

A tonal color to be used in containers.

toString

public @NonNull String toString()

Extension functions

ColorSchemeKt.contentColorFor

public final @NonNull Color ColorSchemeKt.contentColorFor(
    @NonNull ColorScheme receiver,
    @NonNull Color backgroundColor
)

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
@NonNull Color

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

See also
contentColorFor

ColorSchemeKt.surfaceColorAtElevation

public final @NonNull Color ColorSchemeKt.surfaceColorAtElevation(
    @NonNull ColorScheme receiver,
    @NonNull Dp elevation
)

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

Parameters
@NonNull Dp elevation

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

Returns
@NonNull Color

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