# surface

## Functions summary

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier.https://developer.android.com/reference/kotlin/androidx/xr/glimmer/surface.composable#(androidx.compose.ui.Modifier).surface(kotlin.Boolean,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.xr.glimmer.SurfaceDepthEffect,androidx.compose.foundation.interaction.InteractionSource)( enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, shape: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Shape, color: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color, focusedColor: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color, contentColor: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color, focusedContentColor: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color, depthEffect: https://developer.android.com/reference/kotlin/androidx/xr/glimmer/SurfaceDepthEffect?, interactionSource: https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/InteractionSource? )` A surface is a fundamental building block in Glimmer. |

## Functions

### Modifier.surface

Artifact: [androidx.xr.glimmer:glimmer](https://developer.android.com/jetpack/androidx/releases/xr-glimmer) [View Source](https://cs.android.com/search?q=file:androidx/xr/glimmer/Surface.kt+function:surface) Added in [1.0.0-alpha22](https://developer.android.com/jetpack/androidx/releases/xr-glimmer#1.0.0-alpha22)

```
@Composable
fun Modifier.surface(
    enabled: Boolean = true,
    shape: Shape = GlimmerTheme.shapes.medium,
    color: Color = GlimmerTheme.colors.surface,
    focusedColor: Color = SurfaceDefaults.focusedColor(color),
    contentColor: Color = calculateContentColor(color),
    focusedContentColor: Color = calculateContentColor(focusedColor),
    depthEffect: SurfaceDepthEffect? = null,
    interactionSource: InteractionSource? = null
): Modifier
```

A surface is a fundamental building block in Glimmer. A surface represents a distinct visual area or 'physical' boundary for components such as buttons and cards. A `https://developer.android.com/reference/kotlin/androidx/xr/glimmer/surface.composable#(androidx.compose.ui.Modifier).surface(kotlin.Boolean,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.xr.glimmer.SurfaceDepthEffect,androidx.compose.foundation.interaction.InteractionSource)` implements shared visual decoration for Jetpack Compose Glimmer components:

1. Clipping: a surface clips its children to the shape specified by `https://developer.android.com/reference/kotlin/androidx/xr/glimmer/package-summary#(androidx.compose.ui.Modifier).surface(kotlin.Boolean,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.xr.glimmer.SurfaceDepthEffect,androidx.compose.foundation.interaction.InteractionSource)`

2. Border: a surface draws an inner border to emphasize the boundary of the component. When focused, a surface draws a wider border with a focused highlight on top to indicate the focus state.

3. Background: a surface has a background color of `https://developer.android.com/reference/kotlin/androidx/xr/glimmer/package-summary#(androidx.compose.ui.Modifier).surface(kotlin.Boolean,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.xr.glimmer.SurfaceDepthEffect,androidx.compose.foundation.interaction.InteractionSource)` (and `https://developer.android.com/reference/kotlin/androidx/xr/glimmer/package-summary#(androidx.compose.ui.Modifier).surface(kotlin.Boolean,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.xr.glimmer.SurfaceDepthEffect,androidx.compose.foundation.interaction.InteractionSource)` when focused).

4. Depth effect: a surface can have different `https://developer.android.com/reference/kotlin/androidx/xr/glimmer/DepthEffect` shadows for different states, as specified by `https://developer.android.com/reference/kotlin/androidx/xr/glimmer/package-summary#(androidx.compose.ui.Modifier).surface(kotlin.Boolean,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.xr.glimmer.SurfaceDepthEffect,androidx.compose.foundation.interaction.InteractionSource)`.

5. Content color: a surface provides a `https://developer.android.com/reference/kotlin/androidx/xr/glimmer/package-summary#(androidx.compose.ui.Modifier).surface(kotlin.Boolean,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.xr.glimmer.SurfaceDepthEffect,androidx.compose.foundation.interaction.InteractionSource)` (and `https://developer.android.com/reference/kotlin/androidx/xr/glimmer/package-summary#(androidx.compose.ui.Modifier).surface(kotlin.Boolean,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.xr.glimmer.SurfaceDepthEffect,androidx.compose.foundation.interaction.InteractionSource)` when focused) for text and icons inside the surface. By default this is calculated from the provided background color.

6. Interaction states: when focused, a surface displays draws a wider border with a focused highlight on top. When pressed, a surface draws a pressed overlay. This happens for interactions emitted from `https://developer.android.com/reference/kotlin/androidx/xr/glimmer/package-summary#(androidx.compose.ui.Modifier).surface(kotlin.Boolean,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.xr.glimmer.SurfaceDepthEffect,androidx.compose.foundation.interaction.InteractionSource)`.

Use surface on its own for decorative elements that cannot be interacted with by a user:

```kotlin
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.padding
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.xr.glimmer.Text
import androidx.xr.glimmer.surface

Box(Modifier.surface().padding(horizontal = 24.dp, vertical = 20.dp)) {
    Text("This is a surface")
}
```

In most cases surfaces should be interactive, to allow users to consistently move focus and navigate between components. You can use `https://developer.android.com/reference/kotlin/androidx/compose/foundation/focusable.modifier#(androidx.compose.ui.Modifier).focusable(kotlin.Boolean,androidx.compose.foundation.interaction.MutableInteractionSource)` for focus-only surfaces, or `https://developer.android.com/reference/kotlin/androidx/compose/foundation/clickable.modifier#(androidx.compose.ui.Modifier).clickable(kotlin.Boolean,kotlin.String,androidx.compose.ui.semantics.Role,androidx.compose.foundation.interaction.MutableInteractionSource,kotlin.Function0)` and other modifiers for surfaces with actions. To ensure the surface correctly reflects the interaction states, provide the same `https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/InteractionSource` to all modifiers.

For example, to create a clickable surface:

```kotlin
import androidx.compose.foundation.clickable
import androidx.compose.foundation.interaction.MutableInteractionSource
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.padding
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.xr.glimmer.Text
import androidx.xr.glimmer.surface

val interactionSource = remember { MutableInteractionSource() }
Box(
    Modifier.surface(
            // Provide the same interaction source here and to clickable to make sure that
            // surface appears focused and pressed when interacted with
            interactionSource = interactionSource
        )
        .clickable(interactionSource = interactionSource, onClick = {})
        .padding(horizontal = 24.dp, vertical = 20.dp)
) {
    Text("This is a clickable surface")
}
```

Similarly, to create a focusable surface:

```kotlin
import androidx.compose.foundation.focusable
import androidx.compose.foundation.interaction.MutableInteractionSource
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.padding
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.xr.glimmer.Text
import androidx.xr.glimmer.surface

val interactionSource = remember { MutableInteractionSource() }
Box(
    Modifier.surface(
            // Provide the same interaction source here and to focusable to make sure that
            // surface appears focused when interacted with.
            interactionSource = interactionSource
        )
        .focusable(interactionSource = interactionSource)
        .padding(horizontal = 24.dp, vertical = 20.dp)
) {
    Text("This is a focusable surface")
}
```

To create a surface with custom colors:

```kotlin
import androidx.compose.foundation.focusable
import androidx.compose.foundation.interaction.MutableInteractionSource
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.padding
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.xr.glimmer.SurfaceDefaults
import androidx.xr.glimmer.Text
import androidx.xr.glimmer.surface

val interactionSource = remember { MutableInteractionSource() }
Box(
    Modifier.surface(
            focusedColor = SurfaceDefaults.focusedColor(Color(0xFF34E0A1)),
            interactionSource = interactionSource,
        )
        .focusable(interactionSource = interactionSource)
        .padding(horizontal = 24.dp, vertical = 20.dp)
) {
    Text("Surface with custom colors")
}
```

| Parameters |
|---|---|
| `enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | controls the enabled state of this surface. When `false`, a disabled overlay visual will be drawn on top of the surface. Note that this only affects the visual decoration; it does not intercept input or block interaction states (such as focus or press) from the `https://developer.android.com/reference/kotlin/androidx/xr/glimmer/package-summary#(androidx.compose.ui.Modifier).surface(kotlin.Boolean,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.xr.glimmer.SurfaceDepthEffect,androidx.compose.foundation.interaction.InteractionSource)`. |
| `shape: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Shape = GlimmerTheme.shapes.medium` | the `https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Shape` used to clip this surface, and also used to draw the background and border |
| `color: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color = GlimmerTheme.colors.surface` | the background `https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color` for this surface. When providing a custom color, ensure it is suitable for a surface background. |
| `focusedColor: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color = SurfaceDefaults.focusedColor(color)` | the background `https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color` for this surface when focused. When providing a custom color, ensure it is suitable for a focused surface background or use `https://developer.android.com/reference/kotlin/androidx/xr/glimmer/SurfaceDefaults#focusedColor(androidx.compose.ui.graphics.Color)` to adapt it. |
| `contentColor: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color = calculateContentColor(color)` | the `https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color` for content inside this surface |
| `focusedContentColor: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color = calculateContentColor(focusedColor)` | the `https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color` for content inside this surface when focused |
| `depthEffect: https://developer.android.com/reference/kotlin/androidx/xr/glimmer/SurfaceDepthEffect? = null` | the `https://developer.android.com/reference/kotlin/androidx/xr/glimmer/SurfaceDepthEffect` for this surface, representing the `https://developer.android.com/reference/kotlin/androidx/xr/glimmer/DepthEffect` shadows rendered in different states. |
| `interactionSource: https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/InteractionSource? = null` | the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/InteractionSource` that emits `https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/Interaction`s for this surface. For interactive surfaces, the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/InteractionSource` instance provided to this surface must be shared with the modifier responsible for emitting `https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/Interaction`s, such as `https://developer.android.com/reference/kotlin/androidx/compose/foundation/focusable.modifier#(androidx.compose.ui.Modifier).focusable(kotlin.Boolean,androidx.compose.foundation.interaction.MutableInteractionSource)` or `https://developer.android.com/reference/kotlin/androidx/compose/foundation/clickable.modifier#(androidx.compose.ui.Modifier).clickable(kotlin.Boolean,kotlin.String,androidx.compose.ui.semantics.Role,androidx.compose.foundation.interaction.MutableInteractionSource,kotlin.Function0)`. |