Roving Focus

Auto-generate your docs

RovingFocusGroup provides a robust implementation of the roving tabindex pattern, allowing users to navigate through a group of focusable items using arrow keys while maintaining a single tab stop.

Installation

npm install @radix-ui/react-roving-focus

Components

RovingFocusGroup

The root component that manages focus state for all items within the group.

interface RovingFocusGroupProps extends PrimitiveDivProps {
  orientation?: 'horizontal' | 'vertical' | 'both';
  dir?: 'ltr' | 'rtl';
  loop?: boolean;
  currentTabStopId?: string | null;
  defaultCurrentTabStopId?: string;
  onCurrentTabStopIdChange?: (tabStopId: string | null) => void;
  onEntryFocus?: (event: Event) => void;
  preventScrollOnEntryFocus?: boolean;
}

RovingFocusGroupItem

Represents a focusable item within the group.

interface RovingFocusItemProps extends PrimitiveSpanProps {
  tabStopId?: string;
  focusable?: boolean;
  active?: boolean;
}

Props

RovingFocusGroup

'horizontal' | 'vertical' | 'both'

The orientation of the group, which determines which arrow keys navigate between items:

horizontal: Left/Right arrows
vertical: Up/Down arrows
both: All arrow keys

'ltr' | 'rtl'

The reading direction. Affects horizontal keyboard navigation.

boolean

Whether keyboard navigation should wrap around when reaching the first or last item.Default: false

string | null

The controlled tab stop id. Use with onCurrentTabStopIdChange for controlled mode.

string

The default tab stop id for uncontrolled mode.

(tabStopId: string | null) => void

Callback fired when the current tab stop changes.

(event: Event) => void

Event handler called when focus enters the group. Can be prevented.

boolean

Whether to prevent scrolling when focus enters the group.Default: false

Usage

import { RovingFocusGroup, RovingFocusGroupItem } from '@radix-ui/react-roving-focus';

function Toolbar() {
  return (
    <RovingFocusGroup orientation="horizontal">
      <RovingFocusGroupItem asChild>
        <button>Cut</button>
      </RovingFocusGroupItem>
      <RovingFocusGroupItem asChild>
        <button>Copy</button>
      </RovingFocusGroupItem>
      <RovingFocusGroupItem asChild>
        <button>Paste</button>
      </RovingFocusGroupItem>
    </RovingFocusGroup>
  );
}

Vertical List with Looping

import { RovingFocusGroup, RovingFocusGroupItem } from '@radix-ui/react-roving-focus';

function Menu() {
  return (
    <RovingFocusGroup orientation="vertical" loop>
      <RovingFocusGroupItem asChild>
        <div role="menuitem">New File</div>
      </RovingFocusGroupItem>
      <RovingFocusGroupItem asChild>
        <div role="menuitem">Open</div>
      </RovingFocusGroupItem>
      <RovingFocusGroupItem asChild>
        <div role="menuitem">Save</div>
      </RovingFocusGroupItem>
      <RovingFocusGroupItem asChild>
        <div role="menuitem">Exit</div>
      </RovingFocusGroupItem>
    </RovingFocusGroup>
  );
}

Controlled Focus State

import { RovingFocusGroup, RovingFocusGroupItem } from '@radix-ui/react-roving-focus';
import { useState } from 'react';

function ControlledToolbar() {
  const [currentItem, setCurrentItem] = useState<string | null>('item-1');

  return (
    <div>
      <p>Current item: {currentItem}</p>
      <RovingFocusGroup 
        orientation="horizontal"
        currentTabStopId={currentItem}
        onCurrentTabStopIdChange={setCurrentItem}
      >
        <RovingFocusGroupItem tabStopId="item-1" asChild>
          <button>Item 1</button>
        </RovingFocusGroupItem>
        <RovingFocusGroupItem tabStopId="item-2" asChild>
          <button>Item 2</button>
        </RovingFocusGroupItem>
        <RovingFocusGroupItem tabStopId="item-3" asChild>
          <button>Item 3</button>
        </RovingFocusGroupItem>
      </RovingFocusGroup>
    </div>
  );
}

