androidx.compose.foundation.text

In this page, you'll find documentation for types, properties, and functions available in the androidx.compose.foundation.text package such as BasicText, BasicTextField, KeyboardActions, and KeyboardOptions.

If you're looking for guidance instead, check out the Text in Compose guide.

Interfaces

KeyboardActionScope

This scope can be used to execute the default action implementation.
Cmn
TextAutoSize

Interface used by Text composables to override text size to automatically grow or shrink text to fill the layout bounds.
Cmn

Classes

InlineTextContent

A data class that stores a composable to be inserted into the text layout.
Cmn
KeyboardActions

The KeyboardActions class allows developers to specify actions that will be triggered in response to users triggering IME action on the software keyboard.
Cmn
KeyboardOptions

The keyboard configuration options for TextFields.
Cmn

Objects

TextAutoSizeDefaults

Contains defaults for TextAutoSize APIs.
Cmn

Annotations

InternalFoundationTextApi
Cmn

Composables

BasicSecureTextField

BasicSecureTextField is specifically designed for password entry fields and is a preconfigured alternative to BasicTextField.
Cmn
BasicText

Basic element that displays text and provides semantics / accessibility information.
Cmn
BasicTextField

Basic text composable that provides an interactive box that accepts text input through software or hardware keyboard, but provides no decorations like hint or placeholder.
Cmn
ClickableText

A continent version of BasicText component to be able to handle click event on the text.
Cmn

Top-level functions summary

KeyboardActions

Creates an instance of KeyboardActions that uses the specified lambda for all ImeActions.
Cmn

Extension functions summary

Unit
AnnotatedString.Builder.appendInlineContent(
    id: String,
    alternateText: String
)

Used to insert composables into the text layout.
Cmn

Top-level properties summary

ProvidableCompositionLocal<Brush>

CompositionLocal used to change the highlight Brush used for autofilled components.
Cmn
ProvidableCompositionLocal<Color>

This property is deprecated. Use LocalAutofillHighlightBrush instead.
Cmn
ProvidableCompositionLocal<Executor?>

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

Top-level functions

KeyboardActions

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

Creates an instance of KeyboardActions that uses the specified lambda for all ImeActions.

Extension functions

AnnotatedString.Builder.appendInlineContent

Cmn 
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 BasicText. It will append the alternateText to this AnnotatedString and also mark this range of text to be replaced by a composable. BasicText will try to find an InlineTextContent in the map defined by inlineContent whose key equals to id, and it will use the InlineTextContent.children to replace this range of text.

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: String

The id used to look up the InlineTextContent, it is referred by the inlineContent parameter of BasicText to replace the alternateText to the corresponding composable.
alternateText: String = REPLACEMENT_CHAR

The text to be replaced by the inline content. It's displayed when the inlineContent parameter of BasicText doesn't contain id. Accessibility features will also use this text to describe the inline content.
Throws
IllegalArgumentException

if alternateText has zero length.
See also
InlineTextContent
BasicText

Top-level properties

LocalAutofillHighlightBrush

Cmn 
val LocalAutofillHighlightBrush: ProvidableCompositionLocal<Brush>

CompositionLocal used to change the highlight Brush used for autofilled components.

LocalAutofillHighlightColor

Cmn 
val LocalAutofillHighlightColor: ProvidableCompositionLocal<Color>

CompositionLocal used to change the autofillHighlightColor used by components in the hierarchy.

LocalBackgroundTextMeasurementExecutor

android 
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.

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

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