androidx.compose.ui.draw

Common/All

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

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

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

Cmn

Extension functions summary

Modifier	Modifier.alpha(alpha: Float) 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	Modifier.clip(shape: Shape) Clip the content to shape.	Cmn
Modifier	Modifier.clipToBounds() Clip the content to the bounds of a layer defined at this modifier.	Cmn
Modifier	Modifier.drawBehind(onDraw: DrawScope.() -> Unit) Draw into a Canvas behind the modified content.	Cmn
Modifier	Modifier.drawWithCache(onBuildDrawCache: CacheDrawScope.() -> DrawResult) 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	Modifier.drawWithContent(onDraw: ContentDrawScope.() -> Unit) Creates a DrawModifier that allows the developer to draw before or after the layout's contents.	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	Modifier.scale(scale: Float) 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

Artifact: androidx.compose.ui:ui

View Source

Added in 1.5.0

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

Extension functions

alpha

Cmn

Artifact: androidx.compose.ui:ui

View Source

Added in 1.0.0

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

Artifact: androidx.compose.ui:ui

View Source

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

Artifact: androidx.compose.ui:ui

View Source

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

Artifact: androidx.compose.ui:ui

View Source

Added in 1.0.0

fun Modifier.clip(shape: Shape): Modifier

Clip the content to shape.

Parameters
shape: Shape	the content will be clipped to this Shape.

clipToBounds

Cmn

Artifact: androidx.compose.ui:ui

View Source

Added in 1.0.0

fun Modifier.clipToBounds(): Modifier

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

drawBehind

Cmn

Artifact: androidx.compose.ui:ui

View Source

Added in 1.0.0

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

Draw into a Canvas behind the modified content.

drawWithCache

Cmn

Artifact: androidx.compose.ui:ui

View Source

Added in 1.0.0

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

Artifact: androidx.compose.ui:ui

View Source

Added in 1.0.0

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.

paint

Cmn

Artifact: androidx.compose.ui:ui

View Source

Added in 1.0.0

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

Artifact: androidx.compose.ui:ui

View Source

Added in 1.0.0

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

Artifact: androidx.compose.ui:ui

View Source

Added in 1.0.0

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

Artifact: androidx.compose.ui:ui

View Source

Added in 1.0.0

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

Artifact: androidx.compose.ui:ui

View Source

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: