androidx.compose.ui.draw

Interfaces

BuildDrawCacheParams

The set of parameters which could be used to build the drawing cache.
Cmn
CacheDrawModifierNode

Expands on the androidx.compose.ui.node.DrawModifierNode by adding the ability to invalidate the draw cache for changes in things like shapes and bitmaps (see Modifier.border for a usage examples).
Cmn
DrawCacheModifier

DrawModifier implementation that supports building a cache of objects to be referenced across draw calls
Cmn
DrawModifier

A Modifier.Element that draws into the space of the layout.
Cmn
DropShadowScope

Scope that provides the capability to configure the properties of a drop shadow in order to support efficient transformations without recomposition
Cmn
InnerShadowScope

Scope that provides the capability to configure the properties of an inner shadow in order to support efficient transformations without recomposition
Cmn
ShadowScope

Scope that can be used to define properties to render either a drop shadow or inner shadow.
Cmn

Classes

BlurredEdgeTreatment

Determines the strategy used to render pixels in the blurred result that may extend beyond the bounds of the original input.
Cmn
CacheDrawScope

Handle to a drawing environment that enables caching of content based on the resolved size.
Cmn
DrawResult

Holder to a callback to be invoked during draw operations.
Cmn

Top-level functions summary

CacheDrawModifierNode
Cmn

Extension functions summary

Modifier

Draw content with modified alpha that may be less than 1.
Cmn
Modifier
Modifier.blur(radius: Dp, edgeTreatment: BlurredEdgeTreatment)

Draw content blurred with the specified radii.
Cmn
Modifier
Modifier.blur(
    radiusX: Dp,
    radiusY: Dp,
    edgeTreatment: BlurredEdgeTreatment
)

Draw content blurred with the specified radii.
Cmn
Modifier

Clip the content to shape.
Cmn
Modifier

Clip the content to the bounds of a layer defined at this modifier.
Cmn
Modifier

Draw into a Canvas behind the modified content.
Cmn
Modifier

Draw into a DrawScope with content that is persisted across draw calls as long as the size of the drawing area is the same or any state objects that are read have not changed.
Cmn
Modifier

Creates a DrawModifier that allows the developer to draw before or after the layout's contents.
Cmn
Modifier
Modifier.dropShadow(shape: Shape, block: DropShadowScope.() -> Unit)

Draws a drop shadow behind the rest of the content with the geometry specified by the given shape and the shadow properties defined the DropShadowScope.
Cmn
Modifier
Modifier.dropShadow(shape: Shape, shadow: Shadow)

Draws a drop shadow behind the rest of the content with the geometry specified by the given shape and the shadow properties defined by the Shadow.
Cmn
Modifier

Draws an inner shadow behind the rest of the content with the geometry specified by the given shape and the shadow properties defined the InnerShadowScope.
Cmn
Modifier
Modifier.innerShadow(shape: Shape, shadow: Shadow)

Draws an inner shadow on top of the rest of the content with the geometry specified by the given shape and the shadow properties defined by the Shadow.
Cmn
Modifier
Modifier.paint(
    painter: Painter,
    sizeToIntrinsics: Boolean,
    alignment: Alignment,
    contentScale: ContentScale,
    alpha: Float,
    colorFilter: ColorFilter?
)

Paint the content using painter.
Cmn
Modifier
Modifier.rotate(degrees: Float)

Sets the degrees the view is rotated around the center of the composable.
Cmn
Modifier

Scale the contents of both the horizontal and vertical axis uniformly by the same scale factor.
Cmn
Modifier
Modifier.scale(scaleX: Float, scaleY: Float)

Scale the contents of the composable by the following scale factors along the horizontal and vertical axis respectively.
Cmn
Modifier
Modifier.shadow(
    elevation: Dp,
    shape: Shape,
    clip: Boolean,
    ambientColor: Color,
    spotColor: Color
)

Creates a graphicsLayer that draws a shadow.
Cmn

Top-level functions

CacheDrawModifierNode

Cmn 
fun CacheDrawModifierNode(onBuildDrawCache: CacheDrawScope.() -> DrawResult): CacheDrawModifierNode

