SPATIAL_NAVIGATION_API.md

Spatial Navigation API

Dedicated reference for the spatial navigation primitives exported by react-native-cross-elements.

Types

FocusableViewProps

Property	Type	Description
children	ReactElement | (state: FocusableNodeState) => ReactElement	Content or render-prop with node state.
...ViewProps	React Native View props	All view props except children.
...SpatialNavigationNodeDefaultProps	-	Focus handlers plus orientation, grid alignment, index range, and additional offset.

InnerFocusableViewProps

• Same as FocusableViewProps plus a nodeState object injected by SpatialNavigationNode.
• This is an internal helper type and usually does not need to be consumed directly.

SpatialNavigationNodeDefaultProps

Property	Type	Default	Description
orientation	'horizontal' | 'vertical'	'vertical'	Orientation for spatial navigation direction.
onFocus	() => void	-	Called when the node receives focus.
onBlur	() => void	-	Called when the node loses focus.
onSelect	() => void	-	Called when the node is selected or pressed.
onLongSelect	() => void	-	Called when the node is long pressed.
onActive	() => void	-	Called when the node becomes active.
onInactive	() => void	-	Called when the node becomes inactive.
alignInGrid	boolean	false	Hint for grid alignment in LRUD navigation.
indexRange	[number, number]	-	Index range used by virtualized components.
additionalOffset	number	-	Extra scroll offset added during focus-driven scrolling.

SpatialNavigationNodeRef

Method	Signature	Description
focus	() => void	Imperatively focus the node.

SpatialNavigationVirtualizedListRef

Property / Method	Signature / Type	Description
focus	(index: number) => void	Focus an item at the given index.
scrollTo	(index: number) => void	Scroll to an item at the given index.
currentlyFocusedItemIndex	number	Last focused item index tracked by the list.

SpatialNavigationVirtualizedGridRef

• Alias of SpatialNavigationVirtualizedListRef.

CustomScrollViewRef

Method	Signature	Description
getInnerViewNode	() => any	Returns the underlying scrollable node.
scrollTo	({ x?, y?, animated }) => void	Scroll programmatically.

CustomScrollViewProps

Property	Type	Description
horizontal	boolean	Horizontal scroll mode.
scrollDuration	number	Duration for CSS-based scrolling on web.
onScroll	(event: { nativeEvent: { contentOffset: { x: number; y: number } } }) => void	Scroll event callback.
...ScrollViewProps	Omit<ScrollViewProps, 'onScroll' | 'onLayout'>	All other scroll view props.

NodeOrientation

• 'horizontal' | 'vertical'

TypeVirtualizedListAnimation

Signature	Returns	Description
({ currentlyFocusedItemIndex, vertical?, scrollDuration, scrollOffsetsArray })	Animated.WithAnimatedValue<ViewStyle>	Computes the animated style for list transitions.

Components

SpatialNavigationRoot

Top-level provider that enables spatial navigation, remote handling, and focus management.

Prop	Type	Default	Description
isActive	boolean	true	Locks or unlocks the root. Set false to disable focus handling for an inactive screen.
onDirectionHandledWithoutMovement	(direction: 'up' | 'down' | 'left' | 'right') => void	-	Called when navigation reaches a border without moving focus. Useful for switching between sibling roots such as a side menu and page content.
children	ReactNode	required	Subtree controlled by this navigation root.

SpatialNavigationView

Container that participates in spatial navigation when a root exists. Otherwise it falls back to a regular view.

Prop	Type	Default	Description
children	React.ReactNode	required	Content to render. Can include focusable descendants.
direction	'horizontal' | 'vertical'	'horizontal'	Layout direction for arranging children.
alignInGrid	boolean	false	Hint to align focusable children as a grid.
...ViewProps	Omit<ViewProps, 'children' | 'accessibilityState' | 'accessibilityRole'>	-	Pass-through view props.

SpatialNavigationScrollView

Scroll view that keeps the focused child visible while navigating with a remote or keyboard.

Prop	Type	Default	Description
horizontal	boolean	false	Horizontal scroll direction.
offsetFromStart	number	0	Extra margin from the start edge when auto-scrolling to a focused element.
pointerScrollSpeed	number	10	Pixels scrolled every 10ms while hovering the arrow areas with a remote pointer.
useNativeScroll	boolean	false	Use native ScrollView instead of the CSS-based web implementation.
scrollDuration	number	200	Duration for CSS-based smooth scrolling on web.
ascendingArrow	ReactElement	-	Arrow rendered in the up or left control area.
descendingArrow	ReactElement	-	Arrow rendered in the down or right control area.
ascendingArrowContainerStyle	ViewStyle	-	Style for the up or left hover area.
descendingArrowContainerStyle	ViewStyle	-	Style for the down or right hover area.
...CustomScrollViewProps	CustomScrollViewProps	-	All custom/native scroll view props.

SpatialNavigationFocusableView

Focusable wrapper that renders a view and exposes node state to its children.

• See FocusableViewProps above.
• Use the render-prop form of children when you need isFocused, isActive, or isRootActive.

SpatialNavigationNode

Low-level focusable node used internally by SpatialNavigationFocusableView.

• Exposes focus lifecycle hooks and imperative focus via SpatialNavigationNodeRef.
• Accepts SpatialNavigationNodeDefaultProps plus either a focusable render-prop child or a non-focusable child.

SpatialNavigationVirtualizedList

Virtualized list integrated with spatial navigation.

• Exposes focus(index) and scrollTo(index) through SpatialNavigationVirtualizedListRef.
• Tracks currentlyFocusedItemIndex on the ref for consumers coordinating external state.

SpatialNavigationVirtualizedGrid

Virtualized grid variant exposing the same ref API as the list.

DefaultFocus

Marks a node as initially focused inside a subtree when the root activates.

SpatialNavigationDeviceTypeProvider

Provider that detects whether the current interaction mode is pointer or remote-oriented and adapts focus behavior accordingly.