# SelectionState

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/selection/SelectionState.kt+class:androidx.compose.foundation.text.selection.SelectionState) Added in [1.12.0](https://developer.android.com/jetpack/androidx/releases/compose-foundation#1.12.0) Common/AllAndroid/JVM
- Cmn

  ```
  class SelectionState
  ```

*** ** * ** ***

Selection state object for a particular `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionContainer.composable#SelectionContainer(androidx.compose.ui.Modifier,kotlin.Function0)`. It is invalid for the same SelectionState to be passed to multiple SelectionContainers. Holds the currently selected text and functions to perform Selection actions programmatically.

When instantiating this class from a composable, use `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/rememberSelectionState.composable#rememberSelectionState()` to automatically save and restore the selection state. For more advanced use cases, pass `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionState#Saver()` to `https://developer.android.com/reference/kotlin/androidx/compose/runtime/saveable/rememberSaveable.composable#rememberSaveable(kotlin.Array,androidx.compose.runtime.saveable.Saver,kotlin.String,kotlin.Function0)`.

```kotlin
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.text.BasicText
import androidx.compose.foundation.text.selection.SelectionContainer
import androidx.compose.foundation.text.selection.rememberSelectionState
import androidx.compose.material3.Text

val selectionState = rememberSelectionState()

val characterCount = selectionState.selectedTexts.sumOf { it.text.length }

Column {
    SelectionContainer(state = selectionState) {
        Column { BasicText(text = "Text to be selected...") }
    }
    if (characterCount > 0) {
        BasicText(text = "Characters selected: $characterCount")
    }
}
```

## Summary

| ### Public companion properties |
|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/saveable/Saver<https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionState, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html>` | `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionState#Saver()` | Cmn |

| ### Public constructors |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionState#SelectionState()()` | Cmn |

| ### Public functions |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionState#clear()()` Clears the current selection for the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionContainer.composable#SelectionContainer(androidx.compose.ui.Modifier,kotlin.Function0)` and removes selection handles. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionState#extendSelectionByWord()()` Extends the current selection to the next word boundary, if there is another word boundary available within the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionContainer.composable#SelectionContainer(androidx.compose.ui.Modifier,kotlin.Function0)`. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/compose/ui/text/AnnotatedString>` | `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionState#getSelectableTexts()()` Returns a list of all selectable texts within the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionContainer.composable#SelectionContainer(androidx.compose.ui.Modifier,kotlin.Function0)` in visual/layout order. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionState#select(androidx.compose.ui.text.TextRange)(range: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextRange)` Sets the selection to the specified `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextRange` within the global space of all Texts inside the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionContainer.composable#SelectionContainer(androidx.compose.ui.Modifier,kotlin.Function0)`. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionState#selectAll()()` Sets the current selection to include every selectable Text Composable within the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionContainer.composable#SelectionContainer(androidx.compose.ui.Modifier,kotlin.Function0)`. | Cmn |

| ### Public properties |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/compose/ui/text/AnnotatedString>` | `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionState#selectedTexts()` The currently selected texts in the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionContainer.composable#SelectionContainer(androidx.compose.ui.Modifier,kotlin.Function0)` corresponding to this SelectionState, in visual/layout order. | Cmn |

## Public companion properties

### Saver

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

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

## Public constructors

### SelectionState

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

```
SelectionState()
```

## Public functions

### clear

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

```
fun clear(): Unit
```

Clears the current selection for the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionContainer.composable#SelectionContainer(androidx.compose.ui.Modifier,kotlin.Function0)` and removes selection handles.

### extendSelectionByWord

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

```
fun extendSelectionByWord(): Unit
```

Extends the current selection to the next word boundary, if there is another word boundary available within the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionContainer.composable#SelectionContainer(androidx.compose.ui.Modifier,kotlin.Function0)`. The next word is added at the active edge of the selection, following the current text direction. So if the selection is dragged in reverse, this adds a word earlier in the text.

If the next word in the selection is in a different Text composable, this extends to the next Text. If there is no selection, this selects the first word in the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionContainer.composable#SelectionContainer(androidx.compose.ui.Modifier,kotlin.Function0)`.

Word boundaries separate words and non-words such as spaces, symbols, and punctuation. Word boundaries are defined more precisely in Unicode Standard Annex #29 <https://www.unicode.org/reports/tr29/#Word_Boundaries>.

```kotlin
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.text.BasicText
import androidx.compose.foundation.text.selection.SelectionContainer
import androidx.compose.foundation.text.selection.rememberSelectionState
import androidx.compose.material3.Button
import androidx.compose.material3.Text

val selectionState = rememberSelectionState()

Column {
    Button(onClick = { selectionState.extendSelectionByWord() }) {
        BasicText("Extend Selection to Next Word")
    }
    SelectionContainer(state = selectionState) { BasicText("Text to select: word by word") }
}
```

### getSelectableTexts

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

```
fun getSelectableTexts(): List<AnnotatedString>
```

Returns a list of all selectable texts within the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionContainer.composable#SelectionContainer(androidx.compose.ui.Modifier,kotlin.Function0)` in visual/layout order. This returns the entire text content, including all selected or unselected portions. Text nodes excluded from selection using `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/DisableSelection.composable#DisableSelection(kotlin.Function0)` will not be included in the list. Calling this function can be inefficient for containers holding a large volume of text composables.

Note: This should not be called during composition as it requires the layout to be ready.

```kotlin
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.text.BasicText
import androidx.compose.foundation.text.selection.SelectionContainer
import androidx.compose.foundation.text.selection.rememberSelectionState
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.ui.text.TextRange

val selectionState = rememberSelectionState()
val query = "Compose is great!"

Column {
    Button(
        onClick = {
            val index = selectionState.getSelectableTexts().joinToString("").indexOf(query)

            if (index != -1) {
                selectionState.select(TextRange(index, index + query.length))
            }
        }
    ) {
        BasicText("Select Quote")
    }
    SelectionContainer(state = selectionState) {
        Column {
            BasicText(text = "This UI Toolkit Compose")
            BasicText(text = " is great! :)")
        }
    }
}
```

```kotlin
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.text.BasicText
import androidx.compose.foundation.text.selection.SelectionContainer
import androidx.compose.foundation.text.selection.rememberSelectionState
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.ui.text.TextRange

val selectionState = rememberSelectionState()

Column {
    Button(
        onClick = {
            val texts = selectionState.getSelectableTexts()

            if (texts.size >= 3) {
                val globalStart = texts[0].length + texts[1].length
                val globalEnd = globalStart + texts[2].length

                selectionState.select(TextRange(globalStart, globalEnd))
            }
        }
    ) {
        BasicText("Select Third Paragraph")
    }
    SelectionContainer(state = selectionState) {
        Column {
            BasicText(text = "Paragraph 1...")
            BasicText(text = "Paragraph 2...")
            BasicText(text = "Paragraph 3...")
        }
    }
}
```

### select

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

```
fun select(range: TextRange): Unit
```

Sets the selection to the specified `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextRange` within the global space of all Texts inside the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionContainer.composable#SelectionContainer(androidx.compose.ui.Modifier,kotlin.Function0)`. This function loops through all selectables in the SelectionContainer, so it is not advised to call within a loop or as an effect that triggers frequently.

Note: This should not be called during composition as it requires the layout to be ready.

```kotlin
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.text.BasicText
import androidx.compose.foundation.text.selection.SelectionContainer
import androidx.compose.foundation.text.selection.rememberSelectionState
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.ui.text.TextRange

val selectionState = rememberSelectionState()
val query = "Compose is great!"

Column {
    Button(
        onClick = {
            val index = selectionState.getSelectableTexts().joinToString("").indexOf(query)

            if (index != -1) {
                selectionState.select(TextRange(index, index + query.length))
            }
        }
    ) {
        BasicText("Select Quote")
    }
    SelectionContainer(state = selectionState) {
        Column {
            BasicText(text = "This UI Toolkit Compose")
            BasicText(text = " is great! :)")
        }
    }
}
```

```kotlin
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.text.BasicText
import androidx.compose.foundation.text.selection.SelectionContainer
import androidx.compose.foundation.text.selection.rememberSelectionState
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.ui.text.TextRange

val selectionState = rememberSelectionState()

Column {
    Button(
        onClick = {
            val texts = selectionState.getSelectableTexts()

            if (texts.size >= 3) {
                val globalStart = texts[0].length + texts[1].length
                val globalEnd = globalStart + texts[2].length

                selectionState.select(TextRange(globalStart, globalEnd))
            }
        }
    ) {
        BasicText("Select Third Paragraph")
    }
    SelectionContainer(state = selectionState) {
        Column {
            BasicText(text = "Paragraph 1...")
            BasicText(text = "Paragraph 2...")
            BasicText(text = "Paragraph 3...")
        }
    }
}
```

### selectAll

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

```
fun selectAll(): Unit
```

Sets the current selection to include every selectable Text Composable within the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionContainer.composable#SelectionContainer(androidx.compose.ui.Modifier,kotlin.Function0)`.

Note: When using `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionContainer.composable#SelectionContainer(androidx.compose.ui.Modifier,kotlin.Function0)` with `https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/package-summary#LazyList(androidx.compose.ui.Modifier,androidx.compose.foundation.lazy.LazyListState,androidx.compose.foundation.layout.PaddingValues,kotlin.Boolean,kotlin.Boolean,androidx.compose.foundation.gestures.FlingBehavior,kotlin.Boolean,androidx.compose.foundation.OverscrollEffect,kotlin.Int,androidx.compose.ui.Alignment.Horizontal,androidx.compose.foundation.layout.Arrangement.Vertical,androidx.compose.ui.Alignment.Vertical,androidx.compose.foundation.layout.Arrangement.Horizontal,androidx.compose.foundation.lazy.layout.LazyLayoutCacheWindow,kotlin.Function1)`, selectAll will only select all selectable Text Composables that are composed.

```kotlin
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.text.BasicText
import androidx.compose.foundation.text.selection.SelectionContainer
import androidx.compose.foundation.text.selection.rememberSelectionState
import androidx.compose.material3.Button
import androidx.compose.material3.Text

val selectionState = rememberSelectionState()

Column {
    Button(onClick = { selectionState.selectAll() }) { BasicText("Select All") }
    SelectionContainer(state = selectionState) { BasicText(text = "Text to be selected...") }
}
```

## Public properties

### selectedTexts

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

```
val selectedTexts: List<AnnotatedString>
```

The currently selected texts in the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/selection/SelectionContainer.composable#SelectionContainer(androidx.compose.ui.Modifier,kotlin.Function0)` corresponding to this SelectionState, in visual/layout order. Each text composable within the Selection is returned as an AnnotatedString in the list. This field is backed by `https://developer.android.com/reference/kotlin/androidx/compose/runtime/package-summary#mutableStateOf(kotlin.Any,androidx.compose.runtime.SnapshotMutationPolicy)` so it can be observed by Composables.