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.Modifier
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusRequester
import androidx.compose.ui.focus.onFocusChanged
import androidx.compose.ui.graphics.Color.Companion.Black
import androidx.compose.ui.graphics.Color.Companion.Green
import androidx.compose.ui.unit.dp

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
Boolean
requestFocus(focusDirection: FocusDirection)

Use this function to request focus with a specific direction.
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

Cmn
Added in 1.0.0
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.Modifier
import androidx.compose.ui.focus.FocusRequester
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

Cmn
Added in 1.3.0
val Cancel: FocusRequester

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.Modifier
import androidx.compose.ui.focus.FocusRequester.Companion.Cancel
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

Cmn
Added in 1.0.0
val Default: 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.

Public constructors

FocusRequester

Cmn
Added in 1.0.0
@RememberInComposition
FocusRequester()

Public functions

captureFocus

Cmn
Added in 1.0.0
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.Text
import androidx.compose.material.TextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusRequester
import androidx.compose.ui.focus.onFocusChanged
import androidx.compose.ui.graphics.Color.Companion.Red
import androidx.compose.ui.graphics.Color.Companion.Transparent
import androidx.compose.ui.unit.dp

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

Cmn
Added in 1.0.0
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.Text
import androidx.compose.material.TextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusRequester
import androidx.compose.ui.focus.onFocusChanged
import androidx.compose.ui.graphics.Color.Companion.Red
import androidx.compose.ui.graphics.Color.Companion.Transparent
import androidx.compose.ui.unit.dp

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

Cmn 
fun requestFocus(focusDirection: FocusDirection = Enter): Boolean

Use this function to request focus with a specific direction. 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.Modifier
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusRequester
import androidx.compose.ui.focus.onFocusChanged
import androidx.compose.ui.graphics.Color.Companion.Black
import androidx.compose.ui.graphics.Color.Companion.Green
import androidx.compose.ui.unit.dp

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()
)
Parameters
focusDirection: FocusDirection = Enter

The direction passed to the FocusTargetModifierNode to indicate the direction that the focus request comes from.
Returns
Boolean

true if the focus was successfully requested or false if the focus request was canceled.

restoreFocusedChild

Cmn
Added in 1.6.0
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.layout.Row
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.Modifier
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 {
        onExit = { focusRequester.saveFocusedChild() }
        onEnter = { if (focusRequester.restoreFocusedChild()) cancelFocusChange() }
    }
) {
    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

Cmn
Added in 1.6.0
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.layout.Row
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.Modifier
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 {
        onExit = { focusRequester.saveFocusedChild() }
        onEnter = { if (focusRequester.restoreFocusedChild()) cancelFocusChange() }
    }
) {
    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.