Extension functions

alpha

Cmn 
fun Modifier.alpha(alpha: Float): Modifier

Draw content with modified alpha that may be less than 1.

Usage of this API renders this composable into a separate graphics layer. Note when an alpha less than 1.0f is provided, contents are 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.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.alpha
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box(Modifier.size(100.dp).alpha(alpha = 0.5f).background(Color.Red))
Parameters
alpha: Float

the fraction of children's alpha value and must be between 0 and 1, inclusive.
See also
graphicsLayer

Example usage:

blur

Cmn 
fun Modifier.blur(
    radius: Dp,
    edgeTreatment: BlurredEdgeTreatment = BlurredEdgeTreatment.Rectangle
): Modifier

Draw content blurred with the specified radii. Note this effect is only supported on Android 12 and above. Attempts to use this Modifier on older Android versions will be ignored.

Usage of this API renders the corresponding composable into a separate graphics layer. Because the blurred content renders a larger area by the blur radius, this layer is explicitly clipped to the content bounds. It is recommended introduce additional space around the drawn content by the specified blur radius to remain within the content bounds.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.BlurredEdgeTreatment
import androidx.compose.ui.draw.blur
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box(
    Modifier.size(300.dp)
        // Blur content allowing the result to extend beyond the bounds of the original content
        .blur(30.dp, edgeTreatment = BlurredEdgeTreatment.Unbounded)
        .background(Color.Red, CircleShape)
)
 
import androidx.compose.foundation.Image
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.BlurredEdgeTreatment
import androidx.compose.ui.draw.blur
import androidx.compose.ui.res.painterResource
import androidx.compose.ui.unit.dp

Image(
    painter = painterResource(R.drawable.circus),
    contentDescription = "sample blurred image",
    // Blur content within the original bounds, clipping the result to a rounded rectangle
    modifier = Modifier.blur(30.dp, BlurredEdgeTreatment(RoundedCornerShape(5.dp))),
)
Parameters
radius: Dp

Radius of the blur along both the x and y axis
edgeTreatment: BlurredEdgeTreatment = BlurredEdgeTreatment.Rectangle

Strategy used to render pixels outside of bounds of the original input
See also
graphicsLayer

Example usage:

blur

Cmn 
fun Modifier.blur(
    radiusX: Dp,
    radiusY: Dp,
    edgeTreatment: BlurredEdgeTreatment = BlurredEdgeTreatment.Rectangle
): Modifier

Draw content blurred with the specified radii. Note this effect is only supported on Android 12 and above. Attempts to use this Modifier on older Android versions will be ignored.

Usage of this API renders the corresponding composable into a separate graphics layer. Because the blurred content renders a larger area by the blur radius, this layer is explicitly clipped to the content bounds. It is recommended introduce additional space around the drawn content by the specified blur radius to remain within the content bounds.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.BlurredEdgeTreatment
import androidx.compose.ui.draw.blur
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box(
    Modifier.size(300.dp)
        // Blur content allowing the result to extend beyond the bounds of the original content
        .blur(30.dp, edgeTreatment = BlurredEdgeTreatment.Unbounded)
        .background(Color.Red, CircleShape)
)
 
import androidx.compose.foundation.Image
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.BlurredEdgeTreatment
import androidx.compose.ui.draw.blur
import androidx.compose.ui.res.painterResource
import androidx.compose.ui.unit.dp

Image(
    painter = painterResource(R.drawable.circus),
    contentDescription = "sample blurred image",
    // Blur content within the original bounds, clipping the result to a rounded rectangle
    modifier = Modifier.blur(30.dp, BlurredEdgeTreatment(RoundedCornerShape(5.dp))),
)
Parameters
radiusX: Dp

Radius of the blur along the x axis
radiusY: Dp

Radius of the blur along the y axis
edgeTreatment: BlurredEdgeTreatment = BlurredEdgeTreatment.Rectangle

Strategy used to render pixels outside of bounds of the original input
See also
graphicsLayer

Example usage:

clip

Cmn 
fun Modifier.clip(shape: Shape): Modifier

