FocusRequester


The FocusRequester is used in conjunction with Modifier.focusRequester to send requests to change focus.

import androidx.compose.foundation.border
import androidx.compose.foundation.clickable
import androidx.compose.foundation.focusable
import androidx.compose.foundation.layout.Box
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusRequester
import androidx.compose.ui.focus.onFocusChanged

val focusRequester = remember { FocusRequester() }
var color by remember { mutableStateOf(Black) }
Box(
    Modifier
        .clickable { focusRequester.requestFocus() }
        .border(2.dp, color)
        // The focusRequester should be added BEFORE the focusable.
        .focusRequester(focusRequester)
        // The onFocusChanged should be added BEFORE the focusable that is being observed.
        .onFocusChanged { color = if (it.isFocused) Green else Black }
        .focusable()
)
See also
focusRequester

Summary

Nested types

Convenient way to create multiple FocusRequester instances.

Public companion functions

FocusRequester.Companion.FocusRequesterFactory

Convenient way to create multiple FocusRequesters, which can to be used to request focus, or to specify a focus traversal order.

Cmn

Public companion properties

FocusRequester

Cancelled focusRequester, which when used in Modifier.focusProperties implies that we want to block focus search from proceeding in the specified direction.

Cmn
FocusRequester

Default focusRequester, which when used in Modifier.focusProperties implies that we want to use the default system focus order, that is based on the position of the items on the screen.

Cmn

Public constructors

Cmn

Public functions

Boolean

Deny requests to clear focus.

Cmn
Boolean

Use this function to send a request to free focus when one of the components associated with this FocusRequester is in a Captured state.

Cmn
Unit

Use this function to request focus.

Cmn
Boolean

Use this function to restore focus to one of the children of the node pointed to by this FocusRequester.

Cmn
Boolean

Use this function to request the focus target to save a reference to the currently focused child in its saved instance state.

Cmn

Public companion functions

createRefs

fun createRefs(): FocusRequester.Companion.FocusRequesterFactory

Convenient way to create multiple FocusRequesters, which can to be used to request focus, or to specify a focus traversal order.

import androidx.compose.foundation.focusable
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.runtime.remember
import androidx.compose.ui.focus.focusRequester

val (item1, item2, item3, item4) = remember { FocusRequester.createRefs() }
Column {
    Box(Modifier.focusRequester(item1).focusable())
    Box(Modifier.focusRequester(item2).focusable())
    Box(Modifier.focusRequester(item3).focusable())
    Box(Modifier.focusRequester(item4).focusable())
}

Public companion properties

Cancel

@ExperimentalComposeUiApi
val CancelFocusRequester

Cancelled focusRequester, which when used in Modifier.focusProperties implies that we want to block focus search from proceeding in the specified direction.

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.ui.focus.focusProperties
import androidx.compose.ui.focus.focusTarget

// If Box 2 is focused, pressing Up will not take focus to Box 1,
// But pressing Down will move focus to Box 3.
Column {
    // Box 1.
    Box(Modifier.focusTarget())
    // Box 2.
    Box(modifier = Modifier
        .focusProperties { up = Cancel }
        .focusTarget()
    )
    // Box 3.
    Box(Modifier.focusTarget())
}

Default

val DefaultFocusRequester

Default focusRequester, which when used in Modifier.focusProperties implies that we want to use the default system focus order, that is based on the position of the items on the screen.

Public constructors

FocusRequester

FocusRequester()

Public functions

captureFocus

fun captureFocus(): Boolean

Deny requests to clear focus.

Use this function to send a request to capture focus. If a component captures focus, it will send a FocusState object to its associated onFocusChanged modifiers where FocusState.isCaptured == true.

When a component is in a Captured state, all focus requests from other components are declined.

import androidx.compose.foundation.border
import androidx.compose.material.TextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusRequester
import androidx.compose.ui.focus.onFocusChanged

val focusRequester = remember { FocusRequester() }
var value by remember { mutableStateOf("apple") }
var borderColor by remember { mutableStateOf(Transparent) }
TextField(
    value = value,
    onValueChange = {
        value = it.apply {
            if (length > 5) focusRequester.captureFocus() else focusRequester.freeFocus()
        }
    },
    modifier = Modifier
        .border(2.dp, borderColor)
        .focusRequester(focusRequester)
        .onFocusChanged { borderColor = if (it.isCaptured) Red else Transparent }
)
Returns
Boolean

