Surface

Composable Component

Material surface is the central metaphor in material design. Each surface exists at a given elevation, which influences how that piece of surface visually relates to other surfaces and how that surface is modified by tonal variance.

Common

@Composable
fun Surface(
    modifier: Modifier = Modifier,
    shape: Shape = RectangleShape,
    color: Color = MaterialTheme.colorScheme.surface,
    contentColor: Color = contentColorFor(color),
    tonalElevation: Dp = 0.dp,
    shadowElevation: Dp = 0.dp,
    border: BorderStroke? = null,
    content: @Composable () -> Unit,
)

Parameters


modifier	Modifier to be applied to the layout corresponding to the surface
shape	Defines the surface's shape as well its shadow.
color	The background color. Use `Color.Transparent` to have no color.
contentColor	The preferred content color provided by this Surface to its children. Defaults to either the matching content color for `color`, or if `color` is not a color from the theme, this will keep the same value set above this Surface.
tonalElevation	When `color` is `ColorScheme.surface`, a higher the elevation will result in a darker color in light theme and lighter color in dark theme.
shadowElevation	The size of the shadow below the surface. To prevent shadow creep, only apply shadow elevation when absolutely necessary, such as when the surface requires visual separation from a patterned background. Note that It will not affect z index of the Surface. If you want to change the drawing order you can use `Modifier.zIndex`.
border	Optional border to draw on top of the surface
content	The content to be displayed on this Surface

Common

@Composable
fun Surface(
    onClick: () -> Unit,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    shape: Shape = RectangleShape,
    color: Color = MaterialTheme.colorScheme.surface,
    contentColor: Color = contentColorFor(color),
    tonalElevation: Dp = 0.dp,
    shadowElevation: Dp = 0.dp,
    border: BorderStroke? = null,
    interactionSource: MutableInteractionSource? = null,
    content: @Composable () -> Unit,
)

Parameters


onClick	callback to be called when the surface is clicked
modifier	Modifier to be applied to the layout corresponding to the surface
enabled	Controls the enabled state of the surface. When `false`, this surface will not be clickable
shape	Defines the surface's shape as well its shadow. A shadow is only displayed if the `tonalElevation` is greater than zero.
color	The background color. Use `Color.Transparent` to have no color.
contentColor	The preferred content color provided by this Surface to its children. Defaults to either the matching content color for `color`, or if `color` is not a color from the theme, this will keep the same value set above this Surface.
border	Optional border to draw on top of the surface
tonalElevation	When `color` is `ColorScheme.surface`, a higher the elevation will result in a darker color in light theme and lighter color in dark theme.
shadowElevation	The size of the shadow below the surface. Note that It will not affect z index of the Surface. If you want to change the drawing order you can use `Modifier.zIndex`.
interactionSource	an optional hoisted `MutableInteractionSource` for observing and emitting `Interaction`s for this surface. You can use this to change the surface's appearance or preview the surface in different states. Note that if `null` is provided, interactions will still happen internally.
content	The content to be displayed on this Surface

Common

@Composable
fun Surface(
    selected: Boolean,
    onClick: () -> Unit,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    shape: Shape = RectangleShape,
    color: Color = MaterialTheme.colorScheme.surface,
    contentColor: Color = contentColorFor(color),
    tonalElevation: Dp = 0.dp,
    shadowElevation: Dp = 0.dp,
    border: BorderStroke? = null,
    interactionSource: MutableInteractionSource? = null,
    content: @Composable () -> Unit,
)

Parameters


selected	whether or not this Surface is selected
onClick	callback to be called when the surface is clicked
modifier	Modifier to be applied to the layout corresponding to the surface
enabled	Controls the enabled state of the surface. When `false`, this surface will not be clickable
shape	Defines the surface's shape as well its shadow. A shadow is only displayed if the `tonalElevation` is greater than zero.
color	The background color. Use `Color.Transparent` to have no color.
contentColor	The preferred content color provided by this Surface to its children. Defaults to either the matching content color for `color`, or if `color` is not a color from the theme, this will keep the same value set above this Surface.
border	Optional border to draw on top of the surface
tonalElevation	When `color` is `ColorScheme.surface`, a higher the elevation will result in a darker color in light theme and lighter color in dark theme.
shadowElevation	The size of the shadow below the surface. Note that It will not affect z index of the Surface. If you want to change the drawing order you can use `Modifier.zIndex`.
interactionSource	an optional hoisted `MutableInteractionSource` for observing and emitting `Interaction`s for this surface. You can use this to change the surface's appearance or preview the surface in different states. Note that if `null` is provided, interactions will still happen internally.
content	The content to be displayed on this Surface

Common

@Composable
fun Surface(
    checked: Boolean,
    onCheckedChange: (Boolean) -> Unit,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    shape: Shape = RectangleShape,
    color: Color = MaterialTheme.colorScheme.surface,
    contentColor: Color = contentColorFor(color),
    tonalElevation: Dp = 0.dp,
    shadowElevation: Dp = 0.dp,
    border: BorderStroke? = null,
    interactionSource: MutableInteractionSource? = null,
    content: @Composable () -> Unit,
)

Parameters


checked	whether or not this Surface is toggled on or off
onCheckedChange	callback to be invoked when the toggleable Surface is clicked
modifier	Modifier to be applied to the layout corresponding to the surface
enabled	Controls the enabled state of the surface. When `false`, this surface will not be clickable
shape	Defines the surface's shape as well its shadow. A shadow is only displayed if the `tonalElevation` is greater than zero.
color	The background color. Use `Color.Transparent` to have no color.
contentColor	The preferred content color provided by this Surface to its children. Defaults to either the matching content color for `color`, or if `color` is not a color from the theme, this will keep the same value set above this Surface.
border	Optional border to draw on top of the surface
tonalElevation	When `color` is `ColorScheme.surface`, a higher the elevation will result in a darker color in light theme and lighter color in dark theme.
shadowElevation	The size of the shadow below the surface. Note that It will not affect z index of the Surface. If you want to change the drawing order you can use `Modifier.zIndex`.
interactionSource	an optional hoisted `MutableInteractionSource` for observing and emitting `Interaction`s for this surface. You can use this to change the surface's appearance or preview the surface in different states. Note that if `null` is provided, interactions will still happen internally.
content	The content to be displayed on this Surface

Code Examples

SurfaceSample

@Preview
@Composable
fun SurfaceSample() {
    Surface { Text("Text on Surface") }
}

ClickableSurfaceSample

@Preview
@Composable
fun ClickableSurfaceSample() {
    var count by remember { mutableStateOf(0) }
    Surface(onClick = { count++ }) { Text("Clickable Surface. Count: $count") }
}

SelectableSurfaceSample

@Preview
@Composable
fun SelectableSurfaceSample() {
    var selected by remember { mutableStateOf(false) }
    Surface(selected = selected, onClick = { selected = !selected }) {
        Text(text = if (selected) "Selected" else "Not Selected", textAlign = TextAlign.Center)
    }
}

ToggleableSurfaceSample

@Preview
@Composable
fun ToggleableSurfaceSample() {
    var checked by remember { mutableStateOf(false) }
    Surface(
        checked = checked,
        onCheckedChange = { checked = !checked },
        color =
            if (checked) {
                MaterialTheme.colorScheme.surfaceVariant
            } else {
                MaterialTheme.colorScheme.surface
            },
    ) {
        Text(text = if (checked) "ON" else "OFF", textAlign = TextAlign.Center)
    }
}