useArrowNavigation

The useArrowNavigation hook provides keyboard navigation for interactive elements using arrow keys. It supports row, column, and grid layouts with customizable behavior. Used in components: DropdownWrapper, EmojiPicker, Select, ContextMenu, MegaMenu

Most of the time you don't need to use this hook directly. Components like DropdownWrapper, Select, and MegaMenu already provide built-in keyboard navigation. Use this hook when building custom navigable interfaces that aren't covered by existing components.

Features

Arrow key navigation (up, down, left, right)
Support for row, column, and grid layouts
Automatic focus management
Enter/Space key selection
Optional wrapping at boundaries
Visual focus highlighting
ARIA-compliant accessibility

Basic usage

Add arrow navigation to a list:

NavigableList.tsx

import { useRef } from 'react';
import { useArrowNavigation } from '@once-ui-system/core';

function NavigableList({ items }: { items: string[] }) {
const containerRef = useRef(null);

const { handleKeyDown, focusedIndex } = useArrowNavigation({
  layout: 'column',
  itemCount: items.length,
  containerRef,
  onSelect: (index) => console.log('Selected:', items[index])
});

return (
  <Column ref={containerRef} onKeyDown={handleKeyDown}>
    {items.map((item, index) => (
      <Button
        key={index}
        data-focused={focusedIndex === index}
      >
        {item}
      </Button>
    ))}
  </Column>
);
}

Grid layout

Navigate a grid with arrow keys:

EmojiGrid.tsx

import { useRef } from 'react';
import { useArrowNavigation } from '@once-ui-system/core';

function EmojiGrid({ emojis }: { emojis: string[] }) {
const containerRef = useRef(null);

const { handleKeyDown, focusedIndex } = useArrowNavigation({
  layout: 'grid',
  itemCount: emojis.length,
  columns: 8,
  containerRef,
  onSelect: (index) => selectEmoji(emojis[index]),
  wrap: true
});

return (
  <Grid
    ref={containerRef}
    onKeyDown={handleKeyDown}
    role="grid"
    columns={8}
  >
    {emojis.map((emoji, index) => (
      <Button
        key={index}
        role="gridcell"
        data-focused={focusedIndex === index}
      >
        {emoji}
      </Button>
    ))}
  </Grid>
);
}

Row layout

Navigate horizontally:

TabNavigation.tsx

function TabNavigation({ tabs }: { tabs: Tab[] }) {
const containerRef = useRef(null);

const { handleKeyDown, focusedIndex } = useArrowNavigation({
  layout: 'row',
  itemCount: tabs.length,
  containerRef,
  onSelect: (index) => setActiveTab(tabs[index].id),
  wrap: true
});

return (
  <Row ref={containerRef} onKeyDown={handleKeyDown} role="tablist">
    {tabs.map((tab, index) => (
      <Button
        key={tab.id}
        role="tab"
        aria-selected={focusedIndex === index}
      >
        {tab.label}
      </Button>
    ))}
  </Row>
);
}

API Reference

Prop	Type	Default
layout	'row''column''grid'	—
itemCount	number	—
columns	number	8
containerRef	RefObject<HTMLElement>	—
onSelect	(index: number) => void	—
onFocusChange	(index: number) => void	—
wrap	boolean	true
initialFocusedIndex	number	-1
itemSelector	string	'[role="option"], [data-value], button'
autoFocus	boolean	false
disabled	boolean	false
disableHighlighting	boolean	false

Return value

Return type

{
handleKeyDown: (e: KeyboardEvent) => void;
focusedIndex: number;
setFocusedIndex: (index: number) => void;
resetFocus: () => void;
}

Keyboard controls

Arrow Up: Move focus up (column/grid)
Arrow Down: Move focus down (column/grid)
Arrow Left: Move focus left (row/grid)
Arrow Right: Move focus right (row/grid)
Enter/Space: Select focused item
Home: Focus first item
End: Focus last item

Styling focused items

Use the focusedIndex to style the focused item:

StyledList.tsx

function StyledList() {
const { handleKeyDown, focusedIndex } = useArrowNavigation({
  layout: 'column',
  itemCount: items.length
});

return (
  <div onKeyDown={handleKeyDown}>
    {items.map((item, index) => (
      <button
        key={index}
        className={focusedIndex === index ? 'focused' : ''}
        style={{
          outline: focusedIndex === index ? '2px solid blue' : 'none',
          transform: focusedIndex === index ? 'scale(1.05)' : 'scale(1)'
        }}
      >
        {item}
      </button>
    ))}
  </div>
);
}

Accessibility

The hook automatically manages:

Focus visibility with visual indicators
ARIA roles and attributes
Keyboard event handling
Focus trap within container

For best accessibility, add appropriate ARIA attributes:

Accessible list

<div
ref={containerRef}
onKeyDown={handleKeyDown}
role="listbox"
aria-label="Options"
>
{items.map((item, index) => (
  <div
    key={index}
    role="option"
    aria-selected={focusedIndex === index}
    tabIndex={focusedIndex === index ? 0 : -1}
  >
    {item}
  </div>
))}
</div>

Used in components

This hook is used internally by:

EmojiPicker
Dropdown
Select
ContextMenu
MegaMenu