compose-focus-navigation

Compose: focus navigation

Core principle

Focus is stateful UI behavior. Make focus targets explicit, request focus after composition succeeds, and test navigation with the same input model users use: keyboard, D-pad, or remote keys.

When to use this skill

Use this when UI:

• Runs on TV, desktop, ChromeOS, keyboard-first Android, or remote-control devices.
• Uses FocusRequester, focusRequester, focusProperties, onFocusChanged, or key handlers.
• Needs initial focus, restored focus, directional navigation, or back/escape behavior.
• Has a carousel, grid, lazy list, menu, dialog, or modal with focus traps.
• Has tests asserting which item is focused.

Build focus targets deliberately

Start with components that already participate in focus, then add only the focus hooks the behavior needs:

Need	Add
Normal button/text field/clickable focus	Nothing extra; use the focusable component
Programmatic initial/restored focus	FocusRequester + Modifier.focusRequester(...)
Visual or state reaction to focus changes	Modifier.onFocusChanged { ... }
Custom interactive surface that is not already focusable	Modifier.focusable() plus role/semantics as appropriate

For example, request and observe focus only when both behaviors are needed:

val requester = remember { FocusRequester() }

Button(
    onClick = onClick,
    modifier = Modifier
        .focusRequester(requester)
        .onFocusChanged { state -> isFocused = state.isFocused },
) {
    Text("Play")
}

Prefer focusable components (Button, TextField, clickable/selectable surfaces) over manually adding focusable() to passive layout. Add manual focus only when the element is truly interactive or participates in navigation.

Request focus after composition

Call focus requests from an effect, not from the composable body:

val initialFocus = remember { FocusRequester() }

LaunchedEffect(initialFocus) {
    initialFocus.requestFocus()
}