androidx.compose.ui.focus

Interfaces

FocusEnterExitScope

Receiver scope for FocusProperties.onEnter and FocusProperties.onExit.
Cmn
FocusEventModifier

This interface is deprecated. Use FocusEventModifierNode instead
Cmn
FocusEventModifierNode

Implement this interface create a modifier node that can be used to observe focus state changes to a FocusTargetNode down the hierarchy.
Cmn
FocusManager
Cmn
FocusOrderModifier

This interface is deprecated. Use Modifier.focusProperties() instead
Cmn
FocusProperties

Properties that are applied to focusTarget that is the first child of the FocusPropertiesModifierNode that sets these properties.
Cmn
FocusPropertiesModifierNode

Implement this interface create a modifier node that can be used to modify the focus properties of the associated FocusTargetNode.
Cmn
FocusRequesterModifier

This interface is deprecated. Use FocusRequesterModifierNode instead
Cmn
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.
Cmn
FocusState

The focus state of a FocusTargetNode.
Cmn
FocusTargetModifierNode

This modifier node can be delegated to in order to create a modifier that makes a component focusable.
Cmn

Classes

FocusDirection

The FocusDirection is used to specify the direction for a FocusManager.moveFocus request.
Cmn
FocusOrder

This class is deprecated. Use FocusProperties instead
Cmn
FocusRequester

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

Focusability configures whether a focus target can be focused.
Cmn

Objects

FocusRequester.Companion
Cmn
FocusRequester.Companion.FocusRequesterFactory

Convenient way to create multiple FocusRequester instances.
Cmn

Modifiers

focusModifier

Add this modifier to a component to make it focusable.
Cmn
focusOrder

Use this modifier to specify a custom focus traversal order.
Cmn
focusProperties

This modifier allows you to specify properties that are accessible to focusTargets further down the modifier chain or on child layout nodes.
Cmn
focusRequester

Add this modifier to a component to request changes to focus.
Cmn
focusRestorer

This modifier can be used to save and restore focus to a focus group.
Cmn
focusTarget

Add this modifier to a component to make it focusable.
Cmn
onFocusChanged

Add this modifier to a component to observe focus state events.
Cmn
onFocusEvent

Add this modifier to a component to observe focus state events.
Cmn

Top-level functions summary

FocusTargetModifierNode
FocusTargetModifierNode(
    focusability: Focusability,
    onFocusChange: ((previous: FocusState, current: FocusState) -> Unit)?
)

Create a FocusTargetModifierNode that can be delegated to in order to create a modifier that makes a component focusable.
Cmn

Extension functions summary

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
Rect?

Calculates the rectangular area in this node's coordinates that corresponds to the focus area of the focused node under this FocusTargetModifierNode, including itself.
Cmn
Unit
Cmn
Boolean

Use this function to request focus.
Cmn
Boolean
DelegatableNode.requestFocusForChildInRootBounds(
    left: Int,
    top: Int,
    right: Int,
    bottom: Int
)

Attempts to request focus for the most suitable focusable child node that overlaps with the given rect area (left, top, right, bottom).
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

Top-level functions

FocusTargetModifierNode

Cmn 
fun FocusTargetModifierNode(
    focusability: Focusability = Focusability.Always,
    onFocusChange: ((previous: FocusState, current: FocusState) -> Unit)? = null
): FocusTargetModifierNode

Create a FocusTargetModifierNode that can be delegated to in order to create a modifier that makes a component focusable. Use a different instance of FocusTargetModifierNode for each focusable component.

Parameters
focusability: Focusability = Focusability.Always

the Focusability that configures focusability for this node
onFocusChange: ((previous: FocusState, current: FocusState) -> Unit)? = null

a callback invoked when the FocusTargetModifierNode.focusState changes, providing the previous state that it changed from, and the current focus state. Note that this will be invoked if the node is losing focus due to being detached from the hierarchy, but before the node is marked as detached (node.isAttached will still be true).

Extension functions

FocusRequesterModifierNode.captureFocus

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

FocusRequesterModifierNode.freeFocus

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

FocusTargetModifierNode.getFocusedRect

Cmn 
fun FocusTargetModifierNode.getFocusedRect(): Rect?

Calculates the rectangular area in this node's coordinates that corresponds to the focus area of the focused node under this FocusTargetModifierNode, including itself.

This function returns null when;

  • This node is not focused and there is no focused descendant.

  • This node is detached from the composition hierarchy.

FocusPropertiesModifierNode.invalidateFocusProperties

Cmn 
fun FocusPropertiesModifierNode.invalidateFocusProperties(): Unit

FocusRequesterModifierNode.requestFocus

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

DelegatableNode.requestFocusForChildInRootBounds

Cmn 
fun DelegatableNode.requestFocusForChildInRootBounds(
    left: Int,
    top: Int,
    right: Int,
    bottom: Int
): Boolean

Attempts to request focus for the most suitable focusable child node that overlaps with the given rect area (left, top, right, bottom).

The rectangle is interpreted in the coordinate space relative to the compose root. See androidx.compose.ui.layout.LayoutCoordinates.localToRoot for converting local coordinates to the root coordinates.

Parameters
left: Int

is the left edge of the rectangle, in pixels relative to the compose root.
top: Int

is the top edge of the rectangle, in pixels relative to the compose root.
right: Int

is the right edge of the rectangle, in pixels relative to the compose root.
bottom: Int

is the bottom edge of the rectangle, in pixels relative to the compose root.
Returns
Boolean

true if a matching child was found and focus was granted; false if no such child exists, it is already focused, or the focus request failed.

FocusRequesterModifierNode.restoreFocusedChild

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

FocusRequesterModifierNode.saveFocusedChild

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