State of Compose 2023 results are in! Click here to learn more

← Back to Material 3 Compose

TextField

Component
in
Material 3
. Since 1.0.0

Overview

Code Examples

Video

<a href="https://m3.material.io/components/text-fields/overview" class="external" target="_blank">Material Design filled text field</a>.

Text fields allow users to enter text into a UI. They typically appear in forms and dialogs. Filled text fields have more visual emphasis than outlined text fields, making them stand out when surrounded by other content and components.

!Filled text field image(https://developer.android.com/images/reference/androidx/compose/material3/filled-text-field.png)

If you are looking for an outlined version, see OutlinedTextField.

A simple single line text field looks like:

Overloads

TextField

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun TextField(
    value: String,
    onValueChange: (String) -> Unit,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    readOnly: Boolean = false,
    textStyle: TextStyle = LocalTextStyle.current,
    label: @Composable (() -> Unit)? = null,
    placeholder: @Composable (() -> Unit)? = null,
    leadingIcon: @Composable (() -> Unit)? = null,
    trailingIcon: @Composable (() -> Unit)? = null,
    prefix: @Composable (() -> Unit)? = null,
    suffix: @Composable (() -> Unit)? = null,
    supportingText: @Composable (() -> Unit)? = null,
    isError: Boolean = false,
    visualTransformation: VisualTransformation = VisualTransformation.None,
    keyboardOptions: KeyboardOptions = KeyboardOptions.Default,
    keyboardActions: KeyboardActions = KeyboardActions.Default,
    singleLine: Boolean = false,
    maxLines: Int = if (singleLine) 1 else Int.MAX_VALUE,
    minLines: Int = 1,
    interactionSource: MutableInteractionSource = remember { MutableInteractionSource() },
    shape: Shape = TextFieldDefaults.shape,
    colors: TextFieldColors = TextFieldDefaults.colors()
)

Parameters

NameDescription
valuethe input text to be shown in the text field
onValueChangethe callback that is triggered when the input service updates the text. An updated text comes as a parameter of the callback
modifierthe Modifier to be applied to this text field
enabledcontrols the enabled state of this text field. When false, this component will not respond to user input, and it will appear visually disabled and disabled to accessibility services.
readOnlycontrols the editable state of the text field. When true, the text field cannot 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 a user cannot edit.
textStylethe style to be applied to the input text. Defaults to LocalTextStyle.
labelthe optional label to be displayed inside the text field container. The default text style for internal Text is Typography.bodySmall when the text field is in focus and Typography.bodyLarge when the text field is not in focus
placeholderthe optional placeholder to be displayed when the text field is in focus and the input text is empty. The default text style for internal Text is Typography.bodyLarge
leadingIconthe optional leading icon to be displayed at the beginning of the text field container
trailingIconthe optional trailing icon to be displayed at the end of the text field container
prefixthe optional prefix to be displayed before the input text in the text field
suffixthe optional suffix to be displayed after the input text in the text field
supportingTextthe optional supporting text to be displayed below the text field
isErrorindicates if the text field's current value is in error. If set to true, the label, bottom indicator and trailing icon by default will be displayed in error color
visualTransformationtransforms the visual representation of the input value For example, you can use PasswordVisualTransformationandroidx.compose.ui.text.input.PasswordVisualTransformation to create a password text field. By default, no visual transformation is applied.
keyboardOptionssoftware keyboard options that contains configuration such as KeyboardType and ImeAction.
keyboardActionswhen 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.
singleLinewhen 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. Note that maxLines parameter will be ignored as the maxLines attribute will be automatically set to 1.
maxLinesthe 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.
minLinesthe 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.
interactionSourcethe MutableInteractionSource representing the stream of Interactions for this text field. You can create and pass in your own remembered instance to observe Interactions and customize the appearance / behavior of this text field in different states.
shapedefines the shape of this text field's container
colorsTextFieldColors that will be used to resolve the colors used for this text field in different states. See TextFieldDefaults.colors

TextField

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun TextField(
    value: TextFieldValue,
    onValueChange: (TextFieldValue) -> Unit,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    readOnly: Boolean = false,
    textStyle: TextStyle = LocalTextStyle.current,
    label: @Composable (() -> Unit)? = null,
    placeholder: @Composable (() -> Unit)? = null,
    leadingIcon: @Composable (() -> Unit)? = null,
    trailingIcon: @Composable (() -> Unit)? = null,
    prefix: @Composable (() -> Unit)? = null,
    suffix: @Composable (() -> Unit)? = null,
    supportingText: @Composable (() -> Unit)? = null,
    isError: Boolean = false,
    visualTransformation: VisualTransformation = VisualTransformation.None,
    keyboardOptions: KeyboardOptions = KeyboardOptions.Default,
    keyboardActions: KeyboardActions = KeyboardActions.Default,
    singleLine: Boolean = false,
    maxLines: Int = if (singleLine) 1 else Int.MAX_VALUE,
    minLines: Int = 1,
    interactionSource: MutableInteractionSource = remember { MutableInteractionSource() },
    shape: Shape = TextFieldDefaults.shape,
    colors: TextFieldColors = TextFieldDefaults.colors()
)

Parameters

NameDescription
valuethe input TextFieldValue to be shown in the text field
onValueChangethe callback that is triggered when the input service updates values in TextFieldValue. An updated TextFieldValue comes as a parameter of the callback
modifierthe Modifier to be applied to this text field
enabledcontrols the enabled state of this text field. When false, this component will not respond to user input, and it will appear visually disabled and disabled to accessibility services.
readOnlycontrols the editable state of the text field. When true, the text field cannot 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 a user cannot edit.
textStylethe style to be applied to the input text. Defaults to LocalTextStyle.
labelthe optional label to be displayed inside the text field container. The default text style for internal Text is Typography.bodySmall when the text field is in focus and Typography.bodyLarge when the text field is not in focus
placeholderthe optional placeholder to be displayed when the text field is in focus and the input text is empty. The default text style for internal Text is Typography.bodyLarge
leadingIconthe optional leading icon to be displayed at the beginning of the text field container
trailingIconthe optional trailing icon to be displayed at the end of the text field container
prefixthe optional prefix to be displayed before the input text in the text field
suffixthe optional suffix to be displayed after the input text in the text field
supportingTextthe optional supporting text to be displayed below the text field
isErrorindicates if the text field's current value is in error state. If set to true, the label, bottom indicator and trailing icon by default will be displayed in error color
visualTransformationtransforms the visual representation of the input value. For example, you can use PasswordVisualTransformationandroidx.compose.ui.text.input.PasswordVisualTransformation to create a password text field. By default, no visual transformation is applied.
keyboardOptionssoftware keyboard options that contains configuration such as KeyboardType and ImeAction.
keyboardActionswhen 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.
singleLinewhen 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. Note that maxLines parameter will be ignored as the maxLines attribute will be automatically set to 1.
maxLinesthe 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.
minLinesthe 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.
interactionSourcethe MutableInteractionSource representing the stream of Interactions for this text field. You can create and pass in your own remembered instance to observe Interactions and customize the appearance / behavior of this text field in different states.
shapedefines the shape of this text field's container
colorsTextFieldColors that will be used to resolve the colors used for this text field in different states. See TextFieldDefaults.colors