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 Interactions 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 Interactions 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 Interactions 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

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)
    }
}

SurfaceSample

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

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)
    }
}