Selection state object for a particular SelectionContainer. 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 rememberSelectionState to automatically save and restore the selection state. For more advanced use cases, pass SelectionState.Saver to rememberSaveable.

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.material.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
Saver<SelectionState, Any>
Cmn

Public constructors
Cmn

Public functions
Unit

Clears the current selection for the SelectionContainer and removes selection handles.
Cmn
Unit

Extends the current selection to the next word boundary, if there is another word boundary available within the SelectionContainer.
Cmn
List<AnnotatedString>

Returns a list of all selectable texts within the SelectionContainer in visual/layout order.
Cmn
Unit
select(range: TextRange)

Sets the selection to the specified TextRange within the global space of all Texts inside the SelectionContainer.
Cmn
Unit

Sets the current selection to include every selectable Text Composable within the SelectionContainer.
Cmn

Public properties
List<AnnotatedString>

The currently selected texts in the SelectionContainer corresponding to this SelectionState, in visual/layout order.
Cmn

Public companion properties

Saver

Cmn 
val Saver: Saver<SelectionState, Any>

Public constructors

SelectionState

Cmn 
SelectionState()

Public functions

clear

Cmn 
fun clear(): Unit

Clears the current selection for the SelectionContainer and removes selection handles.

extendSelectionByWord

Cmn 
fun extendSelectionByWord(): Unit

Extends the current selection to the next word boundary, if there is another word boundary available within the SelectionContainer. 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 SelectionContainer.

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.

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.material.Button
import androidx.compose.material.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 
fun getSelectableTexts(): List<AnnotatedString>

Returns a list of all selectable texts within the SelectionContainer in visual/layout order. This returns the entire text content, including all selected or unselected portions. Text nodes excluded from selection using DisableSelection 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.

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.material.Button
import androidx.compose.material.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! :)")
        }
    }
}
 
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.material.Button
import androidx.compose.material.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 
fun select(range: TextRange): Unit

Sets the selection to the specified TextRange within the global space of all Texts inside the SelectionContainer. 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.

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.material.Button
import androidx.compose.material.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! :)")
        }
    }
}
 
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.material.Button
import androidx.compose.material.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 
fun selectAll(): Unit

Sets the current selection to include every selectable Text Composable within the SelectionContainer.

Note: When using SelectionContainer with androidx.compose.foundation.lazy.LazyList, selectAll will only select all selectable Text Composables that are composed.

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.material.Button
import androidx.compose.material.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 
val selectedTexts: List<AnnotatedString>

The currently selected texts in the SelectionContainer 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 androidx.compose.runtime.mutableStateOf so it can be observed by Composables.