Jetpack Compose Surface in Material 3 Compose

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.

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

The Surface is responsible for:

Clipping: Surface clips its children to the shape specified by shape
Borders: If shape has a border, then it will also be drawn.
Background: Surface fills the shape specified by shape with the color. If color is ColorScheme.surface a color overlay will be applied. The color of the overlay depends on the tonalElevation of this Surface, and the LocalAbsoluteTonalElevation 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.
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 ColorScheme, and return the corresponding content color. For example, if the color of this surface is ColorScheme.surface, contentColor will be set to ColorScheme.onSurface. If color is not part of the theme palette, contentColor will keep the same value set above this Surface.

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

Blocking touch propagation behind the surface.

Surface sample:

Overloads

Surface

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

Name	Description
`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 surfac

Surface

@Composable
@NonRestartableComposable
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 = remember { MutableInteractionSource() },
    content: @Composable () -> Unit
)

Parameters

Name	Description
`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`	the MutableInteractionSource representing the stream of Interactions for this Surface. You can create and pass in your own remembered MutableInteractionSource if you want to observe Interactions and customize the appearance / behavior of this Surface in different Interactions

Surface

@Composable
@NonRestartableComposable
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 = remember { MutableInteractionSource() },
    content: @Composable () -> Unit
)

Parameters

Name	Description
`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`	the MutableInteractionSource representing the stream of Interactions for this Surface. You can create and pass in your own remembered MutableInteractionSource if you want to observe Interactions and customize the appearance / behavior of this Surface in different Interactions

Surface

@Composable
@NonRestartableComposable
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 = remember { MutableInteractionSource() },
    content: @Composable () -> Unit
)

Parameters

Name	Description
`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`	the MutableInteractionSource representing the stream of Interactions for this Surface. You can create and pass in your own remembered MutableInteractionSource if you want to observe Interactions and customize the appearance / behavior of this Surface in different Interactions