skip to content

Material Theming

MaterialTheme's ColorScheme, Typography and Shapes, dynamic color, and CompositionLocals for custom tokens. It comes up when an existing design system has to survive the move to Compose.

on this pageshow

explore

questions

5

In Jetpack Compose Material 3, how does MaterialTheme supply colors, typography and shapes to components, and how should a composable read them?

level: juniorimportance: must knowfreq 72%

answer

  1. three subsystems, one wrapper
  2. values flow down implicitly
  3. the MaterialTheme object's getters
  4. readable only during composition

basics

~20 s

MaterialTheme takes a ColorScheme, a Typography and a Shapes and provides them to everything in its content. Material components use them as defaults, and your own composables read MaterialTheme.colorScheme, .typography and .shapes instead of hardcoding values.

solid answer

~40 s

`MaterialTheme(colorScheme, typography, shapes) { ... }` wraps the app's content and provides those three subsystems through composition locals, so any composable below reads `MaterialTheme.colorScheme.primary`, `MaterialTheme.typography.titleLarge` or `MaterialTheme.shapes.medium` at its own position. Material components such as `Button` and `Card` take their default colors, text styles and corner shapes from the same values, so changing the theme restyles them without touching call sites. A parameter you leave out inherits from an enclosing `MaterialTheme`, or falls back to Material's baseline defaults when there is none, so you can nest a second theme to override one subsystem for one screen. The getters are `@Composable`, so read them in the composable body, not in a click handler. Hardcoding `Color(0xFF...)` in a screen breaks dark theme and every later brand change.

go deeper

for a junior

Name the three subsystems MaterialTheme takes and show how a composable reads one value, such as MaterialTheme.colorScheme.primary, instead of a color literal.

for a middle

Explain that values travel through composition locals, that omitted parameters inherit from an enclosing theme, and why the getters only work during composition.

for a senior

Use nesting deliberately, for example a second MaterialTheme for one flow, and catch hardcoded literals and unthemed previews in review before they ship.

for a principal

Treat MaterialTheme as the contract between design and code: decide which roles the brand defines and keep screens reading roles, never literal values.

