{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

SurfaceKt

public final class SurfaceKt


Summary

Public methods

static final void
@Composable
@NonRestartableComposable
Surface(
    @NonNull Modifier modifier,
    @NonNull Shape shape,
    @NonNull Color color,
    @NonNull Color contentColor,
    @NonNull Dp tonalElevation,
    @NonNull Dp shadowElevation,
    BorderStroke border,
    @Composable @NonNull Function0<Unit> content
)

Material surface is the central metaphor in material design.

static final void
@Composable
@NonRestartableComposable
Surface(
    @NonNull Function0<Unit> onClick,
    @NonNull Modifier modifier,
    boolean enabled,
    @NonNull Shape shape,
    @NonNull Color color,
    @NonNull Color contentColor,
    @NonNull Dp tonalElevation,
    @NonNull Dp shadowElevation,
    BorderStroke border,
    @NonNull MutableInteractionSource interactionSource,
    @Composable @NonNull Function0<Unit> content
)

Material surface is the central metaphor in material design.

static final void
@Composable
@NonRestartableComposable
Surface(
    boolean checked,
    @NonNull Function1<@NonNull BooleanUnit> onCheckedChange,
    @NonNull Modifier modifier,
    boolean enabled,
    @NonNull Shape shape,
    @NonNull Color color,
    @NonNull Color contentColor,
    @NonNull Dp tonalElevation,
    @NonNull Dp shadowElevation,
    BorderStroke border,
    @NonNull MutableInteractionSource interactionSource,
    @Composable @NonNull Function0<Unit> content
)

Material surface is the central metaphor in material design.

static final void
@Composable
@NonRestartableComposable
Surface(
    boolean selected,
    @NonNull Function0<Unit> onClick,
    @NonNull Modifier modifier,
    boolean enabled,
    @NonNull Shape shape,
    @NonNull Color color,
    @NonNull Color contentColor,
    @NonNull Dp tonalElevation,
    @NonNull Dp shadowElevation,
    BorderStroke border,
    @NonNull MutableInteractionSource interactionSource,
    @Composable @NonNull Function0<Unit> content
)

Material surface is the central metaphor in material design.

static final @NonNull ProvidableCompositionLocal<@NonNull Dp>

CompositionLocal containing the current absolute elevation provided by Surface components.

Public methods

Surface

@Composable
@NonRestartableComposable
public static final void Surface(
    @NonNull Modifier modifier,
    @NonNull Shape shape,
    @NonNull Color color,
    @NonNull Color contentColor,
    @NonNull Dp tonalElevation,
    @NonNull Dp shadowElevation,
    BorderStroke border,
    @Composable @NonNull Function0<Unit> content
)

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:

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

  2. Borders: If shape has a border, then it will also be drawn.

  3. 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.

  4. 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.

  1. Blocking touch propagation behind the surface.

Surface sample:

import androidx.compose.material3.Surface
import androidx.compose.material3.Text

Surface {
    Text("Text on Surface")
}
Parameters
@NonNull Modifier modifier

Modifier to be applied to the layout corresponding to the surface

@NonNull Shape shape

Defines the surface's shape as well its shadow.

@NonNull Color color

The background color. Use Color.Transparent to have no color.

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

@NonNull Dp 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.

@NonNull Dp 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.

BorderStroke border

Optional border to draw on top of the surface

Surface

@Composable
@NonRestartableComposable
public static final void Surface(
    @NonNull Function0<Unit> onClick,
    @NonNull Modifier modifier,
    boolean enabled,
    @NonNull Shape shape,
    @NonNull Color color,
    @NonNull Color contentColor,
    @NonNull Dp tonalElevation,
    @NonNull Dp shadowElevation,
    BorderStroke border,
    @NonNull MutableInteractionSource interactionSource,
    @Composable @NonNull Function0<Unit> content
)

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.

This version of Surface is responsible for a click handling as well as 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. Borders: If shape has a border, then it will also be drawn.

  3. Background: Surface fills the shape specified by shape with the color. If color is ColorScheme.surface a color overlay may 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.

  4. 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.

  5. Click handling. This version of surface will react to the clicks, calling onClick lambda, updating the interactionSource when 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. If you need to set a custom label for the onClick, apply a Modifier.semantics { onClick(label = "YOUR_LABEL", action = null) } to the Surface.

  6. 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 Role with a Modifier.semantics.

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

Clickable surface sample:

import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

var count by remember { mutableStateOf(0) }
Surface(
    onClick = { count++ },
) {
    Text("Clickable Surface. Count: $count")
}
Parameters
@NonNull Function0<Unit> onClick

callback to be called when the surface is clicked

@NonNull Modifier modifier

Modifier to be applied to the layout corresponding to the surface

boolean enabled

Controls the enabled state of the surface. When false, this surface will not be clickable

@NonNull Shape shape

Defines the surface's shape as well its shadow. A shadow is only displayed if the tonalElevation is greater than zero.

@NonNull Color color

The background color. Use Color.Transparent to have no color.

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

@NonNull Dp 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.

@NonNull Dp 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.

BorderStroke border

Optional border to draw on top of the surface

@NonNull MutableInteractionSource 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
public static final void Surface(
    boolean checked,
    @NonNull Function1<@NonNull BooleanUnit> onCheckedChange,
    @NonNull Modifier modifier,
    boolean enabled,
    @NonNull Shape shape,
    @NonNull Color color,
    @NonNull Color contentColor,
    @NonNull Dp tonalElevation,
    @NonNull Dp shadowElevation,
    BorderStroke border,
    @NonNull MutableInteractionSource interactionSource,
    @Composable @NonNull Function0<Unit> content
)

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.

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. Borders: If shape has a border, then it will also be drawn.

  3. Background: Surface fills the shape specified by shape with the color. If color is ColorScheme.surface a color overlay may 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.

  4. 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.

  5. Click handling. This version of surface will react to the check toggles, calling onCheckedChange lambda, updating the interactionSource when 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.

  6. 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 Role with a Modifier.semantics.

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

Toggleable surface sample:

import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.material3.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.colorScheme.surfaceVariant
    } else {
        MaterialTheme.colorScheme.surface
    }
) {
    Text(
        text = if (checked) "ON" else "OFF",
        textAlign = TextAlign.Center
    )
}
Parameters
boolean checked

