BorderRenderer provides rendering and caching logic for drawing borders inside a DrawScope.

BorderRenderer provides the same border drawing that androidx.compose.foundation.border uses so you can draw borders from any drawing context, such as a androidx.compose.ui.node.DrawModifierNode. This can be useful when you need to render multiple inset borders at once, or efficiently animate borders. For simple cases you can continue to use androidx.compose.foundation.border.

Borders drawn with BorderRenderer are internal borders - they grow inwards as the border width increases.

BorderRenderer contains caches to efficiently draw borders over time. As a result, make sure to:

  • Reuse the same BorderRenderer instance each time you draw the border

  • Use a separate instance for each border that is drawn at the same time. For example, if you want to draw two borders, inset from each other, each border should have its own BorderRenderer. See the samples for more information.

Drawing a border from inside a androidx.compose.ui.node.DrawModifierNode:

import androidx.compose.foundation.BorderRenderer
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Brush
import androidx.compose.ui.graphics.Shape
import androidx.compose.ui.graphics.drawscope.ContentDrawScope
import androidx.compose.ui.graphics.layer.GraphicsLayer
import androidx.compose.ui.node.DrawModifierNode
import androidx.compose.ui.node.requireGraphicsContext
import androidx.compose.ui.unit.Dp

// Note: you may need to implement semantics here, depending on your use case.
class SimpleBorderNode(var width: Dp, var brush: Brush, var shape: Shape) :
    Modifier.Node(), DrawModifierNode {
    // The GraphicsLayer is only created if the BorderRenderer needs one, and is released when
    // the node is detached.
    private var graphicsLayer: GraphicsLayer? = null

    // Keep the same BorderRenderer across draws so it can reuse its drawing resources.
    private val borderRenderer = BorderRenderer {
        graphicsLayer
            ?: requireGraphicsContext().createGraphicsLayer().also { graphicsLayer = it }
    }

    override fun ContentDrawScope.draw() {
        drawContent()
        borderRenderer.drawBorder(
            drawScope = this,
            width = width,
            brush = brush,
            outline = shape.createOutline(size, layoutDirection, this),
        )
    }

    override fun onDetach() {
        graphicsLayer?.let { requireGraphicsContext().releaseGraphicsLayer(it) }
        graphicsLayer = null
    }
}

Drawing two borders inset from each other (using separate BorderRenderers):

import androidx.compose.foundation.BorderRenderer
import androidx.compose.foundation.shape.CutCornerShape
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Brush
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.Shape
import androidx.compose.ui.graphics.SolidColor
import androidx.compose.ui.graphics.drawscope.ContentDrawScope
import androidx.compose.ui.graphics.drawscope.inset
import androidx.compose.ui.graphics.layer.GraphicsLayer
import androidx.compose.ui.node.DrawModifierNode
import androidx.compose.ui.node.requireGraphicsContext
import androidx.compose.ui.unit.dp

// Note: you may need to implement semantics here, depending on your use case.
class DoubleBorderNode : Modifier.Node(), DrawModifierNode {
    private val borderWidth = 2.dp
    // 2.dp between the inner edge of the outer border and the outer edge of the inner border
    private val innerBorderInset = borderWidth + 2.dp
    private val outerBrush = SolidColor(Color.Black)
    private val innerBrush = Brush.linearGradient(listOf(Color.Magenta, Color.Cyan))
    private val shape = CutCornerShape(8.dp)

    // Each border needs its own GraphicsLayer, as both may be used in the same draw.
    private var outerGraphicsLayer: GraphicsLayer? = null
    private var innerGraphicsLayer: GraphicsLayer? = null

    // Use a separate BorderRenderer for each border, so that each one can reuse its own
    // drawing resources across draws.
    private val outerBorderRenderer = BorderRenderer {
        outerGraphicsLayer
            ?: requireGraphicsContext().createGraphicsLayer().also { outerGraphicsLayer = it }
    }
    private val innerBorderRenderer = BorderRenderer {
        innerGraphicsLayer
            ?: requireGraphicsContext().createGraphicsLayer().also { innerGraphicsLayer = it }
    }

