# BasicTextField

Common/AllAndroid/JVM

## Functions summary

|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicTextField.composable#BasicTextField(androidx.compose.foundation.text.input.TextFieldState,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.foundation.text.input.InputTransformation,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.input.KeyboardActionHandler,androidx.compose.foundation.text.input.TextFieldLineLimits,kotlin.Function2,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,androidx.compose.foundation.text.input.OutputTransformation,androidx.compose.foundation.text.input.TextFieldDecorator,androidx.compose.foundation.ScrollState)( state: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/TextFieldState, modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier, enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, readOnly: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, inputTransformation: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/InputTransformation?, textStyle: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextStyle, keyboardOptions: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardOptions, onKeyboardAction: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/KeyboardActionHandler?, lineLimits: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/TextFieldLineLimits, onTextLayout: (https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Density.(getResult: () -> https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextLayoutResult?) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, interactionSource: https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/MutableInteractionSource?, cursorBrush: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Brush, outputTransformation: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/OutputTransformation?, decorator: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/TextFieldDecorator?, scrollState: https://developer.android.com/reference/kotlin/androidx/compose/foundation/ScrollState )` Interactive text input field without decorations. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable [BasicTextField](https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicTextField.composable#BasicTextField(kotlin.String,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1))( value: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, onValueChange: (https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html, modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier, enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, readOnly: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, textStyle: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextStyle, keyboardOptions: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardOptions, keyboardActions: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardActions, singleLine: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, maxLines: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, minLines: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, visualTransformation: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/VisualTransformation, onTextLayout: (https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextLayoutResult) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html, interactionSource: https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/MutableInteractionSource?, cursorBrush: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Brush, decorationBox: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable innerTextField: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` **This function is deprecated.** Use the BasicTextField(state: TextFieldState, ...) overload instead. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable [BasicTextField](https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicTextField.composable#BasicTextField(androidx.compose.ui.text.input.TextFieldValue,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1))( value: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue, onValueChange: (https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html, modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier, enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, readOnly: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, textStyle: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextStyle, keyboardOptions: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardOptions, keyboardActions: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardActions, singleLine: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, maxLines: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, minLines: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, visualTransformation: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/VisualTransformation, onTextLayout: (https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextLayoutResult) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html, interactionSource: https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/MutableInteractionSource?, cursorBrush: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Brush, decorationBox: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable innerTextField: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` **This function is deprecated.** Use the BasicTextField(state: TextFieldState, ...) overload instead. | Cmn |

## Functions

### BasicTextField