Clip the content to shape.

Parameters
shape: Shape

the content will be clipped to this Shape.

clipToBounds

Cmn 
fun Modifier.clipToBounds(): Modifier

Clip the content to the bounds of a layer defined at this modifier.

drawBehind

Cmn 
fun Modifier.drawBehind(onDraw: DrawScope.() -> Unit): Modifier

Draw into a Canvas behind the modified content.

drawWithCache

Cmn 
fun Modifier.drawWithCache(onBuildDrawCache: CacheDrawScope.() -> DrawResult): Modifier

Draw into a DrawScope with content that is persisted across draw calls as long as the size of the drawing area is the same or any state objects that are read have not changed. In the event that the drawing area changes, or the underlying state values that are being read change, this method is invoked again to recreate objects to be used during drawing

For example, a androidx.compose.ui.graphics.LinearGradient that is to occupy the full bounds of the drawing area can be created once the size has been defined and referenced for subsequent draw calls without having to re-allocate.

import androidx.compose.foundation.layout.Box
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.drawWithCache
import androidx.compose.ui.geometry.Offset
import androidx.compose.ui.graphics.Brush
import androidx.compose.ui.graphics.Color

Box(
    Modifier.drawWithCache {
        val gradient =
            Brush.linearGradient(
                colors = listOf(Color.Red, Color.Blue),
                start = Offset.Zero,
                end = Offset(size.width, size.height),
            )
        onDrawBehind { drawRect(gradient) }
    }
)
 
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Box
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.drawWithCache
import androidx.compose.ui.geometry.Offset
import androidx.compose.ui.graphics.Brush
import androidx.compose.ui.graphics.Color

val colors1 = listOf(Color.Red, Color.Blue)
val colors2 = listOf(Color.Yellow, Color.Green)
var toggle by remember { mutableStateOf(true) }
Box(
    Modifier.clickable { toggle = !toggle }
        .drawWithCache {
            val gradient =
                Brush.linearGradient(
                    colors = if (toggle) colors1 else colors2,
                    start = Offset.Zero,
                    end = Offset(size.width, size.height),
                )
            onDrawBehind { drawRect(gradient) }
        }
)
 
import androidx.compose.foundation.Image
import androidx.compose.foundation.layout.requiredSize
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.drawWithCache
import androidx.compose.ui.geometry.Offset
import androidx.compose.ui.graphics.BlendMode
import androidx.compose.ui.graphics.Brush
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.SolidColor
import androidx.compose.ui.graphics.vector.Path
import androidx.compose.ui.graphics.vector.PathData
import androidx.compose.ui.graphics.vector.rememberVectorPainter
import androidx.compose.ui.unit.dp

val vectorPainter =
    rememberVectorPainter(24.dp, 24.dp, autoMirror = true) { viewportWidth, viewportHeight ->
        Path(
            pathData =
                PathData {
                    lineTo(viewportWidth, 0f)
                    lineTo(0f, viewportHeight)
                    close()
                },
            fill = SolidColor(Color.Black),
        )
    }
Image(
    painter = vectorPainter,
    contentDescription = null,
    modifier =
        Modifier.requiredSize(120.dp).drawWithCache {
            val gradient =
                Brush.linearGradient(
                    colors = listOf(Color.Red, Color.Blue),
                    start = Offset.Zero,
                    end = Offset(0f, size.height),
                )
            onDrawWithContent {
                drawContent()
                drawRect(gradient, blendMode = BlendMode.Plus)
            }
        },
)

drawWithContent

Cmn 
fun Modifier.drawWithContent(onDraw: ContentDrawScope.() -> Unit): Modifier

Creates a DrawModifier that allows the developer to draw before or after the layout's contents. It also allows the modifier to adjust the layout's canvas.

dropShadow

Cmn 
fun Modifier.dropShadow(shape: Shape, block: DropShadowScope.() -> Unit): Modifier

