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:
mergeLines = true(default): Overlapping boxes on adjacent lines merge into a single shape.mergeLines = false: Each line is drawn as a separate rounded rectangle. A negative vertical
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.
spread (for example, SpreadValues(vertical = (-2).dp)) shrinks each box's top and bottom edges to leave a gap between lines.
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
override fun DrawAnnotationScope.drawBehind()
equals
override fun equals(other: Any?): Boolean
hashCode
override fun hashCode(): Int
toString
override fun toString(): String
Members
SpreadValues
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:
- Neighboring characters on the same line whose horizontal bounds touch or overlap are merged
- Multi-line ranges and bidirectional text ranges that split into separate visual runs on the
into a single box spanning the line's `top, bottom`.
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 - Negative vertical spread (for example,
SpreadValues(vertical = (-2).dp)): when - Positive vertical spread expands the top and bottom edges outward past the line bounds (on
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.
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.
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.
Functions
equals
override fun equals(other: Any?): Boolean
Creates SpreadValues with all four edges spread by the same amount.
hashCode
override fun hashCode(): Int
Members
Companion
public companion object
Properties
Zero
public val Zero: SpreadValues = SpreadValues(0.dp, 0.dp, 0.dp, 0.dp)
A SpreadValues with 0.dp spread on all four edges.
Border
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
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
override fun hashCode(): Int
toString
override fun toString(): String