{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

TextFieldKt

public final class TextFieldKt


Summary

Public methods

static final void
@Composable
TextField(
    @NonNull String value,
    @NonNull Function1<@NonNull StringUnit> onValueChange,
    @NonNull Modifier modifier,
    boolean enabled,
    boolean readOnly,
    @NonNull TextStyle textStyle,
    @Composable Function0<Unit> label,
    @Composable Function0<Unit> placeholder,
    @Composable Function0<Unit> leadingIcon,
    @Composable Function0<Unit> trailingIcon,
    @Composable Function0<Unit> prefix,
    @Composable Function0<Unit> suffix,
    @Composable Function0<Unit> supportingText,
    boolean isError,
    @NonNull VisualTransformation visualTransformation,
    @NonNull KeyboardOptions keyboardOptions,
    @NonNull KeyboardActions keyboardActions,
    boolean singleLine,
    int maxLines,
    int minLines,
    @NonNull MutableInteractionSource interactionSource,
    @NonNull Shape shape,
    @NonNull TextFieldColors colors
)

Material Design filled text field.

static final void
@Composable
TextField(
    @NonNull TextFieldValue value,
    @NonNull Function1<@NonNull TextFieldValueUnit> onValueChange,
    @NonNull Modifier modifier,
    boolean enabled,
    boolean readOnly,
    @NonNull TextStyle textStyle,
    @Composable Function0<Unit> label,
    @Composable Function0<Unit> placeholder,
    @Composable Function0<Unit> leadingIcon,
    @Composable Function0<Unit> trailingIcon,
    @Composable Function0<Unit> prefix,
    @Composable Function0<Unit> suffix,
    @Composable Function0<Unit> supportingText,
    boolean isError,
    @NonNull VisualTransformation visualTransformation,
    @NonNull KeyboardOptions keyboardOptions,
    @NonNull KeyboardActions keyboardActions,
    boolean singleLine,
    int maxLines,
    int minLines,
    @NonNull MutableInteractionSource interactionSource,
    @NonNull Shape shape,
    @NonNull TextFieldColors colors
)

Material Design filled text field.

Public methods

TextField

@Composable
public static final void TextField(
    @NonNull String value,
    @NonNull Function1<@NonNull StringUnit> onValueChange,
    @NonNull Modifier modifier,
    boolean enabled,
    boolean readOnly,
    @NonNull TextStyle textStyle,
    @Composable Function0<Unit> label,
    @Composable Function0<Unit> placeholder,
    @Composable Function0<Unit> leadingIcon,
    @Composable Function0<Unit> trailingIcon,
    @Composable Function0<Unit> prefix,
    @Composable Function0<Unit> suffix,
    @Composable Function0<Unit> supportingText,
    boolean isError,
    @NonNull VisualTransformation visualTransformation,
    @NonNull KeyboardOptions keyboardOptions,
    @NonNull KeyboardActions keyboardActions,
    boolean singleLine,
    int maxLines,
    int minLines,
    @NonNull MutableInteractionSource interactionSource,
    @NonNull Shape shape,
    @NonNull TextFieldColors colors
)

Material Design filled text field.

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

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

A simple single line text field looks like:

import androidx.compose.material3.Text
import androidx.compose.material3.TextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.saveable.rememberSaveable

var text by rememberSaveable { mutableStateOf("") }

TextField(
    value = text,
    onValueChange = { text = it },
    label = { Text("Label") },
    singleLine = true
)

You may provide a placeholder:

import androidx.compose.material3.Text
import androidx.compose.material3.TextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.saveable.rememberSaveable

var text by rememberSaveable { mutableStateOf("") }

TextField(
    value = text,
    onValueChange = { text = it },
    label = { Text("Email") },
    placeholder = { Text("example@gmail.com") }
)

You can also provide leading and trailing icons:

import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material.icons.filled.Info
import androidx.compose.material3.Icon
import androidx.compose.material3.Text
import androidx.compose.material3.TextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.saveable.rememberSaveable

var text by rememberSaveable { mutableStateOf("") }

TextField(
    value = text,
    onValueChange = { text = it },
    label = { Text("Label") },
    leadingIcon = { Icon(Icons.Filled.Favorite, contentDescription = "Localized description") },
    trailingIcon = { Icon(Icons.Filled.Info, contentDescription = "Localized description") }
)

You can also provide a prefix or suffix to the text:

import androidx.compose.material3.Text
import androidx.compose.material3.TextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.saveable.rememberSaveable

var text by rememberSaveable { mutableStateOf("") }

TextField(
    value = text,
    onValueChange = { text = it },
    singleLine = true,
    label = { Text("Label") },
    prefix = { Text("www.") },
    suffix = { Text(".com") },
    placeholder = { Text("google") },
)

To handle the error input state, use isError parameter:

import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.text.KeyboardActions
import androidx.compose.material3.Text
import androidx.compose.material3.TextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.ui.Modifier
import androidx.compose.ui.semantics.error
import androidx.compose.ui.semantics.semantics
import androidx.compose.ui.text.style.TextAlign

val errorMessage = "Text input too long"
var text by rememberSaveable { mutableStateOf("") }
var isError by rememberSaveable { mutableStateOf(false) }
val charLimit = 10

fun validate(text: String) {
    isError = text.length > charLimit
}

TextField(
    value = text,
    onValueChange = {
        text = it
        validate(text)
    },
    singleLine = true,
    label = { Text(if (isError) "Username*" else "Username") },
    supportingText = {
        Text(
            modifier = Modifier.fillMaxWidth(),
            text = "Limit: ${text.length}/$charLimit",
            textAlign = TextAlign.End,
        )
    },
    isError = isError,
    keyboardActions = KeyboardActions { validate(text) },
    modifier = Modifier.semantics {
        // Provide localized description of the error
        if (isError) error(errorMessage)
    }
)

Additionally, you may provide additional message at the bottom:

import androidx.compose.material3.Text
import androidx.compose.material3.TextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.saveable.rememberSaveable

var text by rememberSaveable { mutableStateOf("") }

TextField(
    value = text,
    onValueChange = { text = it },
    label = { Text("Label") },
    supportingText = {
        Text("Supporting text that is long and perhaps goes onto another line.")
    },
)

Password text field example:

import androidx.compose.foundation.text.KeyboardOptions
import androidx.compose.material.icons.Icons
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.Text
import androidx.compose.material3.TextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.ui.text.input.KeyboardType
import androidx.compose.ui.text.input.PasswordVisualTransformation
import androidx.compose.ui.text.input.VisualTransformation

var password by rememberSaveable { mutableStateOf("") }
var passwordHidden by rememberSaveable { mutableStateOf(true) }
TextField(
    value = password,
    onValueChange = { password = it },
    singleLine = true,
    label = { Text("Enter password") },
    visualTransformation =
    if (passwordHidden) PasswordVisualTransformation() else VisualTransformation.None,
    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password),
    trailingIcon = {
        IconButton(onClick = { passwordHidden = !passwordHidden }) {
            val visibilityIcon =
                if (passwordHidden) Icons.Filled.Visibility else Icons.Filled.VisibilityOff
            // Please provide localized description for accessibility services
            val description = if (passwordHidden) "Show password" else "Hide password"
            Icon(imageVector = visibilityIcon, contentDescription = description)
        }
    }
)