Draws a drop shadow behind the rest of the content with the geometry specified by the given shape and the shadow properties defined the DropShadowScope. This is different than Modifier.shadow as this does not introduce a graphicsLayer to render elevation based shadows. This shadow is rendered without a single light source and will render consistently regardless of the on screen position of the content. This is similar to Modifier.dropShadow except that specification of drop shadow parameters is done with the lambda with DropShadowScope allows for more efficient transformations for animated use cases without recomposition.

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.dropShadow
import androidx.compose.ui.graphics.RectangleShape
import androidx.compose.ui.graphics.shadow.Shadow
import androidx.compose.ui.unit.dp

Box(Modifier.size(100.dp, 100.dp).dropShadow(RectangleShape, Shadow(12.dp)))
Parameters
shape: Shape

Geometry of the shadow
block: DropShadowScope.() -> Unit

DropShadowScope block where shadow properties are defined

dropShadow

Cmn 
fun Modifier.dropShadow(shape: Shape, shadow: Shadow): Modifier

Draws a drop shadow behind the rest of the content with the geometry specified by the given shape and the shadow properties defined by the Shadow. This is different than Modifier.shadow as this does not introduce a graphicsLayer to render elevation based shadows. This shadow is rendered without a single light source and will render consistently regardless of the on screen position of the content.

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.dropShadow
import androidx.compose.ui.graphics.RectangleShape
import androidx.compose.ui.graphics.shadow.Shadow
import androidx.compose.ui.unit.dp

Box(Modifier.size(100.dp, 100.dp).dropShadow(RectangleShape, Shadow(12.dp)))
Parameters
shape: Shape

Geometry of the shadow
shadow: Shadow

Properties of the shadow like radius, spread, offset, and fill properties like the color or brush

innerShadow

Cmn 
fun Modifier.innerShadow(shape: Shape, block: InnerShadowScope.() -> Unit): Modifier

Draws an inner shadow behind the rest of the content with the geometry specified by the given shape and the shadow properties defined the InnerShadowScope. This is different than Modifier.shadow as this does not introduce a graphicsLayer to render elevation based shadows. This shadow is rendered without a single light source and will render consistently regardless of the on screen position of the content. This is similar to Modifier.innerShadow except that specification of inner shadow parameters is done with the lambda with InnerShadowScope allows for more efficient transformations for animated use cases without recomposition.

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.innerShadow
import androidx.compose.ui.graphics.RectangleShape
import androidx.compose.ui.graphics.shadow.Shadow
import androidx.compose.ui.unit.dp

Box(Modifier.size(100.dp, 100.dp).innerShadow(RectangleShape, Shadow(12.dp)))
Parameters
shape: Shape

Geometry of the shadow
block: InnerShadowScope.() -> Unit

InnerShadowScope block where shadow properties are defined

innerShadow

Cmn 
fun Modifier.innerShadow(shape: Shape, shadow: Shadow): Modifier

Draws an inner shadow on top of the rest of the content with the geometry specified by the given shape and the shadow properties defined by the Shadow. This is different than Modifier.shadow as this does not introduce a graphicsLayer to render elevation based shadows. Additionally this shadow will render only within the geometry and can be used to provide a recessed like visual effect. This shadow is rendered without a single light source and will render consistently regardless of the on screen position of the content.

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.innerShadow
import androidx.compose.ui.graphics.RectangleShape
import androidx.compose.ui.graphics.shadow.Shadow
import androidx.compose.ui.unit.dp

Box(Modifier.size(100.dp, 100.dp).innerShadow(RectangleShape, Shadow(12.dp)))
Parameters
shape: Shape

Geometry of the shadow
shadow: Shadow

Properties of the shadow like radius, spread, offset, and fill properties like the color or brush

paint

Cmn 
fun Modifier.paint(
    painter: Painter,
    sizeToIntrinsics: Boolean = true,
    alignment: Alignment = Alignment.Center,
    contentScale: ContentScale = ContentScale.Inside,
    alpha: Float = DefaultAlpha,
    colorFilter: ColorFilter? = null
): Modifier

Paint the content using painter.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.padding
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.paint
import androidx.compose.ui.geometry.Size
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.drawscope.DrawScope
import androidx.compose.ui.graphics.painter.Painter
import androidx.compose.ui.unit.dp

