We just launched Compose Examples featuring over 150+ components! Check it out →

graphicsLayer

Common

Modifier in Compose Ui

A [Modifier.Element] that makes content draw into a draw layer. The draw layer can be invalidated separately from parents. A [graphicsLayer] should be used when the content updates independently from anything above it to minimize the invalidated content.

[graphicsLayer] can also be used to apply effects to content, such as scaling ([scaleX], [scaleY]), rotation ([rotationX], [rotationY], [rotationZ]), opacity ([alpha]), shadow ([shadowElevation], [shape]), and clipping ([clip], [shape]).

Note that if you provide a non-zero [shadowElevation] and if the passed [shape] is concave the shadow will not be drawn on Android versions less than 10.

Also note that alpha values less than 1.0f will have their contents implicitly clipped to their bounds. This is because an intermediate compositing layer is created to render contents into first before being drawn into the destination with the desired alpha. This layer is sized to the bounds of the composable this modifier is configured on, and contents outside of these bounds are omitted.

If the layer parameters are backed by a [androidx.compose.runtime.State] or an animated value prefer an overload with a lambda block on [GraphicsLayerScope] as reading a state inside the block will only cause the layer properties update without triggering recomposition and relayout.

Last updated:

Installation

dependencies {
   implementation("androidx.compose.ui:ui:1.8.0-alpha04")
}

Overloads

@Deprecated(
    "Replace with graphicsLayer that consumes an optional RenderEffect parameter and " +
        "shadow color parameters",
    replaceWith =
        ReplaceWith(
            "Modifier.graphicsLayer(scaleX, scaleY, alpha, translationX, translationY, " +
                "shadowElevation, rotationX, rotationY, rotationZ, cameraDistance, transformOrigin, " +
                "shape, clip, null, DefaultShadowColor, DefaultShadowColor)",
            "androidx.compose.ui.graphics"
        ),
    level = DeprecationLevel.HIDDEN
)
@Stable
fun Modifier.graphicsLayer(
    scaleX: Float = 1f,
    scaleY: Float = 1f,
    alpha: Float = 1f,
    translationX: Float = 0f,
    translationY: Float = 0f,
    shadowElevation: Float = 0f,
    rotationX: Float = 0f,
    rotationY: Float = 0f,
    rotationZ: Float = 0f,
    cameraDistance: Float = DefaultCameraDistance,
    transformOrigin: TransformOrigin = TransformOrigin.Center,
    shape: Shape = RectangleShape,
    clip: Boolean = false
)

Parameters

namedescription
scaleXsee [GraphicsLayerScope.scaleX]
scaleYsee [GraphicsLayerScope.scaleY]
alphasee [GraphicsLayerScope.alpha]
translationXsee [GraphicsLayerScope.translationX]
translationYsee [GraphicsLayerScope.translationY]
shadowElevationsee [GraphicsLayerScope.shadowElevation]
rotationXsee [GraphicsLayerScope.rotationX]
rotationYsee [GraphicsLayerScope.rotationY]
rotationZsee [GraphicsLayerScope.rotationZ]
cameraDistancesee [GraphicsLayerScope.cameraDistance]
transformOriginsee [GraphicsLayerScope.transformOrigin]
shapesee [GraphicsLayerScope.shape]
clipsee [GraphicsLayerScope.clip]
@Deprecated(
    "Replace with graphicsLayer that consumes shadow color parameters",
    replaceWith =
        ReplaceWith(
            "Modifier.graphicsLayer(scaleX, scaleY, alpha, translationX, translationY, " +
                "shadowElevation, rotationX, rotationY, rotationZ, cameraDistance, transformOrigin, " +
                "shape, clip, null, DefaultShadowColor, DefaultShadowColor)",
            "androidx.compose.ui.graphics"
        ),
    level = DeprecationLevel.HIDDEN
)
@Stable
fun Modifier.graphicsLayer(
    scaleX: Float = 1f,
    scaleY: Float = 1f,
    alpha: Float = 1f,
    translationX: Float = 0f,
    translationY: Float = 0f,
    shadowElevation: Float = 0f,
    rotationX: Float = 0f,
    rotationY: Float = 0f,
    rotationZ: Float = 0f,
    cameraDistance: Float = DefaultCameraDistance,
    transformOrigin: TransformOrigin = TransformOrigin.Center,
    shape: Shape = RectangleShape,
    clip: Boolean = false,
    renderEffect: RenderEffect? = null
)

Parameters

namedescription
scaleXsee [GraphicsLayerScope.scaleX]
scaleYsee [GraphicsLayerScope.scaleY]
alphasee [GraphicsLayerScope.alpha]
translationXsee [GraphicsLayerScope.translationX]
translationYsee [GraphicsLayerScope.translationY]
shadowElevationsee [GraphicsLayerScope.shadowElevation]
rotationXsee [GraphicsLayerScope.rotationX]
rotationYsee [GraphicsLayerScope.rotationY]
rotationZsee [GraphicsLayerScope.rotationZ]
cameraDistancesee [GraphicsLayerScope.cameraDistance]
transformOriginsee [GraphicsLayerScope.transformOrigin]
shapesee [GraphicsLayerScope.shape]
clipsee [GraphicsLayerScope.clip]
renderEffectsee [GraphicsLayerScope.renderEffect]
@Deprecated(
    "Replace with graphicsLayer that consumes a compositing strategy",
    replaceWith =
        ReplaceWith(
            "Modifier.graphicsLayer(scaleX, scaleY, alpha, translationX, translationY, " +
                "shadowElevation, rotationX, rotationY, rotationZ, cameraDistance, transformOrigin, " +
                "shape, clip, null, DefaultShadowColor, DefaultShadowColor, CompositingStrategy.Auto)",
            "androidx.compose.ui.graphics"
        ),
    level = DeprecationLevel.HIDDEN
)
@Stable
fun Modifier.graphicsLayer(
    scaleX: Float = 1f,
    scaleY: Float = 1f,
    alpha: Float = 1f,
    translationX: Float = 0f,
    translationY: Float = 0f,
    shadowElevation: Float = 0f,
    rotationX: Float = 0f,
    rotationY: Float = 0f,
    rotationZ: Float = 0f,
    cameraDistance: Float = DefaultCameraDistance,
    transformOrigin: TransformOrigin = TransformOrigin.Center,
    shape: Shape = RectangleShape,
    clip: Boolean = false,
    renderEffect: RenderEffect? = null,
    ambientShadowColor: Color = DefaultShadowColor,
    spotShadowColor: Color = DefaultShadowColor,
)

