New Compose Multiplatform components arrived on Composables UICheck it out →

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.

See the other overloads for clickable, selectable, and toggleable surfaces.

The Surface is responsible for:

  1. Clipping: Surface clips its children to the shape specified by [shape]

  2. Elevation: Surface draws a shadow to represent depth, where [elevation] represents the depth of this surface. If the passed [shape] is concave the shadow will not be drawn on Android versions less than 10.

  3. Borders: If [shape] has a border, then it will also be drawn.

  4. Background: Surface fills the shape specified by [shape] with the [color]. If [color] is [Colors.surface], the [ElevationOverlay] from [LocalElevationOverlay] will be used to apply an overlay - by default this will only occur in dark theme. The color of the overlay depends on the [elevation] of this Surface, and the [LocalAbsoluteElevation] set by any parent surfaces. This ensures that a Surface never appears to have a lower elevation overlay than its ancestors, by summing the elevation of all previous Surfaces.

  5. Content color: Surface uses [contentColor] to specify a preferred color for the content of this surface - this is used by the [Text] and [Icon] components as a default color.

  6. Blocking touch propagation behind the surface.

If no [contentColor] is set, this surface will try and match its background color to a color defined in the theme [Colors], and return the corresponding content color. For example, if the [color] of this surface is [Colors.surface], [contentColor] will be set to [Colors.onSurface]. If [color] is not part of the theme palette, [contentColor] will keep the same value set above this Surface.

Last updated:

Installation

dependencies {
   implementation("androidx.compose.material:material:1.7.0-beta03")
}

Overloads

@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

namedescription
modifierModifier to be applied to the layout corresponding to the surface
shapeDefines the surface's shape as well its shadow. A shadow is only displayed if the [elevation] is greater than zero.
colorThe background color. Use [Color.Transparent] to have no color.
contentColorThe 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.
borderOptional border to draw on top of the surface
elevationThe 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.
@Composable
@ExperimentalMaterialApi
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

namedescription
onClickcallback to be called when the surface is clicked
modifierModifier to be applied to the layout corresponding to the surface
enabledControls the enabled state of the surface. When false, this surface will not be clickable
shapeDefines the surface's shape as well its shadow. A shadow is only displayed if the [elevation] is greater than zero.
colorThe background color. Use [Color.Transparent] to have no color.
contentColorThe 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.
borderOptional border to draw on top of the surface
elevationThe 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.
interactionSourcean 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.
@Composable
@ExperimentalMaterialApi
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

namedescription
selectedwhether this Surface is selected
onClickcallback to be called when the surface is clicked
modifierModifier to be applied to the layout corresponding to the surface
enabledControls the enabled state of the surface. When false, this surface will not be selectable
shapeDefines the surface's shape as well its shadow. A shadow is only displayed if the [elevation] is greater than zero.
colorThe background color. Use [Color.Transparent] to have no color.
contentColorThe 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.
borderOptional border to draw on top of the surface
elevationThe 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.
interactionSourcean 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.
@Composable
@ExperimentalMaterialApi
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

namedescription
checkedwhether or not this Surface is toggled on or off
onCheckedChangecallback to be invoked when the toggleable Surface is clicked
modifierModifier to be applied to the layout corresponding to the surface
enabledControls the enabled state of the surface. When false, this surface will not be selectable
shapeDefines the surface's shape as well its shadow. A shadow is only displayed if the [elevation] is greater than zero.
colorThe background color. Use [Color.Transparent] to have no color.
contentColorThe 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.
borderOptional border to draw on top of the surface
elevationThe 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.
interactionSourcean 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.

Code Examples

SurfaceSample

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

ClickableSurfaceSample

@Composable
@Sampled
@OptIn(ExperimentalMaterialApi::class
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

@Composable
@Sampled
@OptIn(ExperimentalMaterialApi::class
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

@Composable
@Sampled
@OptIn(ExperimentalMaterialApi::class
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
        )
    }
}