hierarchicalFocusGroup

public fun Modifier.hierarchicalFocusGroup(active: Boolean): Modifier

hierarchicalFocusGroup is used to annotate composables in an application, so we can keep track of what is the active part of the composition. In turn, this is used to coordinate focus in a declarative way, requesting focus when needed, as the user navigates through the app (such as between screens or between pages within a screen). In most cases, this is automatically handled by Wear Compose components and no action is necessary. In particular this is done by BasicSwipeToDismissBox, HorizontalPager, VerticalPager and PickerGroup. This modifier is useful if you implement a custom component that needs to direct focus to one of several children, like a custom Pager, a Tabbed layout, etc.

hierarchicalFocusGroups can be nested to form a focus tree, with an implicit root. For sibling hierarchicalFocusGroups, only one should have active = true. Within the focus tree, components that need to request focus can do so using Modifier.requestFocusOnHierarchyActive. Note that ScalingLazyColumn and TransformingLazyColumn are using it already, so there is no need to add it explicitly.

When focus changes, the focus tree is examined and the topmost (closest to the root of the tree) requestFocusOnHierarchyActive which has all its hierarchicalFocusGroup ancestors with active = true will request focus. If no such requestFocusOnHierarchyActive exists, the focus will be cleared.

NOTE: This shouldn't be used together with FocusRequester.requestFocus calls in LaunchedEffect.

Sample using nested hierarchicalFocusGroup:

Parameters