Class

BackgroundAnnotation

Draws a filled background and optional Border behind an annotated text range.

Source set: Common
public class BackgroundAnnotation private constructor(
    public val color: Color = Color.Unspecified,
    public val colorProducer: ColorProducer? = null,
    public val brush: Brush? = null,
    public val cornerRadius: Dp = DefaultCornerRadius,
    public val spread: SpreadValues = DefaultSpread,
    @get:Suppress("GetterSetterNames") public val mergeLines: Boolean = DefaultMergeLines,
    public val border: Border? = null,
    public val alpha: Float = DefaultAlpha,
) : DrawAnnotation()

Draws a filled background and optional Border behind an annotated text range.

Use BackgroundAnnotation instead of SpanStyle.background to draw rounded multi-line highlights, inline pills with Borders, or draw-phase color and brush animations without triggering text measurement or relayout.

How multi-line ranges are drawn depends on mergeLines:

    Vertical spread applies only to the top of the first line and the bottom of the last line, keeping the inner seams between lines connected.

  • mergeLines = true (default): Overlapping boxes on adjacent lines merge into a single shape.
  • spread (for example, SpreadValues(vertical = (-2).dp)) shrinks each box's top and bottom edges to leave a gap between lines.

  • mergeLines = false: Each line is drawn as a separate rounded rectangle. A negative vertical
mergeLines = true (unified contour):    mergeLines = false (per-line pills):
.----------.                            .----------.
Hello, | world    |                     Hello, | world    |
.------'   .------'                            '----------'
| again    | now.                       .----------.
'----------'                            | again    | now.
'----------'

Note: AnnotatedString.Saver does not save or restore BackgroundAnnotation instances.

Functions

drawBehind

Source set: Common
override fun DrawAnnotationScope.drawBehind()

equals

Source set: Common
override fun equals(other: Any?): Boolean

hashCode

Source set: Common
override fun hashCode(): Int

toString

Source set: Common
override fun toString(): String

Members

SpreadValues

Source set: Common
public class SpreadValues(
        public val left: Dp = 0.dp,
        public val top: Dp = 0.dp,
        public val right: Dp = 0.dp,
        public val bottom: Dp = 0.dp,
    )

Per-edge Dp spread applied to a text range's bounding boxes during the draw phase.

Spread applies to the per-line boxes returned by TextLayoutResult.getBoundingBoxesForRange, rather than to each glyph individually:

    into a single box spanning the line's `top, bottom`.

  • Neighboring characters on the same line whose horizontal bounds touch or overlap are merged
  • same line produce one box per run.

  • Multi-line ranges and bidirectional text ranges that split into separate visual runs on the

By default (SpreadValues.Zero), each box spans the full line height (`top, bottom) and fits tightly around the glyphs horizontally. Configure BackgroundAnnotation.spread with SpreadValues` to adjust those bounds at draw time without shifting text layout:

    left and right edges outward to add space between the first or last glyph and a pill's border or rounded corners. If horizontal expansion causes two separate boxes on the same line to touch or overlap, they are merged into a single box.

  • Positive horizontal spread (for example, SpreadValues(horizontal = 4.dp)) expands the
  • BackgroundAnnotation.mergeLines is false, shrinks each per-line box's top and bottom edges inward from the line bounds so pills on consecutive lines have a vertical gap instead of touching; when BackgroundAnnotation.mergeLines is true, shrinks only the outer top of the first line and outer bottom of the last line of each merged stack while inner line seams remain joined as a continuous contour.

  • Negative vertical spread (for example, SpreadValues(vertical = (-2).dp)): when
  • each per-line box when mergeLines = false, or on the outer top and bottom of each merged stack when mergeLines = true).

  • Positive vertical spread expands the top and bottom edges outward past the line bounds (on

If negative spread values reduce a box's width or height (or a merged line stack's height) to <= 0, that box or stack is omitted and not drawn.

Functions

equals

Source set: Common
override fun equals(other: Any?): Boolean

Creates SpreadValues with all four edges spread by the same amount.

hashCode

Source set: Common
override fun hashCode(): Int

Members

Companion

Source set: Common
public companion object

Properties

Zero

Source set: Common
public val Zero: SpreadValues = SpreadValues(0.dp, 0.dp, 0.dp, 0.dp)

A SpreadValues with 0.dp spread on all four edges.

Border

Source set: Common
public class Border private constructor(
        public val width: Dp,
        public val color: Color,
        public val colorProducer: ColorProducer?,
        public val brush: Brush?,
    )

Border stroke specification for BackgroundAnnotation.

Equivalent to BorderStroke in androidx.compose.foundation (which ui-text does not depend on), with an additional ColorProducer overload for draw-phase color animations.

Drawn as a centered stroke along the background contour: half of width extends outside the contour (past spread) and half overlaps inside the fill.

Functions

equals

Source set: Common
override fun equals(other: Any?): Boolean

Creates a Border with a stroke width painted with a brush.

Parameters

width stroke width, or Dp.Hairline for a single-pixel hairline stroke
brush stroke brush applied to the contour border

hashCode

Source set: Common
override fun hashCode(): Int

toString

Source set: Common
override fun toString(): String
Jetpack Compose beyond MaterialFree components, screens and templates for apps that don’t look like Google’s. Copy them into your app, or let your coding agent add them.Browse for free

Content updated: