New Compose Multiplatform components arrived on Composables UICheck it out →

Surface

The [Surface] is a building block component that will be used for any element on TV such as buttons, cards, navigation, or a simple background etc. This non-interactive Surface is similar to Compose Material's Surface composable

Last updated:

Installation

dependencies {
   implementation("androidx.tv:tv-material:1.0.0-beta01")
}

Overloads

@Composable
@NonRestartableComposable
fun Surface(
    modifier: Modifier = Modifier,
    tonalElevation: Dp = 0.dp,
    shape: Shape = SurfaceDefaults.shape,
    colors: SurfaceColors = SurfaceDefaults.colors(),
    border: Border = SurfaceDefaults.border,
    glow: Glow = SurfaceDefaults.glow,
    content: @Composable (BoxScope.() -> Unit)
)

Parameters

namedescription
modifierModifier to be applied to the layout corresponding to the surface
tonalElevationWhen [color] is [ColorScheme.surface], a higher the elevation will result in a darker color in light theme and lighter color in dark theme.
shapeDefines the surface's shape.
colorsDefines the background & content color to be used in this Surface. See [SurfaceDefaults.colors].
borderDefines a border around the Surface.
glowDiffused shadow to be shown behind the Surface. Note that glow is disabled for API levels below 28 as it is not supported by the underlying OS
contentdefines the [Composable] content inside the surface
@Composable
fun Surface(
    onClick: () -> Unit,
    modifier: Modifier = Modifier,
    onLongClick: (() -> Unit)? = null,
    enabled: Boolean = true,
    tonalElevation: Dp = 0.dp,
    shape: ClickableSurfaceShape = ClickableSurfaceDefaults.shape(),
    colors: ClickableSurfaceColors = ClickableSurfaceDefaults.colors(),
    scale: ClickableSurfaceScale = ClickableSurfaceDefaults.scale(),
    border: ClickableSurfaceBorder = ClickableSurfaceDefaults.border(),
    glow: ClickableSurfaceGlow = ClickableSurfaceDefaults.glow(),
    interactionSource: MutableInteractionSource? = null,
    content: @Composable (BoxScope.() -> Unit)
)

Parameters

namedescription
onClickcallback to be called when the surface is clicked. Note: DPad Enter button won't work if this value is null
modifierModifier to be applied to the layout corresponding to the surface
onLongClickcallback to be called when the surface is long clicked (long-pressed).
enabledControls the enabled state of the surface. When false, this Surface will not be clickable. A disabled surface will still be focusable (reason: https://issuetracker.google.com/302955429). If you still want it to not be focusable, consider using the Non-interactive variant of the Surface.
tonalElevationWhen [color] is [ColorScheme.surface], a higher the elevation will result in a darker color in light theme and lighter color in dark theme.
shapeDefines the surface's shape.
colorsDefines the background & content colors to be used in this surface for different interaction states. See [ClickableSurfaceDefaults.colors].
scaleDefines size of the Surface relative to its original size.
borderDefines a border around the Surface.
glowDiffused shadow to be shown behind the Surface. Note that glow is disabled for API levels below 28 as it is not supported by the underlying OS
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.
contentdefines the [Composable] content inside the surface
@Composable
fun Surface(
    selected: Boolean,
    onClick: () -> Unit,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    onLongClick: (() -> Unit)? = null,
    tonalElevation: Dp = Elevation.Level0,
    shape: SelectableSurfaceShape = SelectableSurfaceDefaults.shape(),
    colors: SelectableSurfaceColors = SelectableSurfaceDefaults.colors(),
    scale: SelectableSurfaceScale = SelectableSurfaceDefaults.scale(),
    border: SelectableSurfaceBorder = SelectableSurfaceDefaults.border(),
    glow: SelectableSurfaceGlow = SelectableSurfaceDefaults.glow(),
    interactionSource: MutableInteractionSource? = null,
    content: @Composable (BoxScope.() -> Unit)
)

Parameters

namedescription
selectedwhether or not this Surface is selected
onClickcallback to be invoked when the selectable Surface is clicked.
modifier[Modifier] to be applied to the layout corresponding to the surface
onLongClickcallback to be called when the selectable surface is long clicked (long-pressed).
enabledControls the enabled state of the surface. When false, this Surface will not be clickable. A disabled surface will still be focusable (reason: https://issuetracker.google.com/302955429). If you still want it to not be focusable, consider using the Non-interactive variant of the Surface.
tonalElevationWhen [color] is [ColorScheme.surface], a higher the elevation will result in a darker color in light theme and lighter color in dark theme.
shapeDefines the surface's shape.
colorsDefines the background & content colors to be used in this surface for different interaction states. See [SelectableSurfaceDefaults.colors].
scaleDefines size of the Surface relative to its original size.
borderDefines a border around the Surface.
glowDiffused shadow to be shown behind the Surface. Note that glow is disabled for API levels below 28 as it is not supported by the underlying OS
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.
contentdefines the [Composable] content inside the surface