# androidx.compose.foundation.text

Common/AllAndroid/JVM

In this page, you'll find documentation for types, properties, and functions available in the `androidx.compose.foundation.text` package such as `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicText.composable#BasicText(kotlin.String,androidx.compose.ui.Modifier,androidx.compose.ui.text.TextStyle,kotlin.Function1,androidx.compose.ui.text.style.TextOverflow,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.graphics.ColorProducer,androidx.compose.foundation.text.TextAutoSize)`, `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicTextField.composable#BasicTextField(androidx.compose.foundation.text.input.TextFieldState,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.foundation.text.input.InputTransformation,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.input.KeyboardActionHandler,androidx.compose.foundation.text.input.TextFieldLineLimits,kotlin.Function2,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,androidx.compose.foundation.text.input.OutputTransformation,androidx.compose.foundation.text.input.TextFieldDecorator,androidx.compose.foundation.ScrollState)`, `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardActions`, and `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardOptions`.

If you're looking for guidance instead, check out the [Text in Compose guide](https://developer.android.com/jetpack/compose/text).

## Interfaces

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardActionScope` | This scope can be used to execute the default action implementation. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/TextAutoSize` | Interface used by Text composables to override text size to automatically grow or shrink text to fill the layout bounds. | Cmn |

## Classes

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/InlineTextContent` | A data class that stores a composable to be inserted into the text layout. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardActions` | Configures custom actions to run when the action button on the software keyboard (such as the "Done", "Search", or "Next" button in the bottom corner of the keyboard) is clicked. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardOptions` | Defines keyboard configuration options for TextFields. | Cmn |

## Objects

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/TextAutoSizeDefaults` | Contains defaults for `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/TextAutoSize` APIs. | Cmn |

## Annotations

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/InternalFoundationTextApi` |   | Cmn |

## Composables

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicSecureTextField.composable` | BasicSecureTextField is specifically designed for password entry fields and is a preconfigured alternative to `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicTextField.composable#BasicTextField(androidx.compose.foundation.text.input.TextFieldState,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.foundation.text.input.InputTransformation,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.input.KeyboardActionHandler,androidx.compose.foundation.text.input.TextFieldLineLimits,kotlin.Function2,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,androidx.compose.foundation.text.input.OutputTransformation,androidx.compose.foundation.text.input.TextFieldDecorator,androidx.compose.foundation.ScrollState)`. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicText.composable` | Displays text with semantics and accessibility information. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicTextField.composable` | Interactive text input field without decorations. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/ClickableText.composable` | A continent version of `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicText.composable#BasicText(kotlin.String,androidx.compose.ui.Modifier,androidx.compose.ui.text.TextStyle,kotlin.Function1,androidx.compose.ui.text.style.TextOverflow,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.graphics.ColorProducer,androidx.compose.foundation.text.TextAutoSize)` component to be able to handle click event on the text. | Cmn |

## Top-level functions summary

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardActions` | `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#KeyboardActions(kotlin.Function1)(onAny: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardActionScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)` Creates an instance of `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#KeyboardActions(kotlin.Function1)` that uses the specified lambda for all `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/ImeAction`s. | Cmn |

## Extension functions summary

|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/AnnotatedString.Builder.https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#(androidx.compose.ui.text.AnnotatedString.Builder).appendInlineContent(kotlin.String,kotlin.String)( id: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, alternateText: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html )` Used to insert composables into the text layout. | Cmn |

## Top-level properties summary

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ProvidableCompositionLocal<https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Brush>` | `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#LocalAutofillHighlightBrush()` CompositionLocal used to change the highlight `https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Brush` used for autofilled components. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ProvidableCompositionLocal<https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color>` | `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#LocalAutofillHighlightColor()` **This property is deprecated.** Use LocalAutofillHighlightBrush instead. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ProvidableCompositionLocal<https://developer.android.com/reference/java/util/concurrent/Executor.html?>` | `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#LocalBackgroundTextMeasurementExecutor()` CompositionLocal that provides an Executor for background text processing to potentially get run on. | android |
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ProvidableCompositionLocal<https://developer.android.com/reference/java/util/concurrent/Executor.html?>` | `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#LocalTextFieldContentObserverRegistrationExecutor()` `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicSecureTextField.composable#BasicSecureTextField(androidx.compose.foundation.text.input.TextFieldState,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.foundation.text.input.InputTransformation,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.input.KeyboardActionHandler,kotlin.Function2,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,androidx.compose.foundation.text.input.TextFieldDecorator,androidx.compose.foundation.text.input.TextObfuscationMode,kotlin.Char,androidx.compose.foundation.ScrollState)` or any other secure TextField that depends on it needs to register a `https://developer.android.com/reference/android/database/ContentObserver.html` to be able to observe the changes to platform password visibility settings. | android |

## Top-level functions

### KeyboardActions