class CustomPainter : Painter() {

    override val intrinsicSize: Size
        get() = Size(300.0f, 300.0f)

    override fun DrawScope.onDraw() {
        drawCircle(center = center, radius = size.minDimension / 2.0f, color = Color.Red)
    }
}

Box(
    modifier =
        Modifier.background(color = Color.Gray)
            .padding(30.dp)
            .background(color = Color.Yellow)
            .paint(CustomPainter())
) {
    /** intentionally empty */
}
Parameters
painter: Painter

Painter to be drawn by this Modifier
sizeToIntrinsics: Boolean = true

true to size the element relative to Painter.intrinsicSize
alignment: Alignment = Alignment.Center

specifies alignment of the painter relative to content
contentScale: ContentScale = ContentScale.Inside

strategy for scaling painter if its size does not match the content size
alpha: Float = DefaultAlpha

opacity of painter
colorFilter: ColorFilter? = null

optional ColorFilter to apply to painter

rotate

Cmn 
fun Modifier.rotate(degrees: Float): Modifier

Sets the degrees the view is rotated around the center of the composable. Increasing values result in clockwise rotation. Negative degrees are used to rotate in the counter clockwise direction

Usage of this API renders this composable into a separate graphics layer.

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.rotate
import androidx.compose.ui.unit.dp

Box(Modifier.rotate(45f).size(100.dp, 100.dp))
See also
graphicsLayer

Example usage:

scale

Cmn 
fun Modifier.scale(scale: Float): Modifier

Scale the contents of both the horizontal and vertical axis uniformly by the same scale factor.

Usage of this API renders this composable into a separate graphics layer

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.scale
import androidx.compose.ui.unit.dp

Box(Modifier.scale(2f).size(100.dp, 100.dp))
Parameters
scale: Float

Multiplier to scale content along the horizontal and vertical axis
See also
graphicsLayer

Example usage:

scale

Cmn 
fun Modifier.scale(scaleX: Float, scaleY: Float): Modifier

Scale the contents of the composable by the following scale factors along the horizontal and vertical axis respectively. Negative scale factors can be used to mirror content across the corresponding horizontal or vertical axis.

Example usage:

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.scale
import androidx.compose.ui.unit.dp

Box(Modifier.scale(scaleX = 2f, scaleY = 3f).size(100.dp, 100.dp))

Usage of this API renders this composable into a separate graphics layer

Parameters
scaleX: Float

Multiplier to scale content along the horizontal axis
scaleY: Float

Multiplier to scale content along the vertical axis
See also
graphicsLayer

shadow

Cmn 
fun Modifier.shadow(
    elevation: Dp,
    shape: Shape = RectangleShape,
    clip: Boolean = elevation > 0.dp,
    ambientColor: Color = DefaultShadowColor,
    spotColor: Color = DefaultShadowColor
): Modifier

Creates a graphicsLayer that draws a shadow. The elevation defines the visual depth of the physical object. The physical object has a shape specified by shape.

If the passed shape is concave the shadow will not be drawn on Android versions less than 10.

Note that elevation is only affecting the shadow size and doesn't change the drawing order. Use a androidx.compose.ui.zIndex modifier if you want to draw the elements with larger elevation after all the elements with a smaller one.

Note that this parameter is only supported on Android 9 (Pie) and above. On older versions, this property always returns Color.Black and setting new values is ignored.

Usage of this API renders this composable into a separate graphics layer

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.shadow
import androidx.compose.ui.graphics.RectangleShape
import androidx.compose.ui.unit.dp

Box(Modifier.shadow(12.dp, RectangleShape).size(100.dp, 100.dp))
Parameters
elevation: Dp

The elevation for the shadow in pixels
shape: Shape = RectangleShape

Defines a shape of the physical object
clip: Boolean = elevation > 0.dp

When active, the content drawing clips to the shape.
ambientColor: Color = DefaultShadowColor

Color of the ambient shadow drawn when elevation 0f
spotColor: Color = DefaultShadowColor

Color of the spot shadow that is drawn when elevation 0f
See also
graphicsLayer

Example usage: