# TextFieldValue

Artifact: [androidx.compose.ui:ui-text](https://developer.android.com/jetpack/androidx/releases/compose-ui) [View Source](https://cs.android.com/search?q=file:androidx/compose/ui/text/input/TextFieldValue.kt+class:androidx.compose.ui.text.input.TextFieldValue) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.0.0) Common/AllAndroid/JVM
- Cmn

  ```
  class TextFieldValue
  ```

*** ** * ** ***

A class holding information about the editing state.

The input service updates text selection, cursor, text and text composition. This class represents those values and it is possible to observe changes to those values in the text editing composables.

This class stores a snapshot of the input state of the edit buffer and provide utility functions for answering IME requests such as getTextBeforeCursor, getSelectedText.

Input service composition is an instance of text produced by IME. An example visual for the composition is that the currently composed word is visually separated from others with underline, or text background. For description of composition please check [W3C IME Composition](https://www.w3.org/TR/ime-api/#ime-composition).

IME composition is defined by `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#(androidx.compose.ui.text.AnnotatedString,androidx.compose.ui.text.TextRange,androidx.compose.ui.text.TextRange)` parameter and function. When a `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue` with null `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#(androidx.compose.ui.text.AnnotatedString,androidx.compose.ui.text.TextRange,androidx.compose.ui.text.TextRange)` is passed to a TextField, if there was an active `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#(androidx.compose.ui.text.AnnotatedString,androidx.compose.ui.text.TextRange,androidx.compose.ui.text.TextRange)` on the text, the changes will be applied. Applying a composition will accept the changes that were still being composed by IME. Please use `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#copy(androidx.compose.ui.text.AnnotatedString,androidx.compose.ui.text.TextRange,androidx.compose.ui.text.TextRange)` functions if you do not want to intentionally apply the ongoing IME composition.

## Summary

| ### Public companion properties |
|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/saveable/Saver<https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html>` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#Saver()` The default `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#Saver()` implementation for `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue`. | Cmn |

| ### Public constructors |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#TextFieldValue(androidx.compose.ui.text.AnnotatedString,androidx.compose.ui.text.TextRange,androidx.compose.ui.text.TextRange)( annotatedString: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/AnnotatedString, selection: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextRange, composition: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextRange? )` | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#TextFieldValue(kotlin.String,androidx.compose.ui.text.TextRange,androidx.compose.ui.text.TextRange)(text: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, selection: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextRange, composition: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextRange?)` | Cmn |

| ### Public functions |
|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#copy(androidx.compose.ui.text.AnnotatedString,androidx.compose.ui.text.TextRange,androidx.compose.ui.text.TextRange)( annotatedString: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/AnnotatedString, selection: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextRange, composition: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextRange? )` Returns a copy of the TextFieldValue. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#copy(kotlin.String,androidx.compose.ui.text.TextRange,androidx.compose.ui.text.TextRange)(text: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, selection: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextRange, composition: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextRange?)` Returns a copy of the TextFieldValue. | Cmn |
| `open operator https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#equals(kotlin.Any)(other: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?)` | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#hashCode()()` | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#toString()()` | Cmn |

| ### Public properties |
|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/AnnotatedString` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#annotatedString()` the text to be rendered. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextRange?` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#composition()` Composition range created by IME. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextRange` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#selection()` The selection range. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#text()` | Cmn |

| ### Extension functions |
|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/AnnotatedString` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue.https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#(androidx.compose.ui.text.input.TextFieldValue).getSelectedText()()` Returns the currently selected text. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/AnnotatedString` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue.https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#(androidx.compose.ui.text.input.TextFieldValue).getTextAfterSelection(kotlin.Int)(maxChars: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Returns the text after the selection. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/AnnotatedString` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue.https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#(androidx.compose.ui.text.input.TextFieldValue).getTextBeforeSelection(kotlin.Int)(maxChars: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Returns the text before the selection. | Cmn |

## Public companion properties

### Saver

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.0.0)

```
val Saver: Saver<TextFieldValue, Any>
```

The default `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#Saver()` implementation for `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue`.

## Public constructors

### TextFieldValue

Cmn Added in [1.9.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.9.0)

```
TextFieldValue(
    annotatedString: AnnotatedString,
    selection: TextRange = TextRange.Zero,
    composition: TextRange? = null
)
```

| Parameters |
|---|---|
| `annotatedString: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/AnnotatedString` | the text to be rendered. |
| `selection: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextRange = TextRange.Zero` | the selection range. If the selection is collapsed, it represents cursor location. When selection range is out of bounds, it is constrained with the text length. |
| `composition: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextRange? = null` | the composition range, null means empty composition or apply if a composition exists on the text. Owned by IME, and if you have an instance of `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue` please use `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#copy(androidx.compose.ui.text.AnnotatedString,androidx.compose.ui.text.TextRange,androidx.compose.ui.text.TextRange)` functions if you do not want to intentionally change the value of this field. |

### TextFieldValue

Cmn Added in [1.9.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.9.0)

```
TextFieldValue(
    text: String = "",
    selection: TextRange = TextRange.Zero,
    composition: TextRange? = null
)
```

| Parameters |
|---|---|
| `text: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html = ""` | the text to be rendered. |
| `selection: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextRange = TextRange.Zero` | the selection range. If the selection is collapsed, it represents cursor location. When selection range is out of bounds, it is constrained with the text length. |
| `composition: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextRange? = null` | the composition range, null means empty composition or apply if a composition exists on the text. Owned by IME, and if you have an instance of `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue` please use `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#copy(androidx.compose.ui.text.AnnotatedString,androidx.compose.ui.text.TextRange,androidx.compose.ui.text.TextRange)` functions if you do not want to intentionally change the value of this field. |

## Public functions

### copy

Cmn Added in [1.10.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.10.0)

```
fun copy(
    annotatedString: AnnotatedString = this.annotatedString,
    selection: TextRange = this.selection,
    composition: TextRange? = this.composition
): TextFieldValue
```

Returns a copy of the TextFieldValue.

### copy

Cmn Added in [1.10.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.10.0)

```
fun copy(
    text: String,
    selection: TextRange = this.selection,
    composition: TextRange? = this.composition
): TextFieldValue
```

Returns a copy of the TextFieldValue.

### equals

Cmn

```
open operator fun equals(other: Any?): Boolean
```

### hashCode

Cmn

```
open fun hashCode(): Int
```

### toString

Cmn

```
open fun toString(): String
```

## Public properties

### annotatedString

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.0.0)

