BackgroundAnnotation.SpreadValues


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:

  • Neighboring characters on the same line whose horizontal bounds touch or overlap are merged into a single box spanning the line's [top, bottom].

  • Multi-line ranges and bidirectional text ranges that split into separate visual runs on the same line produce one box per run.

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:

  • Positive horizontal spread (for example, SpreadValues(horizontal = 4.dp)) expands the 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.

  • Negative vertical spread (for example, SpreadValues(vertical = (-2).dp)): when 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.

  • Positive vertical spread expands the top and bottom edges outward past the line bounds (on each per-line box when mergeLines = false, or on the outer top and bottom of each merged stack when mergeLines = true).

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.

import androidx.compose.foundation.text.BasicText
import androidx.compose.runtime.remember
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.BackgroundAnnotation
import androidx.compose.ui.text.BackgroundAnnotation.SpreadValues
import androidx.compose.ui.text.DrawAnnotation
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.buildAnnotatedString
import androidx.compose.ui.text.withDrawAnnotation
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

val text = remember {
    buildAnnotatedString {
        append("Use positive horizontal and negative vertical ")
        withDrawAnnotation(
            BackgroundAnnotation(
                color = Color.Cyan.copy(alpha = 0.25f),
                cornerRadius = 6.dp,
                // Positive horizontal spread adds side space around the glyphs;
                // negative vertical spread shrinks from the line top/bottom so wrapped pills
                // on consecutive lines stay visually separated instead of touching.
                spread = SpreadValues(horizontal = 4.dp, vertical = (-2).dp),
                mergeLines = false,
                border = BackgroundAnnotation.Border(width = 1.dp, color = Color.Blue),
            )
        ) {
            append("SpreadValues on multi-line per-line pills")
        }
        append(" so adjacent lines do not touch.")
    }
}
BasicText(text = text, style = TextStyle(fontSize = 16.sp, lineHeight = 24.sp))

Summary

Public companion properties

BackgroundAnnotation.SpreadValues

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

Cmn

Public constructors

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

Cmn
SpreadValues(horizontal: Dp, vertical: Dp)

Creates SpreadValues with symmetric horizontal (left and right) and vertical (top and bottom) spread amounts.

Cmn
SpreadValues(left: Dp, top: Dp, right: Dp, bottom: Dp)
Cmn

Public functions

open operator Boolean
equals(other: Any?)
Cmn
open Int
Cmn
open String
Cmn

Public properties

Dp

spread applied to the visual bottom edge of each box, or the outer bottom edge of each merged stack when BackgroundAnnotation.mergeLines is true (positive expands outward, negative shrinks inward); defaults to 0.dp

Cmn
Dp

spread applied to the visual left edge of each per-line bounding box (positive expands outward, negative shrinks inward); defaults to 0.dp

Cmn
Dp

spread applied to the visual right edge of each per-line bounding box (positive expands outward, negative shrinks inward); defaults to 0.dp

Cmn
Dp

spread applied to the visual top edge of each box, or the outer top edge of each merged stack when BackgroundAnnotation.mergeLines is true (positive expands outward, negative shrinks inward); defaults to 0.dp

Cmn

Public companion properties

Zero

val Zero: BackgroundAnnotation.SpreadValues

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

Public constructors

SpreadValues

SpreadValues(all: Dp)

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

SpreadValues

SpreadValues(horizontal: Dp = 0.dp, vertical: Dp = 0.dp)

Creates SpreadValues with symmetric horizontal (left and right) and vertical (top and bottom) spread amounts.

Parameters
horizontal: Dp = 0.dp

spread applied to left and right (positive expands outward, negative shrinks inward); defaults to 0.dp

vertical: Dp = 0.dp

spread applied to top and bottom (positive expands outward, negative shrinks inward); defaults to 0.dp

SpreadValues

SpreadValues(left: Dp = 0.dp, top: Dp = 0.dp, right: Dp = 0.dp, bottom: Dp = 0.dp)

Public functions

equals

open operator fun equals(other: Any?): Boolean

hashCode

open fun hashCode(): Int

toString

open fun toString(): String

Public properties

bottom

val bottom: Dp

spread applied to the visual bottom edge of each box, or the outer bottom edge of each merged stack when BackgroundAnnotation.mergeLines is true (positive expands outward, negative shrinks inward); defaults to 0.dp

left

val left: Dp

spread applied to the visual left edge of each per-line bounding box (positive expands outward, negative shrinks inward); defaults to 0.dp

right

val right: Dp

spread applied to the visual right edge of each per-line bounding box (positive expands outward, negative shrinks inward); defaults to 0.dp

top

val top: Dp

spread applied to the visual top edge of each box, or the outer top edge of each merged stack when BackgroundAnnotation.mergeLines is true (positive expands outward, negative shrinks inward); defaults to 0.dp