TextFieldState

TextFieldState(
    initialText: String = "",
    initialSelection: TextRange = TextRange(initialText.length)
)

inline fun edit(block: TextFieldBuffer.() -> Unit): Unit

Runs block with a mutable version of the current state. The block can make changes to the text and cursor/selection. See the documentation on TextFieldBuffer for a more detailed description of the available operations.

Make sure that you do not make concurrent calls to this function or call it again inside block's scope. Doing either of these actions will result in triggering an IllegalStateException.

import androidx.compose.foundation.text.input.TextFieldState
import androidx.compose.foundation.text.input.delete
import androidx.compose.foundation.text.input.insert
import androidx.compose.material.Text
import androidx.compose.ui.text.TextRange

val state = TextFieldState("hello world!")
state.edit {
    // Insert a comma after "hello".
    insert(5, ",") // = "hello, world!"

    // Delete the exclamation mark.
    delete(12, 13) // = "hello, world"

    // Add a different name.
    append("Compose") // = "hello, Compose"

    // Say goodbye.
    replace(0, 5, "goodbye") // "goodbye, Compose"

    // Select the new name so the user can change it by just starting to type.
    selection = TextRange(9, 16) // "goodbye, ̲C̲o̲m̲p̲o̲s̲e"
}

open fun toString(): String

val composition: TextRange?

The current composing range dictated by the IME. If null, there is no composing region.

To observe changes to this property outside a restartable function, use snapshotFlow { composition }.

val selection: TextRange

The current selection range. If the selection is collapsed, it represents cursor location. This value will automatically update when the user enters text or otherwise changes the text field selection range. To change it programmatically, call edit.

To observe changes to this property outside a restartable function, use snapshotFlow { selection }.

val text: CharSequence

The current text content. This value will automatically update when the user enters text or otherwise changes the text field contents. To change it programmatically, call edit.

To observe changes to this property outside a restartable function, use snapshotFlow { text }.

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.foundation.text.BasicTextField
import androidx.compose.foundation.text.input.TextFieldState
import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.snapshotFlow
import androidx.compose.ui.unit.sp

class SearchViewModel {
    val searchFieldState = TextFieldState()
    var searchResults: List<String> by mutableStateOf(emptyList())
        private set

    /** Called while the view model is active, e.g. from a LaunchedEffect. */
    suspend fun run() {
        snapshotFlow { searchFieldState.text }
            // Let fast typers get multiple keystrokes in before kicking off a search.
            .debounce(500)
            // collectLatest cancels the previous search if it's still running when there's a
            // new change.
            .collectLatest { queryText -> searchResults = performSearch(query = queryText) }
    }

    private suspend fun performSearch(query: CharSequence): List<String> {
        TODO()
    }
}

@Composable
fun SearchScreen(viewModel: SearchViewModel) {
    Column {
        BasicTextField(viewModel.searchFieldState)
        LazyColumn { items(viewModel.searchResults) { TODO() } }
    }
}

@ExperimentalFoundationApi
val undoState: UndoState

Undo history controller for this TextFieldState.

import androidx.compose.foundation.border
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
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.Text
import androidx.compose.material.icons.filled.Clear
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

val state = rememberTextFieldState()

Column(Modifier.padding(8.dp)) {
    Row(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
        androidx.compose.material.Button(
            onClick = { state.undoState.undo() },
            enabled = state.undoState.canUndo
        ) {
            Text("Undo")
        }

        androidx.compose.material.Button(
            onClick = { state.undoState.redo() },
            enabled = state.undoState.canRedo
        ) {
            Text("Redo")
        }

        androidx.compose.material.Button(
            onClick = { state.undoState.clearHistory() },
            enabled = state.undoState.canUndo || state.undoState.canRedo
        ) {
            Text("Clear History")
        }
    }

    BasicTextField(
        state = state,
        modifier =
            Modifier.fillMaxWidth()
                .border(1.dp, Color.LightGray, RoundedCornerShape(6.dp))
                .padding(8.dp),
        textStyle = TextStyle(fontSize = 16.sp)
    )
}

fun TextFieldState.clearText(): Unit

Deletes all the text in the state.

To perform more complicated edits on the text, call TextFieldState.edit. This function is equivalent to calling:

edit {
  delete(0, length)
  placeCursorAtEnd()
}

fun TextFieldState.setTextAndPlaceCursorAtEnd(text: String): Unit

Sets the text in this TextFieldState to text, replacing any text that was previously there, and places the cursor at the end of the new text.

To perform more complicated edits on the text, call TextFieldState.edit. This function is equivalent to calling:

edit {
  replace(0, length, text)
  placeCursorAtEnd()
}

fun TextFieldState.setTextAndSelectAll(text: String): Unit

Sets the text in this TextFieldState to text, replacing any text that was previously there, and selects all the text.

To perform more complicated edits on the text, call TextFieldState.edit. This function is equivalent to calling:

edit {
  replace(0, length, text)
  selectAll()
}

fun TextFieldState.toTextFieldBuffer(): TextFieldBuffer

Creates a temporary, mutable TextFieldBuffer representing the current state of this TextFieldState.

Use a TextFieldBuffer to:

• Apply transformations for testing purposes

• Preview how the TextField would render with a specific OutputTransformation

This is similar to calling TextFieldState.edit, but without committing the changes back to the TextFieldState.

Important: A TextFieldBuffer is intended for short-term use. Let the garbage collecter dispose of it when you're finished to avoid unnecessary memory usage.

import androidx.compose.foundation.text.input.OutputTransformation
import androidx.compose.foundation.text.input.TextFieldBuffer
import androidx.compose.foundation.text.input.TextFieldState
import androidx.compose.foundation.text.input.insert
import androidx.compose.foundation.text.input.toTextFieldBuffer
import androidx.compose.material.Text

val state = TextFieldState("Hello, World")
val outputTransformation = OutputTransformation { insert(0, "> ") }

val buffer = state.toTextFieldBuffer()
with(outputTransformation) { buffer.transformOutput() }

val transformedText = buffer.asCharSequence()
val transformedSelection = buffer.selection