whether or not this Surface is toggled on or off

@NonNull Function1<@NonNull BooleanUnit> onCheckedChange

callback to be invoked when the toggleable Surface is clicked

@NonNull Modifier modifier

Modifier to be applied to the layout corresponding to the surface

boolean enabled

Controls the enabled state of the surface. When false, this surface will not be clickable

@NonNull Shape shape

Defines the surface's shape as well its shadow. A shadow is only displayed if the tonalElevation is greater than zero.

@NonNull Color color

The background color. Use Color.Transparent to have no color.

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

@NonNull Dp 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.

@NonNull Dp 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.

BorderStroke border

Optional border to draw on top of the surface

@NonNull MutableInteractionSource 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
public static final void Surface(
    boolean selected,
    @NonNull Function0<Unit> onClick,
    @NonNull Modifier modifier,
    boolean enabled,
    @NonNull Shape shape,
    @NonNull Color color,
    @NonNull Color contentColor,
    @NonNull Dp tonalElevation,
    @NonNull Dp shadowElevation,
    BorderStroke border,
    @NonNull MutableInteractionSource interactionSource,
    @Composable @NonNull Function0<Unit> content
)

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.

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. Borders: If shape has a border, then it will also be drawn.

  3. Background: Surface fills the shape specified by shape with the color. If color is ColorScheme.surface a color overlay may 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.

  4. 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.

  5. Click handling. This version of surface will react to the clicks, calling onClick lambda, updating the interactionSource when 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.

  6. 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 Role with a Modifier.semantics.

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

Selectable surface sample:

import androidx.compose.material3.Surface
import androidx.compose.material3.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 },
) {
    Text(
        text = if (selected) "Selected" else "Not Selected",
        textAlign = TextAlign.Center
    )
}
Parameters
boolean selected

whether or not this Surface is selected

@NonNull Function0<Unit> onClick

callback to be called when the surface is clicked

@NonNull Modifier modifier

Modifier to be applied to the layout corresponding to the surface

boolean enabled

Controls the enabled state of the surface. When false, this surface will not be clickable

@NonNull Shape shape

Defines the surface's shape as well its shadow. A shadow is only displayed if the tonalElevation is greater than zero.

@NonNull Color color

The background color. Use Color.Transparent to have no color.

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

@NonNull Dp 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.

@NonNull Dp 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.

BorderStroke border

Optional border to draw on top of the surface

@NonNull MutableInteractionSource 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.

getLocalAbsoluteTonalElevation

public static final @NonNull ProvidableCompositionLocal<@NonNull DpgetLocalAbsoluteTonalElevation()

CompositionLocal containing the current absolute elevation provided by Surface components. This absolute elevation is a sum of all the previous elevations. Absolute elevation is only used for calculating surface tonal colors, and is not used for drawing the shadow in a Surface.