androidx.compose.foundation.text.input

@Composable
fun rememberTextFieldState(
    initialText: String = "",
    initialSelection: TextRange = TextRange(initialText.length)
): TextFieldState

Create and remember a TextFieldState. The state is remembered using rememberSaveable and so will be saved and restored with the composition.

If you need to store a TextFieldState in another object, use the TextFieldState.Saver object to manually save and restore the state.

fun InputTransformation.allCaps(locale: Locale): InputTransformation

Returns a InputTransformation that forces all text to be uppercase.

This transformation automatically configures the keyboard to capitalize all characters.

fun InputTransformation.byValue(
    transformation: (current: CharSequence, proposed: CharSequence) -> CharSequence
): InputTransformation

Creates an InputTransformation from a function that accepts both the old and proposed TextFieldCharSequence and returns the TextFieldCharSequence to use for the field.

transformation can return either old, proposed, or a completely different value.

The selection or cursor will be updated automatically. For more control of selection implement InputTransformation directly.

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.byValue
import androidx.compose.material.Text
import androidx.compose.runtime.remember
import androidx.compose.ui.unit.sp

val state = remember { TextFieldState() }
BasicTextField(
    state,
    // Reject whitespace.
    inputTransformation = InputTransformation.byValue { current, proposed ->
        if ("""\s""".toRegex() in proposed) current else proposed
    }
)

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.byValue
import androidx.compose.material.Text
import androidx.compose.runtime.remember
import androidx.compose.ui.unit.sp

val state = remember { TextFieldState() }
BasicTextField(
    state,
    // Convert tabs to spaces.
    inputTransformation = InputTransformation.byValue { _, proposed ->
        proposed.replace("""\t""".toRegex(), "  ")
    }
)

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 TextFieldBuffer.delete(start: Int, end: Int): Unit

Delete the text between start (inclusive) and end (exclusive). Pass 0 as start and TextFieldBuffer.length as end to delete everything in this buffer.

@ExperimentalFoundationApi
inline fun TextFieldBuffer.ChangeList.forEachChange(
    block: (range: TextRange, originalRange: TextRange) -> Unit
): Unit

Iterates over all the changes in this ChangeList.

Changes are iterated by index, so any changes made by block after the current one will be visited by block. block should not make any new changes before the current one or changes will be visited more than once. If you need to make changes, consider using forEachChangeReversed.

import androidx.compose.foundation.text.BasicTextField
import androidx.compose.foundation.text.input.TextFieldState
import androidx.compose.foundation.text.input.forEachChange
import androidx.compose.foundation.text.input.rememberTextFieldState
import androidx.compose.material.Text
import androidx.compose.runtime.remember
import androidx.compose.ui.text.substring

// Print a log message every time the text is changed.
BasicTextField(state = rememberTextFieldState(), inputTransformation = {
    changes.forEachChange { sourceRange, replacedLength ->
        val newString = asCharSequence().substring(sourceRange)
        println("""$replacedLength characters were replaced with "$newString"""")
    }
})

@ExperimentalFoundationApi
inline fun TextFieldBuffer.ChangeList.forEachChangeReversed(
    block: (range: TextRange, originalRange: TextRange) -> Unit
): Unit

Iterates over all the changes in this ChangeList in reverse order.

Changes are iterated by index, so block should not perform any new changes before the current one or changes may be skipped. block may make non-overlapping changes after the current one safely, such changes will not be visited.

import androidx.compose.foundation.text.BasicTextField
import androidx.compose.foundation.text.input.TextFieldState
import androidx.compose.foundation.text.input.delete
import androidx.compose.foundation.text.input.forEachChange
import androidx.compose.foundation.text.input.forEachChangeReversed
import androidx.compose.foundation.text.input.insert
import androidx.compose.foundation.text.input.rememberTextFieldState
import androidx.compose.material.Text
import androidx.compose.runtime.remember

// Make a text field behave in "insert mode" – inserted text overwrites the text ahead of it
// instead of being inserted.
BasicTextField(state = rememberTextFieldState(), inputTransformation = {
    changes.forEachChangeReversed { range, originalRange ->
        if (!range.collapsed && originalRange.collapsed) {
            // New text was inserted, delete the text ahead of it.
            delete(
                range.end.coerceAtMost(length),
                (range.end + range.length).coerceAtMost(length)
            )
        }
    }
})

fun TextFieldBuffer.insert(index: Int, text: String): Unit

Insert text at the given index in this value. Pass 0 to insert text at the beginning of this buffer, and pass TextFieldBuffer.length to insert text at the end of this buffer.

This is equivalent to calling replace(index, index, text).

fun InputTransformation.maxLength(maxLength: Int): InputTransformation

Returns InputTransformation that rejects input which causes the total length of the text field to be more than maxLength characters.

fun TextFieldBuffer.placeCursorAtEnd(): Unit

Places the cursor at the end of the text.

fun TextFieldBuffer.selectAll(): Unit

Places the selection around all the text.

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 InputTransformation.then(next: InputTransformation): InputTransformation

Creates a filter chain that will run next after this. Filters are applied sequentially, so any changes made by this filter will be visible to next.

The returned filter will use the KeyboardOptions from next if non-null, otherwise it will use the options from this transformation.

import androidx.compose.foundation.text.input.InputTransformation
import androidx.compose.foundation.text.input.then

val removeFirstEFilter = InputTransformation {
    val index = asCharSequence().indexOf('e')
    if (index != -1) {
        replace(index, index + 1, "")
    }
}
val printECountFilter = InputTransformation {
    println("found ${asCharSequence().count { it == 'e' }} 'e's in the string")
}

// Returns a filter that always prints 0 e's.
removeFirstEFilter.then(printECountFilter)

// Returns a filter that prints the number of e's before the first one is removed.
printECountFilter.then(removeFirstEFilter)