viewcompose-ui-foundation/com.viewcompose.ui.foundation/BasicSurface

BasicSurface

fun UiTreeBuilder.BasicSurface(style: BasicSurfaceStyle, contentColor: Int, enabled: Boolean = true, onClick: () -> Unit? = null, minimumWidth: UiDp = UiDp.Zero, minimumHeight: UiDp = UiDp.Zero, visualHeight: UiDp? = null, role: SemanticsRole? = null, key: Any? = null, contentAlignment: BoxAlignment = BoxAlignment.TopStart, modifier: Modifier = Modifier, content: BoxScope.() -> Unit)(source)

Emits a design-system-neutral surface from fully resolved visual and interaction values.

The surface owns one Android View whose effective bounds participate in layout, input, focus, and semantics. visualHeight optionally centers only the visual fill, border, ripple, and shape inside those bounds. A caller background, border, or shape in modifier replaces the resolved surface and therefore occupies the complete effective bounds. Caller elevation replaces BasicSurfaceStyle.elevation, while caller shadow modifiers are drawn after the style shadows.

The callback runs synchronously on the renderer input thread, which is the Android main thread for the standard renderer. A non-null onClick with enabled set to false retains disabled semantics but installs no click listener or interaction layer.

Receiver

active tree builder receiving the surface node

Parameters

style

resolved fill, geometry, border, clipping, elevation, and shadow values

contentColor

packed ARGB value provided to descendant content defaults

enabled

whether the optional click action and state layers participate in input

onClick

optional click callback; null creates a non-interactive surface

minimumWidth

non-negative minimum effective width in dp

minimumHeight

non-negative minimum effective height in dp

visualHeight

optional non-negative visual surface height centered inside effective bounds

role

optional accessibility role applied to the merged surface subtree

key

optional stable sibling identity used during reconciliation

contentAlignment

default alignment for children without explicit box parent data

modifier

caller configuration appended after resolved surface behavior and visuals

content

child content emitted inside the surface

Throws

IllegalArgumentException

if a supplied dimension is negative

Samples

val node = buildVNodeTree {
    BasicSurface(
        style = BasicSurfaceStyle(
            fill = Brush.SolidColor(0xFF1E4D5A.toInt()),
            shape = UiShape.continuous(16.dp),
            borderWidth = 1.dp,
            borderColor = 0xFF8FD8E8.toInt(),
            clipContent = true,
            interactionIndication = UiInteractionIndication.StateLayer(
                UiStateLayerColors(
                    pressedColor = 0x33FFFFFF,
                    focusedColor = 0x2AFFFFFF,
                    hoveredColor = 0x1FFFFFFF,
                ),
            ),
        ),
        contentColor = 0xFFFFFFFF.toInt(),
        onClick = {},
        minimumHeight = 48.dp,
        visualHeight = 40.dp,
    ) {
        Text("Open")
    }
}.single()

val surface = node.spec as SurfaceNodeProps
check(surface.minimumHeight == 48.dp)
check(surface.visualHeight == 40.dp)