## What `MaterialTheme` is In Jetpack Compose, **`MaterialTheme`** is a composable that wraps part of the UI tree (usually the whole app, inside `setContent`) and provides the Material 3 theme to everything in its `content` lambda. It takes three main subsystems: - **`colorScheme: ColorScheme`**: the color roles, such as `primary`, `onPrimary`, `primaryContainer`, `surface`, `onSurface` and `error`. - **`typography: Typography`**: the type scale, `TextStyle`s named display, headline, title, body and label, each in large, medium and small. - **`shapes: Shapes`**: the corner scale, with sizes such as `extraSmall`, `small`, `medium`, `large` and `extraLarge`. Material components such as `Button`, `Card`, `TopAppBar` and `TextField` read their default container colors, text styles and corner shapes from these values. Change the theme once and every component that relies on its defaults follows, with no edits at the call sites. ## How values reach a composable `MaterialTheme` does not pass its values as parameters to each child. It provides them through **composition locals**, Compose's mechanism for passing data implicitly down the tree. Any composable below can read the value at its own position through the `MaterialTheme` object: ```kotlin @Composable fun BalanceCard(balance: String) { Card(shape = MaterialTheme.shapes.medium) { Text( text = balance, style = MaterialTheme.typography.headlineSmall, color = MaterialTheme.colorScheme.primary, ) } } ``` The getters `MaterialTheme.colorScheme`, `MaterialTheme.typography` and `MaterialTheme.shapes` are themselves `@Composable` (and `@ReadOnlyComposable`). That has a practical consequence: you can read them during composition, but not from an `onClick` lambda, a coroutine or a plain Kotlin function. Read the value in the composable body and pass it on if code outside composition needs it. `MaterialTheme` also provides `typography.bodyLarge` as the default text style, which is why a bare `Text("...")` inside the theme renders in the body-large style. | Subsystem | Built with | Read with | Typical use | |---|---|---|---| | Color | `lightColorScheme()`, `darkColorScheme()` | `MaterialTheme.colorScheme.primary` | container and content colors | | Type | `Typography(...)` | `MaterialTheme.typography.titleLarge` | `Text(style = ...)` | | Shape | `Shapes(...)` | `MaterialTheme.shapes.medium` | `Card(shape = ...)` | ## Nesting and inheritance Every parameter of `MaterialTheme` defaults to the **current** theme value. So: 1. A top-level `MaterialTheme(colorScheme = bankColors, typography = bankType, shapes = bankShapes)` sets the whole app. 2. A nested `MaterialTheme(shapes = squareShapes) { ... }` around one screen overrides only the shapes; that screen keeps the enclosing color scheme and typography. 3. With no `MaterialTheme` above it at all, a component falls back to Material's baseline defaults (the baseline light color scheme, the default type scale and default shapes), which is a common reason a preview looks "unbranded". ## Building the values You rarely type all the color roles by hand. `lightColorScheme(primary = ..., onPrimary = ...)` and `darkColorScheme(...)` take every role as a parameter with baseline defaults, so you override the roles your brand defines. Tooling such as the Material Theme Builder can generate the light and dark schemes from a few brand source colors. `Typography(...)` likewise has a default for each style, so you override only the ones you change; note that Material 3's `Typography` has **no `defaultFontFamily`** parameter (Material 2's had one), so a brand font is set on each `TextStyle`. `Shapes(...)` takes `CornerBasedShape`s such as `RoundedCornerShape(12.dp)` for each size. ## Putting it into an app A typical project wires the theme in four steps: 1. Define the brand values once, at file level: a light and a dark `ColorScheme`, a `Typography` and a `Shapes`. 2. Write an app theme composable, for example `BankTheme { ... }`, that chooses the color scheme and calls `MaterialTheme` with all three. 3. Call it at the root: `setContent { BankTheme { BankApp() } }`, so every screen sits inside it. 4. Wrap each preview in the same theme function, so previews show the brand rather than the baseline. Screens then never mention a hex value; a brand refresh becomes an edit to step 1. ## Mistakes interviewers listen for - **Hardcoding colors in screens**, for example `Color(0xFF0B5CAD)` in a `Text`. It ignores dark theme, dynamic color and the next brand refresh; read a role from `MaterialTheme.colorScheme` instead. - **Assuming only Material components can use the theme.** Your own composables read the same values through the `MaterialTheme` object. - **Expecting a nested `MaterialTheme` to reset what you did not pass.** It inherits the enclosing values. - **Reading the theme outside composition**, which does not compile because the getters are `@Composable`. - **Picking colors by hue rather than role.** Pair `primary` with `onPrimary` and `primaryContainer` with `onPrimaryContainer`; the "on" role is the one designed to be readable on its partner. A good junior answer names the three subsystems, shows one read through `MaterialTheme.colorScheme`, and explains that components pick up the same values as their defaults.

  • How do you apply a brand font to every Material 3 text style?
    Material 3's `Typography` has no `defaultFontFamily` parameter, unlike Material 2's. Set `fontFamily` on each `TextStyle` you use, typically by copying the defaults: build `Typography()` and call `copy(bodyLarge = base.bodyLarge.copy(fontFamily = brandFont), ...)` for each style, then pass the result to `MaterialTheme(typography = ...)`.
  • Why does a bare Text inside MaterialTheme render in the body-large style?
    `MaterialTheme` provides `typography.bodyLarge` as the current `LocalTextStyle`, and `Text`'s `style` parameter defaults to `LocalTextStyle.current`. Components such as buttons provide their own style to their content, which is why button labels use a label style instead.
  • Why does a composable preview look unbranded even though the app looks right?
    The preview renders the composable without the app's theme function around it, so Material components fall back to the baseline defaults. Wrap the preview content in the app theme, the same function `setContent` uses, to see brand colors, type and shapes.

  • My own composables cannot read MaterialTheme values; only Material components can.
  • Hardcoding brand Color literals in screens is fine once the palette is final.
  • A nested MaterialTheme resets every subsystem that I do not pass to it.
  • MaterialTheme.colorScheme can be read from a click handler or any Kotlin function.
  • Material 3 Typography has a defaultFontFamily parameter, just like Material 2's.
open as a page

In Jetpack Compose Material 3, how do you choose between dynamic color and a brand ColorScheme in light and dark, and what changes below Android 12?

level: middleimportance: must knowfreq 64%

basics

~20 s

The app's theme function picks the scheme: on Android 12 (API 31) and up, dynamicDarkColorScheme or dynamicLightColorScheme from the wallpaper if wanted; otherwise brand darkColorScheme or lightColorScheme, chosen with isSystemInDarkTheme(). Below Android 12 only the brand schemes exist.

open as a page

In Jetpack Compose Material 3, how does Text inside a Surface get a readable color without a color argument, and when does that fail?

level: middleimportance: should knowfreq 46%

basics

~20 s

Surface sets LocalContentColor to contentColorFor(its color), which maps a scheme background such as primary to its on-role, onPrimary. Text and Icon default to LocalContentColor. It fails when the background is not a scheme color, or is painted with Modifier.background.

open as a page

In Jetpack Compose, when you expose a custom spacing scale or brand colors through a CompositionLocal, how do you choose compositionLocalOf or staticCompositionLocalOf?

level: seniorimportance: should knowfreq 40%

basics

~20 s

compositionLocalOf tracks reads, so a new value recomposes only readers of current; staticCompositionLocalOf does not, so a change recomposes the provider's whole content. Use static for values that almost never change, such as a spacing scale, and compositionLocalOf for colors that change or animate.

open as a page

In Jetpack Compose, should a banking app with its own brand palette and spacing scale extend MaterialTheme, replace its subsystems, or build a fully custom design system?

level: principalimportance: should knowfreq 30%

basics

~20 s

Usually extend MaterialTheme: brand ColorScheme, Typography and Shapes, plus spacing and semantic colors in custom CompositionLocals, so Material components keep sensible defaults. Replacing subsystems or going fully custom means wrapping or rebuilding every component you use.

open as a page