Cmn Artifact: [androidx.compose.foundation:foundation](https://developer.android.com/jetpack/androidx/releases/compose-foundation) [View Source](https://cs.android.com/search?q=file:androidx/compose/foundation/text/BasicTextField.kt+function:BasicTextField) Added in [1.7.0](https://developer.android.com/jetpack/androidx/releases/compose-foundation#1.7.0)

```
@Composable
fun BasicTextField(
    state: TextFieldState,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    readOnly: Boolean = false,
    inputTransformation: InputTransformation? = null,
    textStyle: TextStyle = TextStyle.Default,
    keyboardOptions: KeyboardOptions = KeyboardOptions.Default,
    onKeyboardAction: KeyboardActionHandler? = null,
    lineLimits: TextFieldLineLimits = TextFieldLineLimits.Default,
    onTextLayout: (Density.(getResult: () -> TextLayoutResult?) -> Unit)? = null,
    interactionSource: MutableInteractionSource? = null,
    cursorBrush: Brush = BasicTextFieldDefaults.CursorBrush,
    outputTransformation: OutputTransformation? = null,
    decorator: TextFieldDecorator? = null,
    scrollState: ScrollState = rememberScrollState()
): Unit
```

Interactive text input field without decorations.

Hoists editing state through `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(androidx.compose.foundation.text.input.TextFieldState,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.foundation.text.input.InputTransformation,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.input.KeyboardActionHandler,androidx.compose.foundation.text.input.TextFieldLineLimits,kotlin.Function2,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,androidx.compose.foundation.text.input.OutputTransformation,androidx.compose.foundation.text.input.TextFieldDecorator,androidx.compose.foundation.ScrollState)`.

To add decorations (such as borders, placeholders, hints, prefixes, or suffixes) and increase the hit target area, use `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(androidx.compose.foundation.text.input.TextFieldState,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.foundation.text.input.InputTransformation,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.input.KeyboardActionHandler,androidx.compose.foundation.text.input.TextFieldLineLimits,kotlin.Function2,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,androidx.compose.foundation.text.input.OutputTransformation,androidx.compose.foundation.text.input.TextFieldDecorator,androidx.compose.foundation.ScrollState)`.

To filter or modify input (e.g., limit characters or restrict input patterns), use `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/InputTransformation`.

To transform the visual output (e.g., apply password mask or format phone numbers), use `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/OutputTransformation`.

To limit height, use `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(androidx.compose.foundation.text.input.TextFieldState,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.foundation.text.input.InputTransformation,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.input.KeyboardActionHandler,androidx.compose.foundation.text.input.TextFieldLineLimits,kotlin.Function2,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,androidx.compose.foundation.text.input.OutputTransformation,androidx.compose.foundation.text.input.TextFieldDecorator,androidx.compose.foundation.ScrollState)`.

Hoists scroll state via `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(androidx.compose.foundation.text.input.TextFieldState,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.foundation.text.input.InputTransformation,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.input.KeyboardActionHandler,androidx.compose.foundation.text.input.TextFieldLineLimits,kotlin.Function2,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,androidx.compose.foundation.text.input.OutputTransformation,androidx.compose.foundation.text.input.TextFieldDecorator,androidx.compose.foundation.ScrollState)` to observe and manipulate scroll position, such as scrolling a searched keyword into view without focusing.

```kotlin
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.foundation.text.BasicTextField
import androidx.compose.foundation.text.input.TextFieldState
import androidx.compose.foundation.text.input.rememberTextFieldState
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.MailOutline
import androidx.compose.material3.Icon
import androidx.compose.material3.Text
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

// Demonstrates how to use the decorator API on BasicTextField
val state = rememberTextFieldState("Hello, World!")
BasicTextField(
    state = state,
    decorator = { innerTextField ->
        // Because the decorator is used, the whole Row gets the same behaviour as the internal
        // input field would have otherwise. For example, there is no need to add a
        // `Modifier.clickable` to the Row anymore to bring the text field into focus when user
        // taps on a larger text field area which includes paddings and the icon areas.
        Row(
            Modifier.background(Color.LightGray, RoundedCornerShape(percent = 30))
                .padding(16.dp)
        ) {
            Icon(Icons.Default.MailOutline, contentDescription = "Mail Icon")
            Spacer(Modifier.width(16.dp))
            innerTextField()
        }
    },
)
```

```kotlin
import androidx.compose.foundation.text.BasicTextField
import androidx.compose.foundation.text.input.InputTransformation
import androidx.compose.foundation.text.input.TextFieldState
import androidx.compose.foundation.text.input.delete
import androidx.compose.foundation.text.input.insert
import androidx.compose.material3.Text
import androidx.compose.runtime.remember

// Demonstrates how to create a custom and relatively complex InputTransformation.
val state = remember { TextFieldState() }
BasicTextField(
    state,
    inputTransformation =
        InputTransformation {
            // A filter that always places newly-input text at the start of the string, after a
            // prompt character, like a shell.
            val promptChar = '>'

            fun CharSequence.countPrefix(char: Char): Int {
                var i = 0
                while (i < length && get(i) == char) i++
                return i
            }

            // Step one: Figure out the insertion point.
            val newPromptChars = asCharSequence().countPrefix(promptChar)
            val insertionPoint = if (newPromptChars == 0) 0 else 1

            // Step two: Ensure text is placed at the insertion point.
            if (changes.changeCount == 1) {
                val insertedRange = changes.getRange(0)
                val replacedRange = changes.getOriginalRange(0)
                if (!replacedRange.collapsed && insertedRange.collapsed) {
                    // Text was deleted, delete forwards from insertion point.
                    delete(insertionPoint, insertionPoint + replacedRange.length)
                }
            }
            // Else text was replaced or there were multiple changes - don't handle.

            // Step three: Ensure the prompt character is there.
            if (newPromptChars == 0) {
                insert(0, ">")
            }

            // Step four: Ensure the cursor is ready for the next input.
            placeCursorAfterCharAt(0)
        },
)
```

```kotlin
import androidx.compose.foundation.text.BasicTextField
import androidx.compose.foundation.text.input.TextFieldState
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

var text by remember { mutableStateOf("") }
// A reference implementation that demonstrates how to create a TextField with the legacy
// state hoisting design around `BasicTextField(TextFieldState)`
StringTextField(value = text, onValueChange = { text = it })
```

| Parameters |
|---|---|
| `state: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/TextFieldState` | holding the editing state |
| `modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier = Modifier` | for this layout |
| `enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | controls enabled state. If false, field is not editable, focusable, or selectable |
| `readOnly: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = false` | controls editable state. If true, field cannot be modified but can be focused and copied |
| `inputTransformation: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/InputTransformation? = null` | to transform user changes. Only applies to user-initiated changes (e.g., keyboard input, paste, accessibility), not programmatic updates to `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(androidx.compose.foundation.text.input.TextFieldState,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.foundation.text.input.InputTransformation,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.input.KeyboardActionHandler,androidx.compose.foundation.text.input.TextFieldLineLimits,kotlin.Function2,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,androidx.compose.foundation.text.input.OutputTransformation,androidx.compose.foundation.text.input.TextFieldDecorator,androidx.compose.foundation.ScrollState)`. Changing the transformation applies to the next user edit |
| `textStyle: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextStyle = TextStyle.Default` | configuration for text content |
| `keyboardOptions: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardOptions = KeyboardOptions.Default` | software keyboard options |
| `onKeyboardAction: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/KeyboardActionHandler? = null` | run when user triggers IME action |
| `lineLimits: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/TextFieldLineLimits = TextFieldLineLimits.Default` | limits for line count and scroll behavior. If set to `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/TextFieldLineLimits.SingleLine`, the text field scrolls horizontally and newlines ('\\n') are replaced with spaces |
| `onTextLayout: (https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Density.(getResult: () -> https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextLayoutResult?) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = null` | callback run when a new text layout is calculated. The `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextLayoutResult` parameter contains paragraph information, size, baselines, and other details. Use this callback to add decoration or functionality, such as drawing selection |
| `interactionSource: https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/MutableInteractionSource? = null` | to observe interactions |
| `cursorBrush: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Brush = BasicTextFieldDefaults.CursorBrush` | to paint the cursor |
| `outputTransformation: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/OutputTransformation? = null` | to transform output representation |
| `decorator: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/TextFieldDecorator? = null` | to add decorations (such as borders, placeholders, hints, or prefixes/suffixes) around the text field, and increase the hit target area. The decorator receives an `innerTextField` composable lambda representing the actual text input area, which must be called exactly once |
| `scrollState: https://developer.android.com/reference/kotlin/androidx/compose/foundation/ScrollState = rememberScrollState()` | to manage scroll. If `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(androidx.compose.foundation.text.input.TextFieldState,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.foundation.text.input.InputTransformation,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.input.KeyboardActionHandler,androidx.compose.foundation.text.input.TextFieldLineLimits,kotlin.Function2,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,androidx.compose.foundation.text.input.OutputTransformation,androidx.compose.foundation.text.input.TextFieldDecorator,androidx.compose.foundation.ScrollState)` is `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/TextFieldLineLimits.SingleLine`, the text field scrolls horizontally. Otherwise, it scrolls vertically |

### BasicTextField

Cmn Artifact: [androidx.compose.foundation:foundation](https://developer.android.com/jetpack/androidx/releases/compose-foundation) [View Source](https://cs.android.com/search?q=file:androidx/compose/foundation/text/BasicTextField.kt+function:BasicTextField) Added in [1.4.0](https://developer.android.com/jetpack/androidx/releases/compose-foundation#1.4.0)

```
@Composable
fun [BasicTextField](https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicTextField.composable#BasicTextField(kotlin.String,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1))(
    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? = null,
    cursorBrush: Brush = SolidColor(Color.Black),
    decorationBox: @Composable (@Composable innerTextField: () -> Unit) -> Unit = @Composable { innerTextField -> innerTextField() }
): Unit
```

> [!CAUTION]
> **This function is deprecated.**   
> Use the BasicTextField(state: TextFieldState, ...) overload instead. To migrate: create a TextFieldState via rememberTextFieldState(initialText) in composition or TextFieldState(initialText) in a state holder; read text from state.text and update it programmatically via state.edit { ... } or state.setTextAndPlaceCursorAtEnd(text); observe text changes for side effects via snapshotFlow { state.text }.collect { ... }; and replace onValueChange input filtering with InputTransformation, visualTransformation with OutputTransformation (or BasicSecureTextField for passwords), singleLine/maxLines/minLines with TextFieldLineLimits, decorationBox with TextFieldDecorator, and keyboardActions with KeyboardActionHandler. See https://developer.android.com/develop/ui/compose/text/migrate-state-based for full migration guidance.

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, `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(kotlin.String,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)` is called with the most up to date state represented by `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` with which developer is expected to update their state.

Unlike `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue` overload, this composable does not let the developer control selection, cursor and text composition information. Please check `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue` and corresponding `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicTextField.composable#BasicTextField(kotlin.String,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)` overload for more information.

It is crucial that the value provided to the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(kotlin.String,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)` is fed back into `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicTextField.composable#BasicTextField(kotlin.String,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)` 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 `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(kotlin.String,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)` callback, however the following caveats apply:

- The new value must be provided to `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicTextField.composable#BasicTextField(kotlin.String,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)` 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 `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(kotlin.String,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)`, 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.

Example usage:

```kotlin
import androidx.compose.foundation.text.BasicTextField
import androidx.compose.material3.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.saveable.rememberSaveable

var value by rememberSaveable { mutableStateOf("initial value") }
BasicTextField(
    value = value,
    onValueChange = {
        // it is crucial that the update is fed back into BasicTextField in order to
        // see updates on the text
        value = it
    },
)
```

For example, if you need to include a placeholder in your TextField, you can write a composable using the decoration box like this:

```kotlin
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.text.BasicTextField
import androidx.compose.material3.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.saveable.rememberSaveable

var value by rememberSaveable { mutableStateOf("initial value") }
Box {
    BasicTextField(value = value, onValueChange = { value = it })
    if (value.isEmpty()) {
        Text(text = "Placeholder")
    }
}
```

If you want to add decorations to your text field, such as icon or similar, and increase the hit target area, use the decoration box:

```kotlin
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.foundation.text.BasicTextField
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.MailOutline
import androidx.compose.material3.Icon
import androidx.compose.material3.Text
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.graphics.Color
import androidx.compose.ui.unit.dp

var value by rememberSaveable { mutableStateOf("initial value") }
BasicTextField(
    value = value,
    onValueChange = { value = it },
    decorationBox = { innerTextField ->
        // Because the decorationBox is used, the whole Row gets the same behaviour as the
        // internal input field would have otherwise. For example, there is no need to add a
        // Modifier.clickable to the Row anymore to bring the text field into focus when user
        // taps on a larger text field area which includes paddings and the icon areas.
        Row(
            Modifier.background(Color.LightGray, RoundedCornerShape(percent = 30))
                .padding(16.dp)
        ) {
            Icon(Icons.Default.MailOutline, contentDescription = null)
            Spacer(Modifier.width(16.dp))
            innerTextField()
        }
    },
)
```

In order to create formatted text field, for example for entering a phone number or a social security number, use a `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(kotlin.String,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)` parameter. Below is the example of the text field for entering a credit card number:

```kotlin
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.wrapContentSize
import androidx.compose.foundation.text.BasicTextField
import androidx.compose.foundation.text.KeyboardOptions
import androidx.compose.material3.Text
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.graphics.Color
import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.input.KeyboardType
import androidx.compose.ui.text.input.OffsetMapping
import androidx.compose.ui.text.input.TransformedText
import androidx.compose.ui.text.input.VisualTransformation
import androidx.compose.ui.text.substring
import androidx.compose.ui.unit.dp

/** The offset translator used for credit card input field */
val creditCardOffsetTranslator =
    object : OffsetMapping {
        override fun originalToTransformed(offset: Int): Int {
            return when {
                offset < 4 -> offset
                offset < 8 -> offset + 1
                offset < 12 -> offset + 2
                offset <= 16 -> offset + 3
                else -> 19
            }
        }

        override fun transformedToOriginal(offset: Int): Int {
            return when {
                offset <= 4 -> offset
                offset <= 9 -> offset - 1
                offset <= 14 -> offset - 2
                offset <= 19 -> offset - 3
                else -> 16
            }
        }
    }

/**
 * Converts up to 16 digits to hyphen connected 4 digits string. For example, "1234567890123456"
 * will be shown as "1234-5678-9012-3456"
 */
val creditCardTransformation = VisualTransformation { text ->
    val trimmedText = if (text.text.length > 16) text.text.substring(0..15) else text.text
    var transformedText = ""
    trimmedText.forEachIndexed { index, char ->
        transformedText += char
        if ((index + 1) % 4 == 0 && index != 15) transformedText += "-"
    }
    TransformedText(AnnotatedString(transformedText), creditCardOffsetTranslator)
}

var text by rememberSaveable { mutableStateOf("") }
BasicTextField(
    value = text,
    onValueChange = { input ->
        if (input.length <= 16 && input.none { !it.isDigit() }) {
            text = input
        }
    },
    modifier = Modifier.size(170.dp, 30.dp).background(Color.LightGray).wrapContentSize(),
    singleLine = true,
    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number),
    visualTransformation = creditCardTransformation,
)
```

Note: This overload does not support `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardOptions#showKeyboardOnFocus()`.

| Parameters |
|---|---|
| `value: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | the input `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` text to be shown in the text field |
| `onValueChange: (https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | the callback that is triggered when the input service updates the text. An updated text comes as a parameter of the callback |
| `modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier = Modifier` | optional `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier` for this text field. |
| `enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | controls the enabled state of the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicTextField.composable#BasicTextField(kotlin.String,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)`. When `false`, the text field will be neither editable nor focusable, the input of the text field will not be selectable |
| `readOnly: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = false` | controls the editable state of the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicTextField.composable#BasicTextField(kotlin.String,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)`. 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: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextStyle = TextStyle.Default` | Style configuration that applies at character level such as color, font etc. |
| `keyboardOptions: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardOptions = KeyboardOptions.Default` | software keyboard options that contains configuration such as `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/KeyboardType` and `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/ImeAction`. |
| `keyboardActions: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardActions = KeyboardActions.Default` | 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 `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardOptions#imeAction()`. |
| `singleLine: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = false` | 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 `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/ImeAction`. `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(kotlin.String,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)` and `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(kotlin.String,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)` are ignored as both are automatically set to 1. |
| `maxLines: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = if (singleLine) 1 else Int.MAX_VALUE` | the maximum height in terms of maximum number of visible lines. It is required that 1 \<= `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(kotlin.String,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)`\<= `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(kotlin.String,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)`. This parameter is ignored when `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(kotlin.String,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)` is true. |
| `minLines: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = 1` | the minimum height in terms of minimum number of visible lines. It is required that 1 \<= `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(kotlin.String,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)`\<= `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(kotlin.String,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)`. This parameter is ignored when `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(kotlin.String,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)` is true. |
| `visualTransformation: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/VisualTransformation = VisualTransformation.None` | The visual transformation filter for changing the visual representation of the input. By default no visual transformation is applied. |
| `onTextLayout: (https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextLayoutResult) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html = {}` | Callback that is executed when a new text layout is calculated. A `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/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: https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/MutableInteractionSource? = null` | an optional hoisted `https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/MutableInteractionSource` for observing and emitting `https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/Interaction`s for this text field. You can use this to change the text field's appearance or preview the text field in different states. Note that if `null` is provided, interactions will still happen internally. |
| `cursorBrush: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Brush = SolidColor(Color.Black)` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Brush` to paint cursor with. If `https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/SolidColor` with `https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color#Unspecified()` provided, there will be no cursor drawn |
| `decorationBox: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable innerTextField: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html = @Composable { innerTextField -> innerTextField() }` | 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

Cmn Artifact: [androidx.compose.foundation:foundation](https://developer.android.com/jetpack/androidx/releases/compose-foundation) [View Source](https://cs.android.com/search?q=file:androidx/compose/foundation/text/BasicTextField.kt+function:BasicTextField) Added in [1.4.0](https://developer.android.com/jetpack/androidx/releases/compose-foundation#1.4.0)

```
@Composable
fun [BasicTextField](https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicTextField.composable#BasicTextField(androidx.compose.ui.text.input.TextFieldValue,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1))(
    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? = null,
    cursorBrush: Brush = SolidColor(Color.Black),
    decorationBox: @Composable (@Composable innerTextField: () -> Unit) -> Unit = @Composable { innerTextField -> innerTextField() }
): Unit
```

> [!CAUTION]
> **This function is deprecated.**   
> Use the BasicTextField(state: TextFieldState, ...) overload instead. To migrate: create a TextFieldState via rememberTextFieldState(initialText, initialSelection) in composition or TextFieldState(initialText, initialSelection) in a state holder; read text and selection from state.text and state.selection, and update them programmatically via state.edit { ... } or state.setTextAndPlaceCursorAtEnd(text); observe changes for side effects via snapshotFlow { state.text }.collect { ... }; and replace onValueChange input filtering with InputTransformation, visualTransformation with OutputTransformation (or BasicSecureTextField for passwords), singleLine/maxLines/minLines with TextFieldLineLimits, decorationBox with TextFieldDecorator, and keyboardActions with KeyboardActionHandler. See https://developer.android.com/develop/ui/compose/text/migrate-state-based for full migration guidance.

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, `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(androidx.compose.ui.text.input.TextFieldValue,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)` is called with the most up to date state represented by `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue`. `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue` contains the text entered by user, as well as selection, cursor and text composition information. Please check `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue` for the description of its contents.

It is crucial that the value provided to the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(androidx.compose.ui.text.input.TextFieldValue,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)` is fed back into `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicTextField.composable#BasicTextField(androidx.compose.ui.text.input.TextFieldValue,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)` 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 `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(androidx.compose.ui.text.input.TextFieldValue,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)` callback, however the following caveats apply:

- The new value must be provided to `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicTextField.composable#BasicTextField(androidx.compose.ui.text.input.TextFieldValue,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)` 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 `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(androidx.compose.ui.text.input.TextFieldValue,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)`, 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.

Example usage:

```kotlin
import androidx.compose.foundation.text.BasicTextField
import androidx.compose.material3.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.ui.text.input.TextFieldValue

var value by
    rememberSaveable(stateSaver = TextFieldValue.Saver) { mutableStateOf(TextFieldValue()) }
BasicTextField(
    value = value,
    onValueChange = {
        // it is crucial that the update is fed back into BasicTextField in order to
        // see updates on the text
        value = it
    },
)
```

For example, if you need to include a placeholder in your TextField, you can write a composable using the decoration box like this:

```kotlin
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.text.BasicTextField
import androidx.compose.material3.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.saveable.rememberSaveable

var value by rememberSaveable { mutableStateOf("initial value") }
Box {
    BasicTextField(value = value, onValueChange = { value = it })
    if (value.isEmpty()) {
        Text(text = "Placeholder")
    }
}
```

If you want to add decorations to your text field, such as icon or similar, and increase the hit target area, use the decoration box:

```kotlin
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.foundation.text.BasicTextField
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.MailOutline
import androidx.compose.material3.Icon
import androidx.compose.material3.Text
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.graphics.Color
import androidx.compose.ui.unit.dp

var value by rememberSaveable { mutableStateOf("initial value") }
BasicTextField(
    value = value,
    onValueChange = { value = it },
    decorationBox = { innerTextField ->
        // Because the decorationBox is used, the whole Row gets the same behaviour as the
        // internal input field would have otherwise. For example, there is no need to add a
        // Modifier.clickable to the Row anymore to bring the text field into focus when user
        // taps on a larger text field area which includes paddings and the icon areas.
        Row(
            Modifier.background(Color.LightGray, RoundedCornerShape(percent = 30))
                .padding(16.dp)
        ) {
            Icon(Icons.Default.MailOutline, contentDescription = null)
            Spacer(Modifier.width(16.dp))
            innerTextField()
        }
    },
)
```

Note: This overload does not support `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardOptions#showKeyboardOnFocus()`.

| Parameters |
|---|---|
| `value: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue` | The `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue` to be shown in the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicTextField.composable#BasicTextField(androidx.compose.ui.text.input.TextFieldValue,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)`. |
| `onValueChange: (https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | Called when the input service updates the values in `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue`. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier = Modifier` | optional `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier` for this text field. |
| `enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | controls the enabled state of the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicTextField.composable#BasicTextField(androidx.compose.ui.text.input.TextFieldValue,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)`. When `false`, the text field will be neither editable nor focusable, the input of the text field will not be selectable |
| `readOnly: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = false` | controls the editable state of the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/BasicTextField.composable#BasicTextField(androidx.compose.ui.text.input.TextFieldValue,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)`. 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: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextStyle = TextStyle.Default` | Style configuration that applies at character level such as color, font etc. |
| `keyboardOptions: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardOptions = KeyboardOptions.Default` | software keyboard options that contains configuration such as `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/KeyboardType` and `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/ImeAction`. |
| `keyboardActions: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardActions = KeyboardActions.Default` | 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 `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardOptions#imeAction()`. |
| `singleLine: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = false` | 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 `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/ImeAction`. `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(androidx.compose.ui.text.input.TextFieldValue,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)` and `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(androidx.compose.ui.text.input.TextFieldValue,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)` are ignored as both are automatically set to 1. |
| `maxLines: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = if (singleLine) 1 else Int.MAX_VALUE` | the maximum height in terms of maximum number of visible lines. It is required that 1 \<= `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(androidx.compose.ui.text.input.TextFieldValue,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)`\<= `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(androidx.compose.ui.text.input.TextFieldValue,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)`. This parameter is ignored when `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(androidx.compose.ui.text.input.TextFieldValue,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)` is true. |
| `minLines: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = 1` | the minimum height in terms of minimum number of visible lines. It is required that 1 \<= `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(androidx.compose.ui.text.input.TextFieldValue,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)`\<= `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(androidx.compose.ui.text.input.TextFieldValue,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)`. This parameter is ignored when `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/package-summary#BasicTextField(androidx.compose.ui.text.input.TextFieldValue,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.ui.text.input.VisualTransformation,kotlin.Function1,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Brush,kotlin.Function1)` is true. |
| `visualTransformation: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/VisualTransformation = VisualTransformation.None` | The visual transformation filter for changing the visual representation of the input. By default no visual transformation is applied. |
| `onTextLayout: (https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextLayoutResult) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html = {}` | Callback that is executed when a new text layout is calculated. A `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/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: https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/MutableInteractionSource? = null` | an optional hoisted `https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/MutableInteractionSource` for observing and emitting `https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/Interaction`s for this text field. You can use this to change the text field's appearance or preview the text field in different states. Note that if `null` is provided, interactions will still happen internally. |
| `cursorBrush: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Brush = SolidColor(Color.Black)` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Brush` to paint cursor with. If `https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/SolidColor` with `https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color#Unspecified()` provided, there will be no cursor drawn |
| `decorationBox: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable innerTextField: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html = @Composable { innerTextField -> innerTextField() }` | 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. |