FocusRequesterModifierNode


Implement this interface to create a modifier node that can be used to request changes in the focus state of a FocusTargetNode down the hierarchy.

Summary

Extension 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

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

Inherited properties

From androidx.compose.ui.node.DelegatableNode
Modifier.Node

A reference of the Modifier.Node that holds this node's position in the node hierarchy.

Cmn

Extension functions

captureFocus

fun FocusRequesterModifierNode.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 FocusRequesterModifierNode.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 FocusRequesterModifierNode.requestFocus(): Boolean

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 FocusRequesterModifierNode.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.

Returns
Boolean

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

saveFocusedChild

@ExperimentalComposeUiApi
fun FocusRequesterModifierNode.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.

Returns
Boolean

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