Class

DrawAnnotation

Attaches custom draw-phase rendering behind or over a text range.

Source set: Common
public abstract class DrawAnnotation : Annotation

Attaches custom draw-phase rendering behind or over a text range.

Runs during the Compose draw phase with access to DrawAnnotationScope.textLayoutResult and the resolved `start, end) offsets ([DrawAnnotationScope.start and DrawAnnotationScope.end) so callbacks can query per-line bounding boxes via TextLayoutResult.getBoundingBoxesForRange or contour paths via TextLayoutResult.fillPathForRange. Unlike SpanStyle.background, updating or animating state read inside drawBehind or drawOver` only invalidates drawing without triggering text measurement or relayout.

Subclassing and State Guidelines

    DrawAnnotation as a top-level data class or data object holding only primitive or immutable graphics parameters so structural equals and hashCode are generated automatically. On Android, annotating a data class subclass with @Parcelize and implementing Parcelable allows AnnotatedString.Saver (for example, when saving an AnnotatedString via rememberSaveable(stateSaver = AnnotatedString.Saver)) to persist and restore the annotation across configuration changes and process death. Note that system clipboard copy/paste converts text through platform Spanned representations and does not transport DrawAnnotation instances.

  • Prefer data class or data object subclasses: Reusable decorations should subclass
  • ranges, shared across multiple Text layouts, or split across sub-ranges when AnnotatedString.subSequence slices text. Hold a reusable Path instance in a private field and pass it as target to TextLayoutResult.fillPathForRange to avoid allocating a Path on each draw pass; TextLayoutResult caches the per-range bounding boxes internally.

  • Instance reuse and caching: DrawAnnotation implementations may be shared across multiple
  • ViewModels or long-lived state holders. Avoid non-static inner class subclasses or properties that retain View, Context, or ViewModel references.

  • Avoid capturing heavy references: AnnotatedString instances are frequently cached in
  • draw phase and is opaque to accessibility services, clipboard copy, and HTML export. Represent semantic meaning alongside DrawAnnotation using SpanStyle, TtsAnnotation, LinkAnnotation, or StringAnnotation.

  • Visual-only decoration: DrawAnnotation executes imperative canvas commands during the

For standard rounded background fills and borders, use BackgroundAnnotation. For one-off inline decorations, use the DrawAnnotation factory function.

Functions

drawBehind

Source set: Common
public open fun DrawAnnotationScope.drawBehind()

Invoked before the text glyphs are painted. The receiver DrawAnnotationScope is aligned with the text layout origin and provides DrawAnnotationScope.textLayoutResult, DrawAnnotationScope.start, and DrawAnnotationScope.end to query geometry for the annotated range.

drawOver

Source set: Common
public open fun DrawAnnotationScope.drawOver()

Invoked after the text glyphs are painted. The receiver DrawAnnotationScope is aligned with the text layout origin and provides DrawAnnotationScope.textLayoutResult, DrawAnnotationScope.start, and DrawAnnotationScope.end to query geometry for the annotated range.

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: