Surface

@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
): Unit

Material Design 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.

import androidx.compose.material.MaterialTheme
import androidx.compose.material.Surface
import androidx.compose.material.Text

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

To modify these default style values used by text, use ProvideTextStyle or explicitly pass a new TextStyle to your text.

To manually retrieve the content color inside a surface, use LocalContentColor.

@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
): Unit

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.

This version of Surface is responsible for a click handling as well al everything else that a regular Surface does:

This clickable 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 convex 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. 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.

6. Click handling. This version of surface will react to the clicks, calling onClick lambda, updating the interactionSource when androidx.compose.foundation.interaction.PressInteraction occurs, and showing ripple indication in response to press events. If you don't need click handling, consider using the Surface function that doesn't require onClick param.

7. Semantics for clicks. Just like with Modifier.clickable, clickable version of Surface will produce semantics to indicate that it is clicked. No semantic role is set by default, you may specify one by passing a desired androidx.compose.ui.semantics.Role with a Modifier.semantics.

import androidx.compose.material.MaterialTheme
import androidx.compose.material.Surface
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

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

To modify these default style values used by text, use ProvideTextStyle or explicitly pass a new TextStyle to your text.

To manually retrieve the content color inside a surface, use LocalContentColor.

@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
): Unit

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.

This version of Surface is responsible for a toggling its checked state as well as everything else that a regular Surface does:

This toggleable 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 convex 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. 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.

6. Click handling. This version of surface will react to the check toggles, calling onCheckedChange lambda, updating the interactionSource when androidx.compose.foundation.interaction.PressInteraction occurs, and showing ripple indication in response to press events. If you don't need check handling, consider using a Surface function that doesn't require onCheckedChange param.

7. Semantics for toggle. Just like with Modifier.toggleable, toggleable version of Surface will produce semantics to indicate that it is checked. No semantic role is set by default, you may specify one by passing a desired androidx.compose.ui.semantics.Role with a Modifier.semantics.

import androidx.compose.material.MaterialTheme
import androidx.compose.material.Surface
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.text.style.TextAlign

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

To modify these default style values used by text, use ProvideTextStyle or explicitly pass a new TextStyle to your text.

To manually retrieve the content color inside a surface, use LocalContentColor.

@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
): Unit

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.

This version of Surface is responsible for a selection handling as well as everything else that a regular Surface does:

This selectable 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 convex 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. 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.

6. Click handling. This version of surface will react to the clicks, calling onClick lambda, updating the interactionSource when androidx.compose.foundation.interaction.PressInteraction occurs, and showing ripple indication in response to press events. If you don't need click handling, consider using the Surface function that doesn't require onClick param.

7. Semantics for selection. Just like with Modifier.selectable, selectable version of Surface will produce semantics to indicate that it is selected. No semantic role is set by default, you may specify one by passing a desired androidx.compose.ui.semantics.Role with a Modifier.semantics.

import androidx.compose.material.MaterialTheme
import androidx.compose.material.Surface
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.text.style.TextAlign

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

To modify these default style values used by text, use ProvideTextStyle or explicitly pass a new TextStyle to your text.

To manually retrieve the content color inside a surface, use LocalContentColor.