```
val annotatedString: AnnotatedString
```

the text to be rendered.

### composition

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.0.0)

```
val composition: TextRange?
```

Composition range created by IME. If null, there is no composition range.

Input service composition is an instance of text produced by IME. An example visual for the composition is that the currently composed word is visually separated from others with underline, or text background. For description of composition please check [W3C IME Composition](https://www.w3.org/TR/ime-api/#ime-composition)

Composition can be set on the by the system, however it is possible to apply an existing composition by setting the value to null. Applying a composition will accept the changes that were still being composed by IME.

### selection

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.0.0)

```
val selection: TextRange
```

The selection range. If the selection is collapsed, it represents cursor location. When selection range is out of bounds, it is constrained with the text length.

### text

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.0.0)

```
val text: String
```

## Extension functions

### TextFieldValue.getSelectedText

Cmn Artifact: [androidx.compose.ui:ui-text](https://developer.android.com/jetpack/androidx/releases/compose-ui) [View Source](https://cs.android.com/search?q=file:androidx/compose/ui/text/input/TextFieldValue.kt+function:getSelectedText)

```
fun TextFieldValue.getSelectedText(): AnnotatedString
```

Returns the currently selected text.

### TextFieldValue.getTextAfterSelection

Cmn Artifact: [androidx.compose.ui:ui-text](https://developer.android.com/jetpack/androidx/releases/compose-ui) [View Source](https://cs.android.com/search?q=file:androidx/compose/ui/text/input/TextFieldValue.kt+function:getTextAfterSelection)

```
fun TextFieldValue.getTextAfterSelection(maxChars: Int): AnnotatedString
```

Returns the text after the selection.

| Parameters |
|---|---|
| `maxChars: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | maximum number of characters (exclusive) after the maximum value in `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#selection()`. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextRange#max()` |   |

### TextFieldValue.getTextBeforeSelection

Cmn Artifact: [androidx.compose.ui:ui-text](https://developer.android.com/jetpack/androidx/releases/compose-ui) [View Source](https://cs.android.com/search?q=file:androidx/compose/ui/text/input/TextFieldValue.kt+function:getTextBeforeSelection)

```
fun TextFieldValue.getTextBeforeSelection(maxChars: Int): AnnotatedString
```

Returns the text before the selection.

| Parameters |
|---|---|
| `maxChars: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | maximum number of characters (inclusive) before the minimum value in `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/TextFieldValue#selection()`. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextRange#min()` |   |