SpatialNavigation

The SpatialNavigation singleton is the core engine of the library. In most React applications you interact with it through useFocusable and named function exports. This reference documents all public methods.

Importing

Named exports

import {
  init,
  destroy,
  setFocus,
  navigateByDirection,
  pause,
  resume,
  getCurrentFocusKey,
  doesFocusableExist,
  updateAllLayouts,
  setKeyMap,
  setThrottle,
  updateRtl,
  ROOT_FOCUS_KEY
} from '@noriginmedia/norigin-spatial-navigation-core';

---

init(config?)

Initializes the spatial navigation service. Must be called once before any components mount, typically at the top of your application module.

init(config?: {
  debug?: boolean;
  visualDebug?: boolean;
  nativeMode?: boolean;
  throttle?: number;
  throttleKeypresses?: boolean;
  useGetBoundingClientRect?: boolean;
  shouldFocusDOMNode?: boolean;
  domNodeFocusOptions?: FocusOptions;
  shouldUseNativeEvents?: boolean;
  rtl?: boolean;
  distanceCalculationMethod?: 'center' | 'edges' | 'corners';
  customDistanceCalculationFunction?: (
    refCorners: Corners,
    siblingCorners: Corners,
    isVerticalDirection: boolean,
    distanceCalculationMethod: string
  ) => number;
}): void

Config options

Option	Type	Default	Description
debug	boolean	false	Log navigation decisions to the browser console.
visualDebug	boolean	false	Draw a canvas overlay showing component bounding boxes and navigation paths.
nativeMode	boolean	false	Disable DOM key event listeners (for React Native). You must drive navigation manually.
throttle	number	0	Milliseconds to wait between processing repeated key presses. 0 means no throttle.
throttleKeypresses	boolean	false	When true and throttle > 0, throttle key repeat events while a key is held down.
useGetBoundingClientRect	boolean	false	Use getBoundingClientRect() instead of offsetLeft/Top for layout measurement. Use this when elements are CSS-transformed or scaled.
shouldFocusDOMNode	boolean	false	Call HTMLElement.focus() on the focused component's DOM node, enabling native browser focus behavior and accessibility.
domNodeFocusOptions	FocusOptions	undefined	Options passed to HTMLElement.focus() when shouldFocusDOMNode is true.
shouldUseNativeEvents	boolean	false	Do not call preventDefault() on key events, allowing the browser to handle them natively as well.
rtl	boolean	false	Enable right-to-left layout mode. Left and right navigation directions are swapped.
distanceCalculationMethod	'center' \| 'edges' \| 'corners'	'corners'	Algorithm used to calculate distance between components. See Distance Calculation.
customDistanceCalculationFunction	function	undefined	Override the secondary-axis distance calculation. See Distance Calculation.

Example

import { init } from '@noriginmedia/norigin-spatial-navigation-core';

init({
  debug: false,
  visualDebug: false,
  distanceCalculationMethod: 'center',
  throttle: 150,
  throttleKeypresses: true
});

---

destroy()

Disables the service, removes all event listeners, and clears all registered components. Call this when tearing down the application.

destroy(): void

import { destroy } from '@noriginmedia/norigin-spatial-navigation-react';

// In a test afterEach or app cleanup:
destroy();

---

setFocus(focusKey, focusDetails?)

Programmatically move focus to the component with the given focus key.

setFocus(focusKey: string, focusDetails?: FocusDetails): void

Parameter	Description
focusKey	The focus key of the target component. Use ROOT_FOCUS_KEY to focus the root, which routes to the first eligible child.
focusDetails	Optional object passed through to the target component's onFocus handler.

import {
  setFocus,
  ROOT_FOCUS_KEY
} from '@noriginmedia/norigin-spatial-navigation-react';

// Focus a specific component
setFocus('PLAY_BUTTON');

// Focus the root (boots navigation to first child)
setFocus(ROOT_FOCUS_KEY);

// Focus with context data
setFocus('MENU_ITEM_3', { event: someEvent });

---

navigateByDirection(direction, focusDetails?)

Simulate a directional key press, moving focus in the specified direction from the currently focused component.

navigateByDirection(direction: 'up' | 'down' | 'left' | 'right', focusDetails?: FocusDetails): void

import { navigateByDirection } from '@noriginmedia/norigin-spatial-navigation-react';

navigateByDirection('right');
navigateByDirection('down', { source: 'programmatic' });

---

pause()

Suspend all key event handling. Navigation stops until resume() is called. Focus state is preserved.

pause(): void

import { pause } from '@noriginmedia/norigin-spatial-navigation-react';

// While a video is playing full-screen:
pause();

---

resume()

Resume key event handling after a pause().

resume(): void

import { resume } from '@noriginmedia/norigin-spatial-navigation-react';

resume();

---

getCurrentFocusKey()

Return the focus key of the currently focused component.

getCurrentFocusKey(): string

import { getCurrentFocusKey } from '@noriginmedia/norigin-spatial-navigation-react';

const currentKey = getCurrentFocusKey();
console.log('Currently focused:', currentKey);

---

doesFocusableExist(focusKey)

Return true if a component with the given focus key is currently registered. Use this before calling setFocus to avoid errors when a component may or may not be mounted.

doesFocusableExist(focusKey: string): boolean

import {
  doesFocusableExist,
  setFocus
} from '@noriginmedia/norigin-spatial-navigation-react';

if (doesFocusableExist('SIDEBAR_ITEM_2')) {
  setFocus('SIDEBAR_ITEM_2');
}

---

updateAllLayouts()

Force the library to re-measure the screen positions of all registered components. Call this after layout changes that are invisible to React (e.g., after a CSS animation completes or after a window resize that changes element positions).

updateAllLayouts(): void

import { updateAllLayouts } from '@noriginmedia/norigin-spatial-navigation-react';

// After a scale animation finishes:
setTimeout(() => {
  updateAllLayouts();
}, 300);

---

setKeyMap(keyMap)

Override the default keyboard mapping. Accepts key codes (numbers) or key event names (strings).

setKeyMap(keyMap: {
  left?: number | string | (number | string)[];
  right?: number | string | (number | string)[];
  up?: number | string | (number | string)[];
  down?: number | string | (number | string)[];
  enter?: number | string | (number | string)[];
}): void

See Key Mapping for full documentation and examples.

---

setThrottle(options?)

Update throttle settings at runtime without reinitializing.

setThrottle(options?: {
  throttle?: number;
  throttleKeypresses?: boolean;
}): void

import { setThrottle } from '@noriginmedia/norigin-spatial-navigation-react';

// Slow down navigation for a video scrubber
setThrottle({ throttle: 200, throttleKeypresses: true });

// Remove throttling
setThrottle({ throttle: 0 });

---

updateRtl(rtl)

Toggle right-to-left mode at runtime. Useful when the user switches the application language.

updateRtl(rtl: boolean): void

import { updateRtl } from '@noriginmedia/norigin-spatial-navigation-react';

updateRtl(true); // enable RTL
updateRtl(false); // revert to LTR

See RTL Support for more.

---

ROOT_FOCUS_KEY

A constant string ('SN:ROOT') representing the root of the focus tree. Pass it to setFocus to boot navigation.

import {
  ROOT_FOCUS_KEY,
  setFocus
} from '@noriginmedia/norigin-spatial-navigation-react';

setFocus(ROOT_FOCUS_KEY);