Surface

The building block of every container: shape, color, border and elevation in one place.

Category: Layout and structure
API status: Stable
Compose APIs: Surface, MaterialTheme.colorScheme, MaterialTheme.shapes
Interactive page: https://m3e.ljzapps.app/#components/surface

When to use

Surface sets the content color from its background so text and icons stay readable, clips its content to the shape and draws a shadow. Most components are a Surface with a defined role.

Choose a color role rather than a custom color, and prefer tonal container roles to shadows for depth.

Playground

The interactive page has a playground with live property controls for this component and generated code.

Examples

Color roles

Surface(color = MaterialTheme.colorScheme.surfaceContainerLow, shape = MaterialTheme.shapes.large) {
    Text("Low", Modifier.padding(20.dp))
}
Surface(color = MaterialTheme.colorScheme.surfaceContainerHigh, shape = MaterialTheme.shapes.large) {
    Text("High", Modifier.padding(20.dp))
}
Surface(color = MaterialTheme.colorScheme.primaryContainer, shape = MaterialTheme.shapes.large) {
    Text("Primary container", Modifier.padding(20.dp))
}

Selectable

var selected by rememberSaveable { mutableStateOf(false) }

Surface(
    selected = selected,
    onClick = { selected = !selected },
    shape = MaterialTheme.shapes.large,
    color = if (selected) MaterialTheme.colorScheme.secondaryContainer else MaterialTheme.colorScheme.surfaceContainerLow,
) {
    Text(if (selected) "Selected" else "Tap to select", Modifier.padding(20.dp))
}

Parameters

Name	Type	Default	Description
`color`	`Color`	`colorScheme.surface`	Background. Content color is derived with contentColorFor.
`shape`	`Shape`	`RectangleShape`	Clip and background shape.
`tonalElevation / shadowElevation`	`Dp`	`0.dp`	Tonal tint and shadow.
`onClick / selected / checked`	`overloads`		Make the surface interactive.

Guidelines

Do:

Use container roles for grouping.
Keep shapes from the theme.

Don't:

Do not hardcode colors.
Do not stack more than two tonal levels.

Accessibility

Interactive surfaces expose a role. Set one when you use the click overload for a non-button purpose.