Google is committed to advancing racial equity for Black communities. See how.

androidx.compose.foundation.text

Classes

InlineTextContent

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

Top-level functions summary

Unit
CoreText(text: AnnotatedString, modifier: Modifier = Modifier, style: TextStyle, softWrap: Boolean, overflow: TextOverflow, maxLines: Int, inlineContent: Map<String, InlineTextContent>, onTextLayout: (TextLayoutResult) -> Unit)

CoreText is a low level element that displays text with multiple different styles.

Unit
CoreTextField(value: TextFieldValue, modifier: Modifier = Modifier, onValueChange: (TextFieldValue) -> Unit, textStyle: TextStyle = TextStyle.Default, keyboardType: KeyboardType = KeyboardType.Text, imeAction: ImeAction = ImeAction.Unspecified, onImeActionPerformed: (ImeAction) -> Unit = {}, visualTransformation: VisualTransformation = VisualTransformation.None, onTextLayout: (TextLayoutResult) -> Unit = {}, onTextInputStarted: (SoftwareKeyboardController) -> Unit = {})

Base composable that enables users to edit text via hardware or software keyboard.

Top-level properties summary

HorizontalAlignmentLine

AlignmentLine defined by the baseline of a first line of a CoreText.

HorizontalAlignmentLine

AlignmentLine defined by the baseline of the last line of a CoreText.

Extension functions summary

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

Append an inline content into the AnnotatedString.

For SemanticsPropertyReceiver
Unit

Whether the component supports input methods.

Extension properties summary

For SemanticsPropertyReceiver
ImeAction

Contains the IME action provided by the node.

Top-level functions

CoreText

@Composable fun CoreText(
    text: AnnotatedString,
    modifier: Modifier = Modifier,
    style: TextStyle,
    softWrap: Boolean,
    overflow: TextOverflow,
    maxLines: Int,
    inlineContent: Map<String, InlineTextContent>,
    onTextLayout: (TextLayoutResult) -> Unit
): Unit

CoreText is a low level element that displays text with multiple different styles. The text to display is described using a AnnotatedString. Typically you will instead want to use androidx.compose.foundation.Text, which is a higher level Text element that contains semantics and consumes style information from a theme.

Parameters
text: AnnotatedString AnnotatedString encoding a styled text.
modifier: Modifier = Modifier Modifier to apply to this layout node.
style: TextStyle Style configuration for the text such as color, font, line height etc.
softWrap: Boolean Whether the text should break at soft line breaks. If false, the glyphs in the text will be positioned as if there was unlimited horizontal space. If softWrap is false, overflow and TextAlign may have unexpected effects.
overflow: TextOverflow How visual overflow should be handled.
maxLines: Int An optional maximum number of lines for the text to span, wrapping if necessary. If the text exceeds the given number of lines, it will be truncated according to overflow and softWrap. If it is not null, then it must be greater than zero.
inlineContent: Map<String, InlineTextContent> A map store composables that replaces certain ranges of the text. It's used to insert composables into text layout. Check InlineTextContent for more information.
onTextLayout: (TextLayoutResult) -> Unit Callback that is executed when a new text layout is calculated.

CoreTextField

@Composable fun CoreTextField(
    value: TextFieldValue,
    modifier: Modifier = Modifier,
    onValueChange: (TextFieldValue) -> Unit,
    textStyle: TextStyle = TextStyle.Default,
    keyboardType: KeyboardType = KeyboardType.Text,
    imeAction: ImeAction = ImeAction.Unspecified,
    onImeActionPerformed: (ImeAction) -> Unit = {},
    visualTransformation: VisualTransformation = VisualTransformation.None,
    onTextLayout: (TextLayoutResult) -> Unit = {},
    onTextInputStarted: (SoftwareKeyboardController) -> Unit = {}
): Unit

Base composable that enables users to edit text via hardware or software keyboard.