Hiding a software keyboard on IME action performed:

import androidx.compose.foundation.text.KeyboardActions
import androidx.compose.foundation.text.KeyboardOptions
import androidx.compose.material3.Text
import androidx.compose.material3.TextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.ui.platform.LocalSoftwareKeyboardController
import androidx.compose.ui.text.input.ImeAction

val keyboardController = LocalSoftwareKeyboardController.current
var text by rememberSaveable { mutableStateOf("") }
TextField(
    value = text,
    onValueChange = { text = it },
    label = { Text("Label") },
    keyboardOptions = KeyboardOptions(imeAction = ImeAction.Done),
    keyboardActions = KeyboardActions(
        onDone = {
            keyboardController?.hide()
            // do something here
        }
    )
)

If apart from input text change you also want to observe the cursor location, selection range, or IME composition use the TextField overload with the TextFieldValue parameter instead.

Parameters
@NonNull String value

the input text to be shown in the text field

@NonNull Function1<@NonNull StringUnit> onValueChange

the callback that is triggered when the input service updates the text. An updated text comes as a parameter of the callback

@NonNull Modifier modifier

the Modifier to be applied to this text field

boolean enabled

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

boolean readOnly

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

@NonNull TextStyle textStyle

the style to be applied to the input text. Defaults to LocalTextStyle.

@Composable Function0<Unit> label

the 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

@Composable Function0<Unit> placeholder

the 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

@Composable Function0<Unit> leadingIcon