Parameters

namedescription
scaleXsee [GraphicsLayerScope.scaleX]
scaleYsee [GraphicsLayerScope.scaleY]
alphasee [GraphicsLayerScope.alpha]
translationXsee [GraphicsLayerScope.translationX]
translationYsee [GraphicsLayerScope.translationY]
shadowElevationsee [GraphicsLayerScope.shadowElevation]
rotationXsee [GraphicsLayerScope.rotationX]
rotationYsee [GraphicsLayerScope.rotationY]
rotationZsee [GraphicsLayerScope.rotationZ]
cameraDistancesee [GraphicsLayerScope.cameraDistance]
transformOriginsee [GraphicsLayerScope.transformOrigin]
shapesee [GraphicsLayerScope.shape]
clipsee [GraphicsLayerScope.clip]
renderEffectsee [GraphicsLayerScope.renderEffect]
ambientShadowColorsee [GraphicsLayerScope.ambientShadowColor]
spotShadowColorsee [GraphicsLayerScope.spotShadowColor]
@Stable
fun Modifier.graphicsLayer(
    scaleX: Float = 1f,
    scaleY: Float = 1f,
    alpha: Float = 1f,
    translationX: Float = 0f,
    translationY: Float = 0f,
    shadowElevation: Float = 0f,
    rotationX: Float = 0f,
    rotationY: Float = 0f,
    rotationZ: Float = 0f,
    cameraDistance: Float = DefaultCameraDistance,
    transformOrigin: TransformOrigin = TransformOrigin.Center,
    shape: Shape = RectangleShape,
    clip: Boolean = false,
    renderEffect: RenderEffect? = null,
    ambientShadowColor: Color = DefaultShadowColor,
    spotShadowColor: Color = DefaultShadowColor,
    compositingStrategy: CompositingStrategy = CompositingStrategy.Auto
)

Parameters

namedescription
scaleXsee [GraphicsLayerScope.scaleX]
scaleYsee [GraphicsLayerScope.scaleY]
alphasee [GraphicsLayerScope.alpha]
translationXsee [GraphicsLayerScope.translationX]
translationYsee [GraphicsLayerScope.translationY]
shadowElevationsee [GraphicsLayerScope.shadowElevation]
rotationXsee [GraphicsLayerScope.rotationX]
rotationYsee [GraphicsLayerScope.rotationY]
rotationZsee [GraphicsLayerScope.rotationZ]
cameraDistancesee [GraphicsLayerScope.cameraDistance]
transformOriginsee [GraphicsLayerScope.transformOrigin]
shapesee [GraphicsLayerScope.shape]
clipsee [GraphicsLayerScope.clip]
renderEffectsee [GraphicsLayerScope.renderEffect]
ambientShadowColorsee [GraphicsLayerScope.ambientShadowColor]
spotShadowColorsee [GraphicsLayerScope.spotShadowColor]
compositingStrategysee [GraphicsLayerScope.compositingStrategy]
@Stable
fun Modifier.graphicsLayer(block: GraphicsLayerScope.() -> Unit): Modifier

Parameters

namedescription
blockblock on [GraphicsLayerScope] where you define the layer properties.

Code Examples

ChangeOpacity

@Composable
fun ChangeOpacity() {
    Text("Hello World", Modifier.graphicsLayer(alpha = 0.5f, clip = true))
}

CompositingStrategyModulateAlpha

@Composable
fun CompositingStrategyModulateAlpha() {
    Canvas(
        modifier =
            Modifier.size(100.dp)
                .background(Color.Black)
                .graphicsLayer(
                    alpha = 0.5f,
                    compositingStrategy = CompositingStrategy.ModulateAlpha
                )
    ) {
        // Configuring an alpha less than 1.0 and specifying
        // CompositingStrategy.ModulateAlpha ends up with the overlapping region
        // of the 2 draw rect calls to blend transparent blue and transparent red
        // against the black background instead of just transparent blue which is what would
        // occur with CompositingStrategy.Auto or CompositingStrategy.Offscreen
        inset(0f, 0f, size.width / 3, size.height / 3) { drawRect(color = Color.Red) }
        inset(size.width / 3, size.height / 3, 0f, 0f) { drawRect(color = Color.Blue) }
    }
}

AnimateFadeIn

@Composable
fun AnimateFadeIn() {
    val animatedAlpha = remember { Animatable(0f) }
    Text(
        "Hello World",
        Modifier.graphicsLayer {
            alpha = animatedAlpha.value
            clip = true
        }
    )
    LaunchedEffect(animatedAlpha) { animatedAlpha.animateTo(1f) }
}
by @alexstyl