This composable provides basic text editing functionality, however does not include any decorations such as borders, hints/placeholder.

Whenever the user edits the text, onValueChange is called with the most up to date state represented by TextFieldValue. TextFieldValue contains the text entered by user, as well as selection, cursor and text composition information. Please check TextFieldValue for the description of its contents.

It is crucial that the value provided in the onValueChange is fed back into CoreTextField in order to have the final state of the text being displayed. Example usage:

import androidx.compose.foundation.text.CoreTextField
import androidx.compose.runtime.savedinstancestate.savedInstanceState
import androidx.compose.ui.text.input.TextFieldValue

var value by savedInstanceState(saver = TextFieldValue.Saver) { TextFieldValue() }
CoreTextField(
    value = value,
    onValueChange = {
        // it is crucial that the update is fed back into CoreTextField in order to
        // see updates on the text
        value = it
    }
)
Please keep in mind that onValueChange is useful to be informed about the latest state of thetext input by users, however it is generally not recommended to modify the values in theTextFieldValue that you get via onValueChange callback. Any change to the values inTextFieldValue may result in a context reset and end up with input session restart. Sucha scenario would cause glitches in the UI or text input experience for users.
Parameters
value: TextFieldValue The androidx.compose.ui.text.input.TextFieldValue to be shown in the CoreTextField.
onValueChange: (TextFieldValue) -> Unit Called when the input service updates the values in TextFieldValue.
modifier: Modifier = Modifier optional Modifier for this text field.
textStyle: TextStyle = TextStyle.Default Style configuration that applies at character level such as color, font etc.
keyboardType: KeyboardType = KeyboardType.Text The keyboard type to be used in this text field. Note that this input type is honored by IME and shows corresponding keyboard but this is not guaranteed. For example, some IME may send non-ASCII character even if you set KeyboardType.Ascii.
imeAction: ImeAction = ImeAction.Unspecified The IME action. This IME action is honored by IME and may show specific icons on the keyboard. For example, search icon may be shown if ImeAction.Search is specified. Then, when user tap that key, the onImeActionPerformed callback is called with specified ImeAction.
onImeActionPerformed: (ImeAction) -> Unit = {} Called when the input service requested an IME action. When the input service emitted an IME action, this callback is called with the emitted IME action. Note that this IME action may be different from what you specified in imeAction.
visualTransformation: VisualTransformation = VisualTransformation.None The visual transformation filter for changing the visual representation of the input. By default no visual transformation is applied.
onTextLayout: (TextLayoutResult) -> Unit = {} Callback that is executed when a new text layout is calculated.
onTextInputStarted: (SoftwareKeyboardController) -> Unit = {} Callback that is executed when the initialization has done for communicating with platform text input service, e.g. software keyboard on Android. Called with SoftwareKeyboardController instance which can be used for requesting input show/hide software keyboard.

Top-level properties

FirstBaseline

val FirstBaseline: HorizontalAlignmentLine

AlignmentLine defined by the baseline of a first line of a CoreText.

LastBaseline

val LastBaseline: HorizontalAlignmentLine

AlignmentLine defined by the baseline of the last line of a CoreText.

Extension functions

appendInlineContent

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

Append an inline content into the AnnotatedString.

Parameters
id: String The id of this inline content, it is referred by the androidx.compose.foundation.text.CoreText parameter inlineContent 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 androidx.compose.foundation.text.CoreText doesn't contain id. Accessibility features will also use this text to describe the inline content.
Exceptions
IllegalArgumentException if alternateText has zero length.

supportsInputMethods

fun SemanticsPropertyReceiver.supportsInputMethods(): Unit

Whether the component supports input methods.

Supporting input methods means that the component provides a connection to IME (keyboard) and is able to accept input from it. This is typically a text field for instance.

Extension properties

imeAction

var SemanticsPropertyReceiver.imeAction: ImeAction

Contains the IME action provided by the node.