Common
```kotlin
class Builder(capacity: Int = 16) : Appendable
```
Builder class for AnnotatedString. Enables construction of an [AnnotatedString](/jetpack-compose/androidx.compose.ui/ui-text/classes/AnnotatedString) using methods
such as [append](#append) and [addStyle](#addstyle).
This class implements `Appendable` and can be used with other APIs that don't know about
[AnnotatedString](/jetpack-compose/androidx.compose.ui/ui-text/classes/AnnotatedString)s:
#### Parameters
| | |
| --- | --- |
| capacity | initial capacity for the internal char buffer |
## Secondary Constructors
```kotlin
constructor(text: String) : this() {
append(text)
}
```
Create an [Builder](/jetpack-compose/androidx.compose.ui/ui-text/classes/AnnotatedString.Builder) instance using the given `String`.
```kotlin
constructor(text: AnnotatedString) : this() {
append(text)
}
```
Create an [Builder](/jetpack-compose/androidx.compose.ui/ui-text/classes/AnnotatedString.Builder) instance using the given [AnnotatedString](/jetpack-compose/androidx.compose.ui/ui-text/classes/AnnotatedString).
## Properties
Common
```kotlin
val length: Int
```
Returns the length of the `String`.
## Functions
append
```kotlin
fun append(text: String)
```
Appends the given `String` to this [Builder](/jetpack-compose/androidx.compose.ui/ui-text/classes/AnnotatedString.Builder).
#### Parameters
| | |
| --- | --- |
| text | the text to append |
deprecated_append_returning_void
```kotlin
fun deprecated_append_returning_void(char: Char)
```
append
```kotlin
fun append(text: AnnotatedString)
```
Appends the given [AnnotatedString](/jetpack-compose/androidx.compose.ui/ui-text/classes/AnnotatedString) to this [Builder](/jetpack-compose/androidx.compose.ui/ui-text/classes/AnnotatedString.Builder).
#### Parameters
| | |
| --- | --- |
| text | the text to append |
append
```kotlin
fun append(text: AnnotatedString, start: Int, end: Int)
```
Appends the range of [text](/jetpack-compose/androidx.compose.ui/ui/properties/text) between `start` (inclusive) and `end` (exclusive) to this
[Builder](/jetpack-compose/androidx.compose.ui/ui-text/classes/AnnotatedString.Builder). All spans and annotations from [text](/jetpack-compose/androidx.compose.ui/ui/properties/text) between `start` and `end` will be copied
over as well.
#### Parameters
| | |
| --- | --- |
| text | the text to append |
| start | The index of the first character in [text](/jetpack-compose/androidx.compose.ui/ui/properties/text) to copy over (inclusive). |
| end | The index after the last character in [text](/jetpack-compose/androidx.compose.ui/ui/properties/text) to copy over (exclusive). |
addStyle
```kotlin
fun addStyle(style: SpanStyle, start: Int, end: Int)
```
Set a [SpanStyle](/jetpack-compose/androidx.compose.ui/ui-text/classes/SpanStyle) for the given range defined by `start` and `end`.
#### Parameters
| | |
| --- | --- |
| style | [SpanStyle](/jetpack-compose/androidx.compose.ui/ui-text/classes/SpanStyle) to be applied |
| start | the inclusive starting offset of the range |
| end | the exclusive end offset of the range |
addStyle
```kotlin
fun addStyle(style: ParagraphStyle, start: Int, end: Int)
```
Set a [ParagraphStyle](/jetpack-compose/androidx.compose.ui/ui-text/classes/ParagraphStyle) for the given range defined by `start` and `end`. When a
[ParagraphStyle](/jetpack-compose/androidx.compose.ui/ui-text/classes/ParagraphStyle) is applied to the [AnnotatedString](/jetpack-compose/androidx.compose.ui/ui-text/classes/AnnotatedString), it will be rendered as a separate
paragraph.
**Paragraphs arrangement**
AnnotatedString only supports a few ways that arrangements can be arranged.
The () and {} below represent different [ParagraphStyle](/jetpack-compose/androidx.compose.ui/ui-text/classes/ParagraphStyle)s passed in that particular order
to the AnnotatedString.
* **Non-overlapping:** paragraphs don't affect each other. (abc){def} or abc(def)ghi{jkl}.
* **Nested:** one paragraph is completely inside the other. (abc{def}ghi) or ({abc}def) or (abd{def}). Note that because () is passed before {} to the AnnotatedString, these are considered nested.
* **Fully overlapping:** two paragraphs cover the exact same range of text. ({abc}).
* **Overlapping:** one paragraph partially overlaps the other. Note that this is invalid! (abc{de)f}.
The order in which you apply `ParagraphStyle` can affect how the paragraphs are arranged.
For example, when you first add () at range 0..4 and then {} at range 0..2, this
paragraphs arrangement is considered nested. But if you first add a () paragraph at range
0..2 and then {} at range 0..4, this arrangement is considered overlapping and is
invalid.
**Styling**
If you don't pass a paragraph style for any part of the text, a paragraph will be created
anyway with a default style. In case of nested paragraphs, the outer paragraph will be
split on the bounds of inner paragraph when the paragraphs are passed to be measured and
rendered. For example, (abc{def}ghi) will be split into (abc)({def})(ghi). The inner
paragraph, similarly to fully overlapping paragraphs, will have a style that is a
combination of two created using a [ParagraphStyle.merge](/jetpack-compose/androidx.compose.ui/ui-text/classes/ParagraphStyle) method.
#### Parameters
| | |
| --- | --- |
| style | [ParagraphStyle](/jetpack-compose/androidx.compose.ui/ui-text/classes/ParagraphStyle) to be applied |
| start | the inclusive starting offset of the range |
| end | the exclusive end offset of the range |
addStringAnnotation
```kotlin
fun addStringAnnotation(tag: String, annotation: String, start: Int, end: Int)
```
Set an Annotation for the given range defined by `start` and `end`.
#### Parameters
| | |
| --- | --- |
| tag | the tag used to distinguish annotations |
| annotation | the string annotation that is attached |
| start | the inclusive starting offset of the range |
| end | the exclusive end offset of the range |
addTtsAnnotation
```kotlin
fun addTtsAnnotation(ttsAnnotation: TtsAnnotation, start: Int, end: Int)
```
Set a [TtsAnnotation](/jetpack-compose/androidx.compose.ui/ui-text/classes/TtsAnnotation) for the given range defined by `start` and `end`.
#### Parameters
| | |
| --- | --- |
| ttsAnnotation | an object that stores text to speech metadata that intended for the TTS engine. |
| start | the inclusive starting offset of the range |
| end | the exclusive end offset of the range |
addUrlAnnotation
```kotlin
@ExperimentalTextApi
fun addUrlAnnotation(urlAnnotation: UrlAnnotation, start: Int, end: Int)
```
Set a [UrlAnnotation](/jetpack-compose/androidx.compose.ui/ui-text/classes/UrlAnnotation) for the given range defined by `start` and `end`. URLs may be
treated specially by screen readers, including being identified while reading text with
an audio icon or being summarized in a links menu.
#### Parameters
| | |
| --- | --- |
| urlAnnotation | A [UrlAnnotation](/jetpack-compose/androidx.compose.ui/ui-text/classes/UrlAnnotation) object that stores the URL being linked to. |
| start | the inclusive starting offset of the range |
| end | the exclusive end offset of the range |
addLink
```kotlin
fun addLink(url: LinkAnnotation.Url, start: Int, end: Int)
```
Set a [LinkAnnotation.Url](/jetpack-compose/androidx.compose.ui/ui-text/classes/LinkAnnotation.Url) for the given range defined by `start` and `end`.
When clicking on the text in range, the corresponding URL from the `url` annotation will
be opened using [androidx.compose.ui.platform.UriHandler](/jetpack-compose/androidx.compose.ui/ui/interfaces/UriHandler).
URLs may be treated specially by screen readers, including being identified while reading
text with an audio icon or being summarized in a links menu.
#### Parameters
| | |
| --- | --- |
| url | A [LinkAnnotation.Url](/jetpack-compose/androidx.compose.ui/ui-text/classes/LinkAnnotation.Url) object that stores the URL being linked to. |
| start | the inclusive starting offset of the range |
| end | the exclusive end offset of the range |
addLink
```kotlin
fun addLink(clickable: LinkAnnotation.Clickable, start: Int, end: Int)
```
Set a [LinkAnnotation.Clickable](/jetpack-compose/androidx.compose.ui/ui-text/classes/LinkAnnotation.Clickable) for the given range defined by `start` and `end`.
When clicking on the text in range, a [LinkInteractionListener](/jetpack-compose/androidx.compose.ui/ui-text/interfaces/LinkInteractionListener) will be triggered with
the [clickable](/jetpack-compose/androidx.glance/glance/composable-functions/clickable) object.
Clickable link may be treated specially by screen readers, including being identified
while reading text with an audio icon or being summarized in a links menu.
#### Parameters
| | |
| --- | --- |
| clickable | A [LinkAnnotation.Clickable](/jetpack-compose/androidx.compose.ui/ui-text/classes/LinkAnnotation.Clickable) object that stores the tag being linked to. |
| start | the inclusive starting offset of the range |
| end | the exclusive end offset of the range |
addBullet
```kotlin
fun addBullet(bullet: Bullet, start: Int, end: Int)
```
Adds an annotation to draw a bullet. Unlike another overload, this one doesn't add a
separate [ParagraphStyle](/jetpack-compose/androidx.compose.ui/ui-text/classes/ParagraphStyle). As so for bullet to be rendered, make sure it starts on a
separate line by adding a newline before or wrapping with a [ParagraphStyle](/jetpack-compose/androidx.compose.ui/ui-text/classes/ParagraphStyle).
For a convenient API to create a bullet list check [withBulletList](#withbulletlist).
#### Parameters
| | |
| --- | --- |
| bullet | a bullet to draw before the text |
| start | the inclusive starting offset of the range |
| end | the exclusive end offset of the range |
addBullet
```kotlin
fun addBullet(bullet: Bullet, indentation: TextUnit, start: Int, end: Int)
```
Adds an annotation to draw a [bullet](/jetpack-compose/androidx.compose.ui/ui-text/classes/Bullet) together with a paragraph that adds an
`indentation`.
#### Parameters
| | |
| --- | --- |
| bullet | a bullet to draw before the text |
| indentation | indentation that is added to the paragraph. Note that this indentation should be large enough to fit a bullet and a padding between the bullet and beginning of the paragraph |
| start | the inclusive starting offset of the range |
| end | the exclusive end offset of the range |
pushStyle
```kotlin
fun pushStyle(style: SpanStyle): Int
```
Applies the given [SpanStyle](/jetpack-compose/androidx.compose.ui/ui-text/classes/SpanStyle) to any appended text until a corresponding [pop](#pop) is called.
#### Parameters
| | |
| --- | --- |
| style | SpanStyle to be applied |
pushStyle
```kotlin
fun pushStyle(style: ParagraphStyle): Int
```
Applies the given [ParagraphStyle](/jetpack-compose/androidx.compose.ui/ui-text/classes/ParagraphStyle) to any appended text until a corresponding [pop](#pop) is
called.
#### Parameters
| | |
| --- | --- |
| style | ParagraphStyle to be applied |
pushBullet
```kotlin
fun pushBullet(bullet: Bullet): Int
```
Applies the given [bullet](/jetpack-compose/androidx.compose.ui/ui-text/classes/Bullet) annotation to any appended text until a corresponding [pop](#pop) is
called. For bullet to be rendered, make sure it starts on a separate line by either
adding a newline before or by wrapping with a [ParagraphStyle](/jetpack-compose/androidx.compose.ui/ui-text/classes/ParagraphStyle).
For a convenient API to create a bullet list check [withBulletList](#withbulletlist).
withBulletList
```kotlin
fun withBulletList(
indentation: TextUnit = Bullet.DefaultIndentation,
bullet: Bullet = Bullet.Default,
block: BulletScope.() -> R,
): R
```
Creates a bullet list which allows to define a common `indentation` and a [bullet](/jetpack-compose/androidx.compose.ui/ui-text/classes/Bullet) for
evey bullet list item created inside the list.
Note that when nesting the [withBulletList](#withbulletlist) calls, the indentation inside the nested list
will be a combination of all indentations in the nested chain. For example,
```kotlin
withBulletList(10.sp) { withBulletList(15.sp) { // items indentation 25.sp }
}
```
withBulletListItem
```kotlin
fun BulletScope.withBulletListItem(
bullet: Bullet? = null,
block: Builder.() -> R,
): R
```
Creates a bullet list item around the content produced by the `block`. The list item
creates a separate paragraph with the indentation to the bullet defined by the preceding
[Builder.withBulletList](/jetpack-compose/androidx.compose.ui/ui-text/classes/AnnotatedString.Builder) calls.
#### Parameters
| | |
| --- | --- |
| bullet | defines the bullet to be drawn |
| block | function to be executed |
pushStringAnnotation
```kotlin
fun pushStringAnnotation(tag: String, annotation: String): Int
```
Attach the given [annotation](/jetpack-compose/androidx.compose.ui/ui-text/interfaces/AnnotatedString.Annotation) to any appended text until a corresponding [pop](#pop) is called.
#### Parameters
| | |
| --- | --- |
| tag | the tag used to distinguish annotations |
| annotation | the string annotation attached on this AnnotatedString |
pushTtsAnnotation
```kotlin
fun pushTtsAnnotation(ttsAnnotation: TtsAnnotation): Int
```
Attach the given [ttsAnnotation](/jetpack-compose/androidx.compose.ui/ui-text/classes/TtsAnnotation) to any appended text until a corresponding [pop](#pop) is
called.
#### Parameters
| | |
| --- | --- |
| ttsAnnotation | an object that stores text to speech metadata that intended for the TTS engine. |
pushUrlAnnotation
```kotlin
@ExperimentalTextApi
fun pushUrlAnnotation(urlAnnotation: UrlAnnotation): Int
```
Attach the given [UrlAnnotation](/jetpack-compose/androidx.compose.ui/ui-text/classes/UrlAnnotation) to any appended text until a corresponding [pop](#pop) is
called.
#### Parameters
| | |
| --- | --- |
| urlAnnotation | A [UrlAnnotation](/jetpack-compose/androidx.compose.ui/ui-text/classes/UrlAnnotation) object that stores the URL being linked to. |
pushLink
```kotlin
fun pushLink(link: LinkAnnotation): Int
```
Attach the given [LinkAnnotation](/jetpack-compose/androidx.compose.ui/ui-text/classes/LinkAnnotation) to any appended text until a corresponding [pop](#pop) is
called.
#### Parameters
| | |
| --- | --- |
| link | A [LinkAnnotation](/jetpack-compose/androidx.compose.ui/ui-text/classes/LinkAnnotation) object that stores the URL or clickable tag being linked to. |
pop
```kotlin
fun pop()
```
Ends the style or annotation that was added via a push operation before.
pop
```kotlin
fun pop(index: Int)
```
Ends the styles or annotation up to and `including` the [pushStyle](#pushstyle) or
[pushStringAnnotation](#pushstringannotation) that returned the given index.
#### Parameters
| | |
| --- | --- |
| index | the result of the a previous [pushStyle](#pushstyle) or [pushStringAnnotation](#pushstringannotation) in order to pop to |
toAnnotatedString
```kotlin
fun toAnnotatedString(): AnnotatedString
```
Constructs an [AnnotatedString](/jetpack-compose/androidx.compose.ui/ui-text/classes/AnnotatedString) based on the configurations applied to the [Builder](/jetpack-compose/androidx.compose.ui/ui-text/classes/AnnotatedString.Builder).