true if the focus was successfully captured by one of the focus modifiers associated with this FocusRequester. False otherwise.

freeFocus

fun freeFocus(): Boolean

Use this function to send a request to free focus when one of the components associated with this FocusRequester is in a Captured state. If a component frees focus, it will send a FocusState object to its associated onFocusChanged modifiers where FocusState.isCaptured == false.

When a component is in a Captured state, all focus requests from other components are declined. .

import androidx.compose.foundation.border
import androidx.compose.material.TextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusRequester
import androidx.compose.ui.focus.onFocusChanged

val focusRequester = remember { FocusRequester() }
var value by remember { mutableStateOf("apple") }
var borderColor by remember { mutableStateOf(Transparent) }
TextField(
    value = value,
    onValueChange = {
        value = it.apply {
            if (length > 5) focusRequester.captureFocus() else focusRequester.freeFocus()
        }
    },
    modifier = Modifier
        .border(2.dp, borderColor)
        .focusRequester(focusRequester)
        .onFocusChanged { borderColor = if (it.isCaptured) Red else Transparent }
)
Returns
Boolean

true if the captured focus was successfully released. i.e. At the end of this operation, one of the components associated with this focusRequester freed focus.

requestFocus

fun requestFocus(): Unit

Use this function to request focus. If the system grants focus to a component associated with this FocusRequester, its onFocusChanged modifiers will receive a FocusState object where FocusState.isFocused is true.

import androidx.compose.foundation.border
import androidx.compose.foundation.clickable
import androidx.compose.foundation.focusable
import androidx.compose.foundation.layout.Box
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusRequester
import androidx.compose.ui.focus.onFocusChanged

val focusRequester = remember { FocusRequester() }
var color by remember { mutableStateOf(Black) }
Box(
    Modifier
        .clickable { focusRequester.requestFocus() }
        .border(2.dp, color)
        // The focusRequester should be added BEFORE the focusable.
        .focusRequester(focusRequester)
        // The onFocusChanged should be added BEFORE the focusable that is being observed.
        .onFocusChanged { color = if (it.isFocused) Green else Black }
        .focusable()
)

restoreFocusedChild

@ExperimentalComposeUiApi
fun restoreFocusedChild(): Boolean

Use this function to restore focus to one of the children of the node pointed to by this FocusRequester. This restores focus to a previously focused child that was saved by using saveFocusedChild.

import androidx.compose.foundation.lazy.LazyRow
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.remember
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusProperties
import androidx.compose.ui.focus.focusRequester

val focusRequester = remember { FocusRequester() }
LazyRow(
    Modifier
        .focusRequester(focusRequester)
        .focusProperties {
            exit = { focusRequester.saveFocusedChild(); Default }
            enter = { if (focusRequester.restoreFocusedChild()) Cancel else Default }
        }
) {
    item { Button(onClick = {}) { Text("1") } }
    item { Button(onClick = {}) { Text("2") } }
    item { Button(onClick = {}) { Text("3") } }
    item { Button(onClick = {}) { Text("4") } }
}
Returns
Boolean

true if we successfully restored focus to one of the children of the focusTarget associated with this FocusRequester

saveFocusedChild

@ExperimentalComposeUiApi
fun saveFocusedChild(): Boolean

Use this function to request the focus target to save a reference to the currently focused child in its saved instance state. After calling this, focus can be restored to the saved child by making a call to restoreFocusedChild.

import androidx.compose.foundation.lazy.LazyRow
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.remember
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusProperties
import androidx.compose.ui.focus.focusRequester

val focusRequester = remember { FocusRequester() }
LazyRow(
    Modifier
        .focusRequester(focusRequester)
        .focusProperties {
            exit = { focusRequester.saveFocusedChild(); Default }
            enter = { if (focusRequester.restoreFocusedChild()) Cancel else Default }
        }
) {
    item { Button(onClick = {}) { Text("1") } }
    item { Button(onClick = {}) { Text("2") } }
    item { Button(onClick = {}) { Text("3") } }
    item { Button(onClick = {}) { Text("4") } }
}
Returns
Boolean

true if the focus target associated with this FocusRequester has a focused child and we successfully saved a reference to it.