    override fun ContentDrawScope.draw() {
        drawContent()
        val outerOutline = shape.createOutline(size, layoutDirection, this)
        // Draw the outer border at the edge
        outerBorderRenderer.drawBorder(
            drawScope = this,
            width = borderWidth,
            brush = outerBrush,
            outline = outerOutline,
        )
        val inset = innerBorderInset.toPx()
        // Draw the inner border inset from the outer border
        inset(inset) {
            // The size in this scope is already inset, so this outline will be smaller
            val innerOutline = shape.createOutline(size, layoutDirection, this)
            innerBorderRenderer.drawBorder(
                drawScope = this,
                width = borderWidth,
                brush = innerBrush,
                outline = innerOutline,
            )
        }
    }

    override fun onDetach() {
        outerGraphicsLayer?.let { requireGraphicsContext().releaseGraphicsLayer(it) }
        innerGraphicsLayer?.let { requireGraphicsContext().releaseGraphicsLayer(it) }
        outerGraphicsLayer = null
        innerGraphicsLayer = null
    }
}

Summary

Public constructors

@RememberInComposition
BorderRenderer(onProvideGraphicsLayer: () -> GraphicsLayer)
Cmn

Public functions

Unit
drawBorder(drawScope: DrawScope, width: Dp, brush: Brush, outline: Outline)

Draws a border defined by outline, with width and brush, into drawScope.

Cmn

Public constructors

BorderRenderer

@RememberInComposition
BorderRenderer(onProvideGraphicsLayer: () -> GraphicsLayer)
Parameters
onProvideGraphicsLayer: () -> GraphicsLayer

Provides a GraphicsLayer needed for rendering certain borders. This lambda will be invoked when needed, and may be invoked multiple times. As a result make sure to cache / return the same valid GraphicsLayer to avoid creating many layers. This GraphicsLayer should not be used by any other BorderRenderer instances or drawing code at the same time. The caller is responsible for its lifecycle - make sure to call androidx.compose.ui.graphics.GraphicsContext.releaseGraphicsLayer when you no longer need it (such as when a Modifier.Node using this is detached). If you release the layer, make sure to return a new valid GraphicsLayer when this is called again (if the node is re-attached later). See the samples for example usage.

Public functions

drawBorder

fun drawBorder(drawScope: DrawScope, width: Dp, brush: Brush, outline: Outline): Unit

Draws a border defined by outline, with width and brush, into drawScope. The border will be drawn using the size defined by outline, not DrawScope.size. Borders drawn are internal borders (drawn within the bounding box, not outside), and grow inwards as width increases.

To modify the drawn border you can use DrawScope transformation APIs such as translate, just as for any other drawing commands.

To draw several different borders at the same time, use a separate BorderRenderer for each one.

import androidx.compose.foundation.BorderRenderer
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Brush
import androidx.compose.ui.graphics.Shape
import androidx.compose.ui.graphics.drawscope.ContentDrawScope
import androidx.compose.ui.graphics.layer.GraphicsLayer
import androidx.compose.ui.node.DrawModifierNode
import androidx.compose.ui.node.requireGraphicsContext
import androidx.compose.ui.unit.Dp

// Note: you may need to implement semantics here, depending on your use case.
class SimpleBorderNode(var width: Dp, var brush: Brush, var shape: Shape) :
    Modifier.Node(), DrawModifierNode {
    // The GraphicsLayer is only created if the BorderRenderer needs one, and is released when
    // the node is detached.
    private var graphicsLayer: GraphicsLayer? = null

    // Keep the same BorderRenderer across draws so it can reuse its drawing resources.
    private val borderRenderer = BorderRenderer {
        graphicsLayer
            ?: requireGraphicsContext().createGraphicsLayer().also { graphicsLayer = it }
    }

    override fun ContentDrawScope.draw() {
        drawContent()
        borderRenderer.drawBorder(
            drawScope = this,
            width = width,
            brush = brush,
            outline = shape.createOutline(size, layoutDirection, this),
        )
    }

    override fun onDetach() {
        graphicsLayer?.let { requireGraphicsContext().releaseGraphicsLayer(it) }
        graphicsLayer = null
    }
}
Parameters
drawScope: DrawScope

The DrawScope to draw the border into.

width: Dp

The width of the border in Dp.

brush: Brush

The Brush to paint the border with.

outline: Outline

The Outline of the border.