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 casts shadows.

Common

@Composable
fun Surface(
    modifier: Modifier = Modifier,
    shape: Shape = RectangleShape,
    color: Color = MaterialTheme.colors.surface,
    contentColor: Color = contentColorFor(color),
    border: BorderStroke? = null,
    elevation: Dp = 0.dp,
    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. A shadow is only displayed if the `elevation` 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
elevation	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`.
content	The content to be displayed on this Surface

Common

@ExperimentalMaterialApi
@Composable
fun Surface(
    onClick: () -> Unit,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    shape: Shape = RectangleShape,
    color: Color = MaterialTheme.colors.surface,
    contentColor: Color = contentColorFor(color),
    border: BorderStroke? = null,
    elevation: Dp = 0.dp,
    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 `elevation` 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
elevation	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

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

Parameters


selected	whether 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 selectable
shape	Defines the surface's shape as well its shadow. A shadow is only displayed if the `elevation` 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
elevation	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

@ExperimentalMaterialApi
@Composable
fun Surface(
    checked: Boolean,
    onCheckedChange: (Boolean) -> Unit,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    shape: Shape = RectangleShape,
    color: Color = MaterialTheme.colors.surface,
    contentColor: Color = contentColorFor(color),
    border: BorderStroke? = null,
    elevation: Dp = 0.dp,
    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 selectable
shape	Defines the surface's shape as well its shadow. A shadow is only displayed if the `elevation` 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
elevation	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

@Composable
fun SurfaceSample() {
    Surface(color = MaterialTheme.colors.background) { Text("Text color is `onBackground`") }
}

ClickableSurfaceSample

@OptIn(ExperimentalMaterialApi::class)
@Composable
fun ClickableSurfaceSample() {
    var count by remember { mutableStateOf(0) }
    Surface(onClick = { count++ }, color = MaterialTheme.colors.background) {
        Text("Clickable surface Text with `onBackground` color and count: $count")
    }
}

SelectableSurfaceSample

@OptIn(ExperimentalMaterialApi::class)
@Composable
fun SelectableSurfaceSample() {
    var selected by remember { mutableStateOf(false) }
    Surface(
        selected = selected,
        onClick = { selected = !selected },
        color = MaterialTheme.colors.background,
    ) {
        Text(text = if (selected) "Selected" else "Not Selected", textAlign = TextAlign.Center)
    }
}

ToggleableSurfaceSample

@OptIn(ExperimentalMaterialApi::class)
@Composable
fun ToggleableSurfaceSample() {
    var checked by remember { mutableStateOf(false) }
    Surface(
        checked = checked,
        onCheckedChange = { checked = !checked },
        color =
            if (checked) {
                MaterialTheme.colors.primary
            } else {
                MaterialTheme.colors.background
            },
    ) {
        Text(text = if (checked) "ON" else "OFF", textAlign = TextAlign.Center)
    }
}