Jetpack Compose BasicTextField in Foundation

Basic composable that enables users to edit text via hardware or software keyboard, but provides no decorations like hint or placeholder.

Whenever the user edits the text, onValueChange is called with the most up to date state represented by String with which developer is expected to update their state.

Unlike TextFieldValue overload, this composable does not let the developer control selection, cursor and text composition information. Please check TextFieldValue and corresponding BasicTextField overload for more information.

It is crucial that the value provided to the onValueChange is fed back into BasicTextField in order to actually display and continue to edit that text in the field. The value you feed back into the field may be different than the one provided to the onValueChange callback, however the following caveats apply:

The new value must be provided to BasicTextField immediately (i.e. by the next frame), or the text field may appear to glitch, e.g. the cursor may jump around. For more information about this requirement, see this article(https://developer.android.com/jetpack/compose/text/user-input#state-practices).
The value fed back into the field may be different from the one passed to onValueChange, although this may result in the input connection being restarted, which can make the keyboard flicker for the user. This is acceptable when you're using the callback to, for example, filter out certain types of input, but should probably not be done on every update when entering freeform text.

This composable provides basic text editing functionality, however does not include any decorations such as borders, hints/placeholder. A design system based implementation such as Material Design Filled text field is typically what is needed to cover most of the needs. This composable is designed to be used when a custom implementation for different design system is needed.

Overloads

BasicTextField

@Composable
fun BasicTextField(
    value: String,
    onValueChange: (String) -> Unit,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    readOnly: Boolean = false,
    textStyle: TextStyle = TextStyle.Default,
    keyboardOptions: KeyboardOptions = KeyboardOptions.Default,
    keyboardActions: KeyboardActions = KeyboardActions.Default,
    singleLine: Boolean = false,
    maxLines: Int = if (singleLine) 1 else Int.MAX_VALUE,
    minLines: Int = 1,
    visualTransformation: VisualTransformation = VisualTransformation.None,
    onTextLayout: (TextLayoutResult) -> Unit = {},
    interactionSource: MutableInteractionSource = remember { MutableInteractionSource() },
    cursorBrush: Brush = SolidColor(Color.Black),
    decorationBox: @Composable (innerTextField: @Composable () -> Unit) -> Unit =
        @Composable { innerTextField -> innerTextField() }
)

Parameters

Name	Description
`value`	the input String text to be shown in the text field
`onValueChange`	the callback that is triggered when the input service updates the text. An updated text comes as a parameter of the callback
`modifier`	optional Modifier for this text field.
`enabled`	controls the enabled state of the BasicTextField. When `false`, the text field will be neither editable nor focusable, the input of the text field will not be selectable
`readOnly`	controls the editable state of the BasicTextField. When `true`, the text field can not be modified, however, a user can focus it and copy text from it. Read-only text fields are usually used to display pre-filled forms that user can not edit
`textStyle`	Style configuration that applies at character level such as color, font etc.
`keyboardOptions`	software keyboard options that contains configuration such as KeyboardType and ImeAction.
`keyboardActions`	when the input service emits an IME action, the corresponding callback is called. Note that this IME action may be different from what you specified in KeyboardOptions.imeAction.
`singleLine`	when set to true, this text field becomes a single horizontally scrolling text field instead of wrapping onto multiple lines. The keyboard will be informed to not show the return key as the ImeAction. maxLines and minLines are ignored as both are automatically set to 1.
`maxLines`	the maximum height in terms of maximum number of visible lines. It is required that 1 <= minLines <= maxLines. This parameter is ignored when singleLine is true.
`minLines`	the minimum height in terms of minimum number of visible lines. It is required that 1 <= minLines <= maxLines. This parameter is ignored when singleLine is true.
`visualTransformation`	The visual transformation filter for changing the visual representation of the input. By default no visual transformation is applied.
`onTextLayout`	Callback that is executed when a new text layout is calculated. A TextLayoutResult object that callback provides contains paragraph information, size of the text, baselines and other details. The callback can be used to add additional decoration or functionality to the text. For example, to draw a cursor or selection around the text.
`interactionSource`	the MutableInteractionSource representing the stream of Interactions for this TextField. You can create and pass in your own remembered MutableInteractionSource if you want to observe Interactions and customize the appearance / behavior of this TextField in different Interactions.
`cursorBrush`	Brush to paint cursor with. If SolidColor with Color.Unspecified provided, there will be no cursor drawn
`decorationBox`	Composable lambda that allows to add decorations around text field, such as icon, placeholder, helper messages or similar, and automatically increase the hit target area of the text field. To allow you to control the placement of the inner text field relative to your decorations, the text field implementation will pass in a framework-controlled composable parameter "innerTextField" to the decorationBox lambda you provide. You must call innerTextField exactly once

BasicTextField

@Composable
fun BasicTextField(
    value: TextFieldValue,
    onValueChange: (TextFieldValue) -> Unit,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    readOnly: Boolean = false,
    textStyle: TextStyle = TextStyle.Default,
    keyboardOptions: KeyboardOptions = KeyboardOptions.Default,
    keyboardActions: KeyboardActions = KeyboardActions.Default,
    singleLine: Boolean = false,
    maxLines: Int = if (singleLine) 1 else Int.MAX_VALUE,
    minLines: Int = 1,
    visualTransformation: VisualTransformation = VisualTransformation.None,
    onTextLayout: (TextLayoutResult) -> Unit = {},
    interactionSource: MutableInteractionSource = remember { MutableInteractionSource() },
    cursorBrush: Brush = SolidColor(Color.Black),
    decorationBox: @Composable (innerTextField: @Composable () -> Unit) -> Unit =
        @Composable { innerTextField -> innerTextField() }
)

Parameters

Name	Description
`value`	The androidx.compose.ui.text.input.TextFieldValue to be shown in the BasicTextField.
`onValueChange`	Called when the input service updates the values in TextFieldValue.
`modifier`	optional Modifier for this text field.
`enabled`	controls the enabled state of the BasicTextField. When `false`, the text field will be neither editable nor focusable, the input of the text field will not be selectable
`readOnly`	controls the editable state of the BasicTextField. When `true`, the text field can not be modified, however, a user can focus it and copy text from it. Read-only text fields are usually used to display pre-filled forms that user can not edit
`textStyle`	Style configuration that applies at character level such as color, font etc.
`keyboardOptions`	software keyboard options that contains configuration such as KeyboardType and ImeAction.
`keyboardActions`	when the input service emits an IME action, the corresponding callback is called. Note that this IME action may be different from what you specified in KeyboardOptions.imeAction.
`singleLine`	when set to true, this text field becomes a single horizontally scrolling text field instead of wrapping onto multiple lines. The keyboard will be informed to not show the return key as the ImeAction. maxLines and minLines are ignored as both are automatically set to 1.
`maxLines`	the maximum height in terms of maximum number of visible lines. It is required that 1 <= minLines <= maxLines. This parameter is ignored when singleLine is true.
`minLines`	the minimum height in terms of minimum number of visible lines. It is required that 1 <= minLines <= maxLines. This parameter is ignored when singleLine is true.
`visualTransformation`	The visual transformation filter for changing the visual representation of the input. By default no visual transformation is applied.
`onTextLayout`	Callback that is executed when a new text layout is calculated. A TextLayoutResult object that callback provides contains paragraph information, size of the text, baselines and other details. The callback can be used to add additional decoration or functionality to the text. For example, to draw a cursor or selection around the text.
`interactionSource`	the MutableInteractionSource representing the stream of Interactions for this TextField. You can create and pass in your own remembered MutableInteractionSource if you want to observe Interactions and customize the appearance / behavior of this TextField in different Interactions.
`cursorBrush`	Brush to paint cursor with. If SolidColor with Color.Unspecified provided, there will be no cursor drawn
`decorationBox`	Composable lambda that allows to add decorations around text field, such as icon, placeholder, helper messages or similar, and automatically increase the hit target area of the text field. To allow you to control the placement of the inner text field relative to your decorations, the text field implementation will pass in a framework-controlled composable parameter "innerTextField" to the decorationBox lambda you provide. You must call innerTextField exactly once