FocusRequester

Added in 1.0.0

Cmn
```
class 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
`object FocusRequester.Companion`
`object FocusRequester.Companion.FocusRequesterFactory` Convenient way to create multiple `FocusRequester` instances.

Public companion functions
`FocusRequester.Companion.FocusRequesterFactory`	`createRefs()` Convenient way to create multiple `FocusRequester`s, which can to be used to request focus, or to specify a focus traversal order.	Cmn

Public companion properties
`FocusRequester`	`Cancel` 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` 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
`FocusRequester()`	Cmn

Public functions
`Boolean`	`captureFocus()` Deny requests to clear focus.	Cmn
`Boolean`	`freeFocus()` 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`	`requestFocus()` Use this function to request focus.	Cmn
`Boolean`	`restoreFocusedChild()` Use this function to restore focus to one of the children of the node pointed to by this `FocusRequester`.	Cmn
`Boolean`	`saveFocusedChild()` 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

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

Added in 1.0.0

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.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()
)

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()) cancelFocus() }
    }
) {
    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()) cancelFocus() }
    }
) {
    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.

FocusRequester

Summary

Nested types

Public companion functions

Public companion properties

Public constructors

Public functions

Public companion functions

createRefs

Public companion properties

Cancel

Default

Public constructors

FocusRequester

Public functions

captureFocus

freeFocus

requestFocus

restoreFocusedChild

saveFocusedChild