Surface

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

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

SurfaceSample

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

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)
    }
}
View all →