# 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

```kotlin
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

```kotlin
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.

## Related components

- [Card](https://m3e.ljzapps.app/docs/components/card.md)
- [Scaffold](https://m3e.ljzapps.app/docs/components/scaffold.md)