# BackgroundAnnotation

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

## Code Examples

### BackgroundAnnotationSample

```kotlin
@Sampled
@Composable
fun BackgroundAnnotationSample() {
    val text = remember {
        buildAnnotatedString {
            append("Use ")
            withDrawAnnotation(
                BackgroundAnnotation(
                    color = Color.Cyan.copy(alpha = 0.2f),
                    cornerRadius = 6.dp,
                    spread = SpreadValues(horizontal = 4.dp, vertical = 2.dp),
                    border = BackgroundAnnotation.Border(width = 1.dp, color = Color.Blue),
                )
            ) {
                append("BackgroundAnnotation")
            }
            append(" to draw rounded backgrounds and borders.")
        }
    }
    BasicText(text = text)
}
```

### BackgroundAnnotationSpreadSample

```kotlin
@Sampled
@Composable
fun BackgroundAnnotationSpreadSample() {
    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))
}
```

### BackgroundAnnotationColorProducerSample

```kotlin
@Sampled
@Composable
fun BackgroundAnnotationColorProducerSample() {
    val transition = rememberInfiniteTransition(label = "highlight")
    val animatedColor by
        transition.animateColor(
            initialValue = Color.Cyan.copy(alpha = 0.2f),
            targetValue = Color.Cyan.copy(alpha = 0.6f),
            animationSpec = infiniteRepeatable(tween(1000), RepeatMode.Reverse),
            label = "highlightColor",
        )
    val text = remember {
        buildAnnotatedString {
            append("Animate ")
            withDrawAnnotation(
                BackgroundAnnotation(
                    colorProducer = { animatedColor },
                    cornerRadius = 6.dp,
                    spread = SpreadValues(horizontal = 4.dp, vertical = 2.dp),
                )
            ) {
                append("draw-phase color")
            }
            append(" without recomposing or re-measuring text.")
        }
    }
    BasicText(text = text)
}
```

### BackgroundAnnotationBrushSample

```kotlin
@Sampled
@Composable
fun BackgroundAnnotationBrushSample() {
    val gradientBrush = remember {
        Brush.horizontalGradient(
            colors =
                listOf(
                    Color.Cyan.copy(alpha = 0.3f),
                    Color.Magenta.copy(alpha = 0.3f),
                    Color.Red.copy(alpha = 0.3f),
                )
        )
    }
    val borderGradientBrush = remember {
        Brush.horizontalGradient(colors = listOf(Color.Blue, Color.Magenta))
    }
    val text = remember {
        buildAnnotatedString {
            append("Use a ")
            withDrawAnnotation(
                BackgroundAnnotation(
                    brush = gradientBrush,
                    cornerRadius = 6.dp,
                    spread = SpreadValues(horizontal = 4.dp, vertical = 2.dp),
                    border = BackgroundAnnotation.Border(width = 1.dp, brush = borderGradientBrush),
                )
            ) {
                append("gradient Brush background")
            }
            append(" with a matching gradient border.")
        }
    }
    BasicText(text = text)
}
```
