Anatomy of a theme in Compose

Themes in Jetpack Compose are made up of a number of lower-level constructs and related APIs. These can be seen in the source code of MaterialTheme and can also be applied in custom design systems.

Theme system classes

A theme is typically made up of a number of systems that group common visual and behavioral concepts. These systems can be modeled with classes which have theming values.

For example, MaterialTheme includes Colors (color system), Typography (typography system), and Shapes (shape system).

@Immutable
data class ColorSystem(
    val color: Color,
    val gradient: List<Color>
    /* ... */
)

@Immutable
data class TypographySystem(
    val fontFamily: FontFamily,
    val textStyle: TextStyle
)
/* ... */

@Immutable
data class CustomSystem(
    val value1: Int,
    val value2: String
    /* ... */
)

/* ... */

Theme system composition locals

Theme system classes are implicitly provided to the composition tree as CompositionLocal instances. This allows theming values to be statically referenced in composable functions.

To learn more about CompositionLocal, check out the Locally scoped data with CompositionLocal guide.

val LocalColorSystem = staticCompositionLocalOf {
    ColorSystem(
        color = Color.Unspecified,
        gradient = emptyList()
    )
}

val LocalTypographySystem = staticCompositionLocalOf {
    TypographySystem(
        fontFamily = FontFamily.Default,
        textStyle = TextStyle.Default
    )
}

val LocalCustomSystem = staticCompositionLocalOf {
    CustomSystem(
        value1 = 0,
        value2 = ""
    )
}

/* ... */

Theme function

The theme function is the entry point and primary API. It constructs instances of the theme system CompositionLocals — using real values any logic required — that are provided to the composition tree with CompositionLocalProvider. The content parameter allows nested composables to access theming values relative to the hierarchy.

@Composable
fun Theme(
    /* ... */
    content: @Composable () -> Unit
) {
    val colorSystem = ColorSystem(
        color = Color(0xFF3DDC84),
        gradient = listOf(Color.White, Color(0xFFD7EFFF))
    )
    val typographySystem = TypographySystem(
        fontFamily = FontFamily.Monospace,
        textStyle = TextStyle(fontSize = 18.sp)
    )
    val customSystem = CustomSystem(
        value1 = 1000,
        value2 = "Custom system"
    )
    /* ... */
    CompositionLocalProvider(
        LocalColorSystem provides colorSystem,
        LocalTypographySystem provides typographySystem,
        LocalCustomSystem provides customSystem,
        /* ... */
        content = content
    )
}

Theme object

Accessing theme systems is done via an object with convenience properties. For consistency, the object tends to be named the same as the theme function. The properties simply get the current composition local.

// Use with eg. Theme.colorSystem.color
object Theme {
    val colorSystem: ColorSystem
        @Composable
        get() = LocalColorSystem.current
    val typographySystem: TypographySystem
        @Composable
        get() = LocalTypographySystem.current
    val customSystem: CustomSystem
        @Composable
        get() = LocalCustomSystem.current
    /* ... */
}