---
title: "AnnotatedString"
description: "The basic data structure of text with multiple styles. To construct an [AnnotatedString] you can
use [Builder]."
type: "class"
---
Class
Common
```kotlin
class AnnotatedString
internal constructor(internal val annotations: List>?, val text: String) :
CharSequence
```
The basic data structure of text with multiple styles. To construct an `AnnotatedString` you can
use `Builder`.
## Secondary Constructors
```kotlin
constructor(
text: String,
spanStyles: List> = listOf(),
paragraphStyles: List> = listOf(),
) : this(constructAnnotationsFromSpansAndParagraphs(spanStyles, paragraphStyles), text)
```
The basic data structure of text with multiple styles. To construct an `AnnotatedString` you
can use `Builder`.
If you need to provide other types of `Annotation`s, use an alternative constructor.
#### Parameters
| | |
| --- | --- |
| text | the text to be displayed. |
| spanStyles | a list of `Range`s that specifies `SpanStyle`s on certain portion of the text. These styles will be applied in the order of the list. And the `SpanStyle`s applied later can override the former styles. Notice that `SpanStyle` attributes which are null or unspecified won't change the current ones. |
| paragraphStyles | a list of `Range`s that specifies `ParagraphStyle`s on certain portion of the text. Each `ParagraphStyle` with a `Range` defines a paragraph of text. It's required that `Range`s of paragraphs don't overlap with each other. If there are gaps between specified paragraph `Range`s, a default paragraph will be created in between. |
```kotlin
constructor(
text: String,
annotations: List> = listOf(),
) : this(annotations.ifEmpty { null }, text)
```
The basic data structure of text with multiple styles and other annotations. To construct an
`AnnotatedString` you may use a `Builder`.
- `Annotation`s applied later can override the former annotations. For example, the attributes of the last applied `SpanStyle` will override similar attributes of the previously applied `SpanStyle`s.
- `SpanStyle` attributes which are null or Unspecified won't change the styling.
- If there are gaps between specified paragraph `Range`s, a default paragraph will be created in between.
- The paragraph `Range`s can't partially overlap. They must either not overlap at all, be nested (when inner paragraph's range is fully within the range of the outer paragraph) or fully overlap (when ranges of two paragraph are the same). For more details check the `AnnotatedString.Builder.addStyle` documentation.
#### Parameters
| | |
| --- | --- |
| text | the text to be displayed. |
| annotations | a list of `Range`s that specifies `Annotation`s on certain portion of the text. These annotations will be applied in the order of the list. There're a few properties that these annotations have: |
## Properties
Common
```kotlin
val spanStyles: List>
```
All `SpanStyle` that have been applied to a range of this String
Common
```kotlin
val paragraphStyles: List>
```
All `ParagraphStyle` that have been applied to a range of this String
## Functions
```kotlin
fun subSequence(range: TextRange): AnnotatedString
```
Return a substring for the AnnotatedString and include the styles in the given `range`.
#### Parameters
| | |
| --- | --- |
| range | the text range |
```kotlin
operator fun plus(other: AnnotatedString): AnnotatedString
```
```kotlin
fun getStringAnnotations(tag: String, start: Int, end: Int): List>
```
Query the string annotations attached on this AnnotatedString. Annotations are metadata
attached on the AnnotatedString, for example, a URL is a string metadata attached on the a
certain range. Annotations are also store with `Range` like the styles.
#### Parameters
| | |
| --- | --- |
| tag | the tag of the annotations that is being queried. It's used to distinguish the annotations for different purposes. |
| start | the start of the query range, inclusive. |
| end | the end of the query range, exclusive. |
#### Returns
| | |
| --- | --- |
| | a list of annotations stored in `Range`. Notice that All annotations that intersect with the range `start, end) will be returned. When `start` is bigger than `end`, an empty list will be returned. |
```kotlin
fun hasStringAnnotations(tag: String, start: Int, end: Int): Boolean
```
Returns true if `getStringAnnotations` with the same parameters would return a non-empty list
```kotlin
fun getStringAnnotations(start: Int, end: Int): List>
```
Query all of the string annotations attached on this AnnotatedString.
#### Parameters
| | |
| --- | --- |
| start | the start of the query range, inclusive. |
| end | the end of the query range, exclusive. |
#### Returns
| | |
| --- | --- |
| | a list of annotations stored in `Range`. Notice that All annotations that intersect with the range `start, end) will be returned. When `start` is bigger than `end`, an empty list will be returned. |
```kotlin
fun getTtsAnnotations(start: Int, end: Int): List>
```
Query all of the `TtsAnnotation`s attached on this `AnnotatedString`.
#### Parameters
| | |
| --- | --- |
| start | the start of the query range, inclusive. |
| end | the end of the query range, exclusive. |
#### Returns
| | |
| --- | --- |
| | a list of annotations stored in `Range`. Notice that All annotations that intersect with the range `start, end) will be returned. When `start` is bigger than `end`, an empty list will be returned. |
```kotlin
@ExperimentalTextApi
fun getUrlAnnotations(start: Int, end: Int): List>
```
Query all of the `UrlAnnotation`s attached on this `AnnotatedString`.
#### Parameters
| | |
| --- | --- |
| start | the start of the query range, inclusive. |
| end | the end of the query range, exclusive. |
#### Returns
| | |
| --- | --- |
| | a list of annotations stored in `Range`. Notice that All annotations that intersect with the range `start, end) will be returned. When `start` is bigger than `end`, an empty list will be returned. |
```kotlin
fun getLinkAnnotations(start: Int, end: Int): List>
```
Query all of the `LinkAnnotation`s attached on this `AnnotatedString`.
#### Parameters
| | |
| --- | --- |
| start | the start of the query range, inclusive. |
| end | the end of the query range, exclusive. |
#### Returns
| | |
| --- | --- |
| | a list of annotations stored in `Range`. Notice that All annotations that intersect with the range `start, end) will be returned. When `start` is bigger than `end`, an empty list will be returned. |
```kotlin
fun hasLinkAnnotations(start: Int, end: Int): Boolean
```
Returns true if `getLinkAnnotations` with the same parameters would return a non-empty list
```kotlin
fun hasEqualAnnotations(other: AnnotatedString): Boolean
```
Compare the annotations between this and another AnnotatedString.
This may be used for fast partial equality checks.
Note that this checks all annotations including `spanStyles` and `paragraphStyles`, but
`equals` still may be false if `text` is different.
#### Parameters
| | |
| --- | --- |
| other | to compare annotations with |
#### Returns
| | |
| --- | --- |
| | true if and only if this compares equal on annotations with other |
```kotlin
fun mapAnnotations(
transform: (Range) -> Range
): AnnotatedString
```
Returns a new `AnnotatedString` where a list of annotations contains the results of applying
the given `transform` function to each element in the original annotations list.
```kotlin
fun flatMapAnnotations(
transform: (Range) -> List>
): AnnotatedString
```
Returns a new `AnnotatedString` where a list of annotations contains all elements yielded
from results `transform` function being invoked on each element of original annotations list.
## Companion Object
#### Properties
Common
```kotlin
val Saver: Saver
```
The default `Saver` implementation for `AnnotatedString`.
Note this Saver doesn't preserve the `LinkInteractionListener` of the links. You should
handle this case manually if required (check
https://issuetracker.google.com/issues/332901550 for an example).