Cmn Artifact: [androidx.compose.foundation:foundation](https://developer.android.com/jetpack/androidx/releases/compose-foundation) [View Source](https://cs.android.com/search?q=file:androidx/compose/foundation/text/KeyboardActions.kt+function:KeyboardActions) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-foundation#1.0.0)

```
fun KeyboardActions(onAny: KeyboardActionScope.() -> Unit): KeyboardActions
```

Creates an instance of `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#KeyboardActions(kotlin.Function1)` that uses the specified lambda for all `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/ImeAction`s.

## Extension functions

### AnnotatedString.Builder.appendInlineContent

Cmn Artifact: [androidx.compose.foundation:foundation](https://developer.android.com/jetpack/androidx/releases/compose-foundation) [View Source](https://cs.android.com/search?q=file:androidx/compose/foundation/text/InlineTextContent.kt+function:appendInlineContent) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-foundation#1.0.0)

```
fun AnnotatedString.Builder.appendInlineContent(
    id: String,
    alternateText: String = REPLACEMENT_CHAR
): Unit
```

Used to insert composables into the text layout. This method can be used together with the inlineContent parameter of `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicText.composable#BasicText(kotlin.String,androidx.compose.ui.Modifier,androidx.compose.ui.text.TextStyle,kotlin.Function1,androidx.compose.ui.text.style.TextOverflow,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.graphics.ColorProducer,androidx.compose.foundation.text.TextAutoSize)`. It will append the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#(androidx.compose.ui.text.AnnotatedString.Builder).appendInlineContent(kotlin.String,kotlin.String)` to this `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/AnnotatedString` and also mark this range of text to be replaced by a composable. `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicText.composable#BasicText(kotlin.String,androidx.compose.ui.Modifier,androidx.compose.ui.text.TextStyle,kotlin.Function1,androidx.compose.ui.text.style.TextOverflow,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.graphics.ColorProducer,androidx.compose.foundation.text.TextAutoSize)` will try to find an `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/InlineTextContent` in the map defined by inlineContent whose key equals to `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#(androidx.compose.ui.text.AnnotatedString.Builder).appendInlineContent(kotlin.String,kotlin.String)`, and it will use the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/InlineTextContent#children()` to replace this range of text.

```kotlin
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.text.BasicText
import androidx.compose.foundation.text.InlineTextContent
import androidx.compose.foundation.text.appendInlineContent
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.Placeholder
import androidx.compose.ui.text.PlaceholderVerticalAlign
import androidx.compose.ui.text.buildAnnotatedString
import androidx.compose.ui.unit.em

val myId = "inlineContent"
val text = buildAnnotatedString {
    append("Hello")
    // Append a placeholder string "[myBox]" and attach an annotation "inlineContent" on it.
    appendInlineContent(myId, "[myBox]")
}

val inlineContent =
    mapOf(
        Pair(
            // This tells the [BasicText] to replace the placeholder string "[myBox]" by
            // the composable given in the [InlineTextContent] object.
            myId,
            InlineTextContent(
                // Placeholder tells text layout the expected size and vertical alignment of
                // children composable.
                Placeholder(
                    width = 0.5.em,
                    height = 0.5.em,
                    placeholderVerticalAlign = PlaceholderVerticalAlign.AboveBaseline,
                )
            ) {
                // This [Box] will fill maximum size, which is specified by the [Placeholder]
                // above. Notice the width and height in [Placeholder] are specified in
                // TextUnit,
                // and are converted into pixel by text layout.
                Box(modifier = Modifier.fillMaxSize().background(color = Color.Red))
            },
        )
    )

BasicText(text = text, inlineContent = inlineContent)
```

| Parameters |
|---|---|
| `id: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The id used to look up the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/InlineTextContent`, it is referred by the inlineContent parameter of `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicText.composable#BasicText(kotlin.String,androidx.compose.ui.Modifier,androidx.compose.ui.text.TextStyle,kotlin.Function1,androidx.compose.ui.text.style.TextOverflow,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.graphics.ColorProducer,androidx.compose.foundation.text.TextAutoSize)` to replace the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#(androidx.compose.ui.text.AnnotatedString.Builder).appendInlineContent(kotlin.String,kotlin.String)` to the corresponding composable. |
| `alternateText: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html = REPLACEMENT_CHAR` | The text to be replaced by the inline content. It's displayed when the inlineContent parameter of `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicText.composable#BasicText(kotlin.String,androidx.compose.ui.Modifier,androidx.compose.ui.text.TextStyle,kotlin.Function1,androidx.compose.ui.text.style.TextOverflow,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.graphics.ColorProducer,androidx.compose.foundation.text.TextAutoSize)` doesn't contain `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#(androidx.compose.ui.text.AnnotatedString.Builder).appendInlineContent(kotlin.String,kotlin.String)`. Accessibility features will also use this text to describe the inline content. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#(androidx.compose.ui.text.AnnotatedString.Builder).appendInlineContent(kotlin.String,kotlin.String)` has zero length. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/InlineTextContent` |   |
| `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicText.composable#BasicText(kotlin.String,androidx.compose.ui.Modifier,androidx.compose.ui.text.TextStyle,kotlin.Function1,androidx.compose.ui.text.style.TextOverflow,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.graphics.ColorProducer,androidx.compose.foundation.text.TextAutoSize)` |   |

## Top-level properties

### LocalAutofillHighlightBrush

Cmn Artifact: [androidx.compose.foundation:foundation](https://developer.android.com/jetpack/androidx/releases/compose-foundation) [View Source](https://cs.android.com/search?q=file:androidx/compose/foundation/text/AutofillHighlight.kt+symbol:LocalAutofillHighlightBrush) Added in [1.10.0](https://developer.android.com/jetpack/androidx/releases/compose-foundation#1.10.0)

```
val LocalAutofillHighlightBrush: ProvidableCompositionLocal<Brush>
```

CompositionLocal used to change the highlight `https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Brush` used for autofilled components.

### LocalAutofillHighlightColor

Cmn Artifact: [androidx.compose.foundation:foundation](https://developer.android.com/jetpack/androidx/releases/compose-foundation) [View Source](https://cs.android.com/search?q=file:androidx/compose/foundation/text/AutofillHighlight.kt+symbol:LocalAutofillHighlightColor) Added in [1.8.0](https://developer.android.com/jetpack/androidx/releases/compose-foundation#1.8.0) Deprecated in [1.10.0](https://developer.android.com/jetpack/androidx/releases/compose-foundation#1.10.0)

```
val LocalAutofillHighlightColor: ProvidableCompositionLocal<Color>
```

> [!CAUTION]
> **This property is deprecated.**   
> Use LocalAutofillHighlightBrush instead. To provide a solid color, use SolidColor(yourColor), use this instead:
>
> ```kotlin
> LocalAutofillHighlightBrush
> ```

CompositionLocal used to change the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#autofillHighlightColor()` used by components in the hierarchy.

### LocalBackgroundTextMeasurementExecutor

android Artifact: [androidx.compose.foundation:foundation](https://developer.android.com/jetpack/androidx/releases/compose-foundation) [View Source](https://cs.android.com/search?q=file:androidx/compose/foundation/text/BasicText.android.kt+symbol:LocalBackgroundTextMeasurementExecutor)

```
val LocalBackgroundTextMeasurementExecutor: ProvidableCompositionLocal<Executor?>
```

CompositionLocal that provides an Executor for background text processing to potentially get run on.

BasicText premeasure is the process of using a background thread to early start metrics calculation for Text composables on Android to warm up the underlying text layout cache. This becomes especially useful in LazyLists when precomposition may precede premeasurement by at least a frame, which gives the background thread enough time to fully calculate text metrics. This approximately reduces text layout duration on main thread from 50% to 90%.

By default this CompositionLocal provides null, which means that any text prefetch behavior will revert to the system default. You can provide an executor like `Executors.newSingleThreadExecutor()` for BasicText to schedule background tasks.

Please note that prefetch text does not guarantee a net performance increase. It may actually be harmful in certain scenarios where there is not enough time between composition and measurement for background thread to actually start warming the cache, or when the text is long enough that it floods the cache and overflows it, at around 5000 words.

Use benchmarking tools to check whether enabling this behavior works well for your use case.

```kotlin
import androidx.compose.foundation.text.BasicText
import androidx.compose.foundation.text.LocalBackgroundTextMeasurementExecutor
import androidx.compose.runtime.CompositionLocalProvider

CompositionLocalProvider(
    LocalBackgroundTextMeasurementExecutor provides DefaultTextMeasurementExecutor
) {
    BasicText("Hello World!")
}
```

### LocalTextFieldContentObserverRegistrationExecutor

android Artifact: [androidx.compose.foundation:foundation](https://developer.android.com/jetpack/androidx/releases/compose-foundation) [View Source](https://cs.android.com/search?q=file:androidx/compose/foundation/text/BasicSecureTextField.android.kt+symbol:LocalTextFieldContentObserverRegistrationExecutor)

```
val LocalTextFieldContentObserverRegistrationExecutor: ProvidableCompositionLocal<Executor?>
```

`https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicSecureTextField.composable#BasicSecureTextField(androidx.compose.foundation.text.input.TextFieldState,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.foundation.text.input.InputTransformation,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.input.KeyboardActionHandler,kotlin.Function2,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,androidx.compose.foundation.text.input.TextFieldDecorator,androidx.compose.foundation.text.input.TextObfuscationMode,kotlin.Char,androidx.compose.foundation.ScrollState)` or any other secure TextField that depends on it needs to register a `https://developer.android.com/reference/android/database/ContentObserver.html` to be able to observe the changes to platform password visibility settings. Registering this observer on the main thread is usually fine but because it requires an IPC call to be made, a rare lock contention can happen that hangs the main thread for a short time.

This `https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal` provides a way to choose an `https://developer.android.com/reference/java/util/concurrent/Executor.html` to run this registration and its corresponding unregistration in, freeing the main thread.

The default value `null` indicates that the main thread will be used.