the optional leading icon to be displayed at the beginning of the text field container

@Composable Function0<Unit> trailingIcon

the optional trailing icon to be displayed at the end of the text field container

@Composable Function0<Unit> prefix

the optional prefix to be displayed before the input text in the text field

@Composable Function0<Unit> suffix

the optional suffix to be displayed after the input text in the text field

@Composable Function0<Unit> supportingText

the optional supporting text to be displayed below the text field

boolean isError

indicates 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

@NonNull VisualTransformation visualTransformation

transforms the visual representation of the input value For example, you can use PasswordVisualTransformation to create a password text field. By default, no visual transformation is applied.

@NonNull KeyboardOptions keyboardOptions

software keyboard options that contains configuration such as KeyboardType and ImeAction.

@NonNull KeyboardActions 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.

boolean singleLine

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

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

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

@NonNull MutableInteractionSource interactionSource

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

@NonNull Shape shape

defines the shape of this text field's container

@NonNull TextFieldColors colors

TextFieldColors that will be used to resolve the colors used for this text field in different states. See TextFieldDefaults.colors.

TextField

@Composable
public static final void TextField(
    @NonNull TextFieldValue value,
    @NonNull Function1<@NonNull TextFieldValueUnit> onValueChange,
    @NonNull Modifier modifier,
    boolean enabled,
    boolean readOnly,
    @NonNull TextStyle textStyle,
    @Composable Function0<Unit> label,
    @Composable Function0<Unit> placeholder,
    @Composable Function0<Unit> leadingIcon,
    @Composable Function0<Unit> trailingIcon,
    @Composable Function0<Unit> prefix,
    @Composable Function0<Unit> suffix,
    @Composable Function0<Unit> supportingText,
    boolean isError,
    @NonNull VisualTransformation visualTransformation,
    @NonNull KeyboardOptions keyboardOptions,
    @NonNull KeyboardActions keyboardActions,
    boolean singleLine,
    int maxLines,
    int minLines,
    @NonNull MutableInteractionSource interactionSource,
    @NonNull Shape shape,
    @NonNull TextFieldColors colors
)

Material Design filled text field.

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

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

See example usage:

import androidx.compose.material3.Text
import androidx.compose.material3.TextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.ui.text.TextRange
import androidx.compose.ui.text.input.TextFieldValue

var text by rememberSaveable(stateSaver = TextFieldValue.Saver) {
    mutableStateOf(TextFieldValue("example", TextRange(0, 7)))
}

TextField(
    value = text,
    onValueChange = { text = it },
    label = { Text("Label") }
)

This overload provides access to the input text, cursor position, selection range and IME composition. If you only want to observe an input text change, use the TextField overload with the String parameter instead.

Parameters
@NonNull TextFieldValue value

the input TextFieldValue to be shown in the text field

@NonNull Function1<@NonNull TextFieldValueUnit> onValueChange

the callback that is triggered when the input service updates values in TextFieldValue. An updated TextFieldValue comes as a parameter of the callback

@NonNull Modifier modifier

the Modifier to be applied to this text field

boolean enabled

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

boolean readOnly

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

@NonNull TextStyle textStyle

the style to be applied to the input text. Defaults to LocalTextStyle.

@Composable Function0<Unit> label

the 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

@Composable Function0<Unit> placeholder

the 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

@Composable Function0<Unit> leadingIcon

the optional leading icon to be displayed at the beginning of the text field container

@Composable Function0<Unit> trailingIcon

the optional trailing icon to be displayed at the end of the text field container

@Composable Function0<Unit> prefix

the optional prefix to be displayed before the input text in the text field

@Composable Function0<Unit> suffix

the optional suffix to be displayed after the input text in the text field

@Composable Function0<Unit> supportingText

the optional supporting text to be displayed below the text field

boolean isError

indicates 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

@NonNull VisualTransformation visualTransformation

transforms the visual representation of the input value. For example, you can use PasswordVisualTransformation to create a password text field. By default, no visual transformation is applied.

@NonNull KeyboardOptions keyboardOptions

software keyboard options that contains configuration such as KeyboardType and ImeAction.

@NonNull KeyboardActions 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.

boolean singleLine

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

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

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

@NonNull MutableInteractionSource interactionSource

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

@NonNull Shape shape

defines the shape of this text field's container

@NonNull TextFieldColors colors

TextFieldColors that will be used to resolve the colors used for this text field in different states. See TextFieldDefaults.colors.