import { RovingFocusGroup, RovingFocusGroupItem } from '@radix-ui/react-roving-focus';

function ColorPicker() {
  const colors = [
    ['red', 'orange', 'yellow'],
    ['green', 'blue', 'purple'],
    ['pink', 'brown', 'gray'],
  ];

  return (
    <RovingFocusGroup orientation="both" loop>
      {colors.map((row, i) => (
        <div key={i} style={{ display: 'flex' }}>
          {row.map((color) => (
            <RovingFocusGroupItem key={color} asChild>
              <button
                style={{
                  width: 40,
                  height: 40,
                  backgroundColor: color,
                }}
                aria-label={color}
              />
            </RovingFocusGroupItem>
          ))}
        </div>
      ))}
    </RovingFocusGroup>
  );
}

With Disabled Items

import { RovingFocusGroup, RovingFocusGroupItem } from '@radix-ui/react-roving-focus';

function MenuWithDisabledItems() {
  return (
    <RovingFocusGroup orientation="vertical">
      <RovingFocusGroupItem asChild>
        <button>New</button>
      </RovingFocusGroupItem>
      <RovingFocusGroupItem focusable={false} asChild>
        <button disabled>Save (disabled)</button>
      </RovingFocusGroupItem>
      <RovingFocusGroupItem asChild>
        <button>Exit</button>
      </RovingFocusGroupItem>
    </RovingFocusGroup>
  );
}

RTL Support

import { RovingFocusGroup, RovingFocusGroupItem } from '@radix-ui/react-roving-focus';

function RTLToolbar() {
  return (
    <RovingFocusGroup orientation="horizontal" dir="rtl">
      <RovingFocusGroupItem asChild>
        <button>جديد</button>
      </RovingFocusGroupItem>
      <RovingFocusGroupItem asChild>
        <button>حفظ</button>
      </RovingFocusGroupItem>
      <RovingFocusGroupItem asChild>
        <button>خروج</button>
      </RovingFocusGroupItem>
    </RovingFocusGroup>
  );
}

Keyboard Interactions

Moves focus to the current tab stop (or first item if none is set).

vertical orientation

Moves focus to the next item.

vertical orientation

Moves focus to the previous item.

horizontal orientation

Moves focus to the next item (in LTR) or previous item (in RTL).

horizontal orientation

Moves focus to the previous item (in LTR) or next item (in RTL).

Moves focus to the first item.

Moves focus to the last item.

Accessibility

The roving tabindex pattern:

Maintains only one tab stop in the group
Uses arrow keys for navigation within the group
Follows WAI-ARIA best practices
Supports RTL languages
Respects disabled/non-focusable items

Notes

Only one item in the group has tabIndex={0} at a time. All other items have tabIndex={-1}. This ensures a single tab stop while allowing full keyboard navigation with arrow keys.

The component automatically handles focus management, including updating tab indices, focusing items, and managing keyboard navigation based on orientation and direction.

Items marked with focusable={false} are skipped during keyboard navigation but remain in the DOM.

⌘I

Hooks

Primitives

Installation

Components

RovingFocusGroup

RovingFocusGroupItem

Props

RovingFocusGroup

Usage

Basic Example - Horizontal Navigation

Vertical List with Looping

Controlled Focus State

Grid Navigation (2D)

With Disabled Items

RTL Support

Keyboard Interactions

Accessibility

Notes

​Installation

​Components

​RovingFocusGroup

​RovingFocusGroupItem

​Props

​RovingFocusGroup

​Usage

​Basic Example - Horizontal Navigation

​Vertical List with Looping

​Controlled Focus State

​Grid Navigation (2D)

​With Disabled Items

​RTL Support

​Keyboard Interactions

​Accessibility

​Notes

Installation

Components

RovingFocusGroup

RovingFocusGroupItem

Props

RovingFocusGroup

Usage

Basic Example - Horizontal Navigation

Vertical List with Looping

Controlled Focus State

Grid Navigation (2D)

With Disabled Items

RTL Support

Keyboard Interactions

Accessibility

Notes