Navigable

A container that provides predefined focus navigation behaviors to components.

You can use this instead of providing custom code to override default the focus management behavior.

Reference

The Navigable component is available by importing the Navigable library.

import { Navigable } from '@amzn/react-native-kepler/Libraries/Navigable/Navigable';

Props

blockEdges

Specifies how navigation is applied at the edges of a horizontal or vertical Navigable component.

For example, If you have Vertical Navigable component, and you want focus to not move from the down most element, then you can set blockEdges to 'end'. The focus doesn't move away from down most element of the vertical Navigable component, even if the down key is pressed.

defaultFocusItem

Specifies the default item to select when focus moves to the Navigable component. This is applicable:

• when focus moves to the Navigable component for the first time
• when focus leaves the Navigable component, and focus moves back to the Navigable component with retainLastFocus set to false.

The argument is a component tag (which you can access with findNodeHandle).

loopFocus

Specifies whether to loop focus in the direction of Strategy. For example, in a Horizontal Navigable, right key press on last item movse focus to first item and left key press on first item moves focus to last item.

navigationStrategy

Specifies whether the next focusable item is horizontally or vertically navigable. Key input along the navigationStrategy axis moves focus to the previous or next item and key input perpendicular to the axis moves focus out of the current Navigable component. If the width of Navigable component is smaller than the required width, then the items are wrapped to next line. In that case a down key press might select an item within same Navigable component. Keys along the axis or navigation select the previous and next focusable item. Keys along the alternate axis behave 'normally'. This is normal, cartesian based focused management. For more information, see the loopFocus property.

retainLastFocus

Specifies whether to set focus on last focused item when focus is moved from outside to the Navigable component. If true, on first visit to the Navigable component, the default focused item is selected (if available) or the closest item is selected. On subsequent visits to the Navigable component, the last selected item is selected.

Usage

In the following example, the loopFocus prop is set to true and the fourth item is set to not focusable (focusable prop is set to false). Navigation is set to be blocked at the end side, but the loopFocus setting has priority and the blockEndEdge prop is ignored.

<Navigable navigationStrategy="V" loopFocus={true} blockEdges="end" style={styles.navigable} >
    <Card txt={'1'} width={130} />
    <Card txt={'2'} width={130} />
    <Card txt={'3'} width={130} />
    <Card txt={'4'} width={130} focusable={false} />
    <Card txt={'5'} width={130} />
</Navigable>

References

• TVFocusGuideView
• FocusManager TM

Known Issues

• navigationStrategy sometimes fails to set correctly on first mount. The exact situations where this occurs are unclear, but it's been observed to fail when using native refs and defaultFocusItem.

Last updated: Sep 30, 2025