SpatialNavigationFocusableView

iOS

Android

Web

TV

Wraps a View into a focusable spatial navigation node. Exposes isFocused state to children via a render-prop and fires lifecycle events — onFocus, onBlur, onSelect, onLongSelect.

Import

tsx

import { SpatialNavigationFocusableView, SpatialNavigationView, SpatialNavigationNode, DefaultFocus, type SpatialNavigationNodeRef, } from 'react-native-cross-elements';

Usage with SpatialNavigationView

focusable-view.tsx

Tab or click to focus

Card A

Card B

Card C

Nest SpatialNavigationFocusableView inside a SpatialNavigationView to define the navigation direction between siblings.

tsx

import { Text } from 'react-native'; import { SpatialNavigationRoot, SpatialNavigationView, SpatialNavigationFocusableView, SpatialNavigationDeviceTypeProvider, } from 'react-native-cross-elements'; export default function Example() { return ( <SpatialNavigationDeviceTypeProvider> <SpatialNavigationRoot> {/* Row of focusable cards */} <SpatialNavigationView direction="horizontal"> {['Card A', 'Card B', 'Card C'].map((label) => ( <SpatialNavigationFocusableView key={label} onSelect={() => console.log('selected', label)} style={{ margin: 8, padding: 20, borderRadius: 12 }} > {({ isFocused }) => ( <Text style={{ color: isFocused ? '#fff' : '#a1a1aa', backgroundColor: isFocused ? '#6366f1' : '#18181b', padding: 16, borderRadius: 10, }} > {label} </Text> )} </SpatialNavigationFocusableView> ))} </SpatialNavigationView> </SpatialNavigationRoot> </SpatialNavigationDeviceTypeProvider> ); }

DefaultFocus

Wrap a node in DefaultFocus to make it the initial focused element when its parent root activates.

tsx

import { DefaultFocus, SpatialNavigationFocusableView } from 'react-native-cross-elements'; // Mark a subtree as initially focused when the parent activates <DefaultFocus> <SpatialNavigationFocusableView onSelect={() => {}}> {({ isFocused }) => <MyCard focused={isFocused} />} </SpatialNavigationFocusableView> </DefaultFocus>

Programmatic focus via SpatialNavigationNode

Use the lower-level SpatialNavigationNode with a ref typed as SpatialNavigationNodeRef to focus a node programmatically.

tsx

import { SpatialNavigationNode, type SpatialNavigationNodeRef } from 'react-native-cross-elements'; const nodeRef = React.useRef<SpatialNavigationNodeRef>(null); <SpatialNavigationNode ref={nodeRef} onSelect={() => {}}> <MyItem /> </SpatialNavigationNode> // Focus programmatically nodeRef.current?.focus();

Accessibility

ℹ️

SpatialNavigationFocusableView automatically applies the correct accessibility props via the useSpatialNavigatorFocusableAccessibilityProps hook. You can also call this hook directly to apply nav accessibility props to your own components.

FocusableView props

Prop

Type

Default

Description

children

req

ReactNode | (state: { isFocused }) => ReactNode

—

Content or render-prop receiving focus state.

onFocus

() => void

—

Called when this node receives focus.

onBlur

() => void

—

Called when this node loses focus.

onSelect

() => void

—

Called when the select action fires on this node.

onLongSelect

() => void

—

Called on long press / long select.

style

ViewStyle

—

Container style.

viewProps

ViewProps

—

Additional props forwarded to the inner View.

SpatialNavigationNode props

Prop

Type

Default

Description

onFocus

() => void

—

Called on focus.

onBlur

() => void

—

Called on blur.

onSelect

() => void

—

Called on select action.

onActive

() => void

—

Called when the node becomes active.

onInactive

() => void

—

Called when the node becomes inactive.

orientation

NodeOrientation

—

Layout orientation for child focus propagation.

isFocusable

boolean

true

Whether this node can receive focus.

children

req

ReactNode

—

Navigable children.