GitHub

RovingFocusGroup

Manage keyboard navigation within a group of focusable elements.

A utility component for managing keyboard focus within a group of elements using the roving tabindex pattern. Enables arrow key navigation between focusable items while maintaining a single tab stop for the group.

Note that this is primarily a web component. On native it renders children without keyboard navigation management.

Features

  • Arrow key navigation between items (respects orientation).

  • Single tab stop for the entire group.

  • Optional looping from last to first item.

  • RTL direction support.

  • Tracks active/current item state.

Installation

RovingFocusGroup is already installed in tamagui, or you can install it independently:

yarn add @tamagui/roving-focus

Usage

Wrap focusable items with RovingFocusGroup and use RovingFocusGroup.Item for each focusable element:

import { Button, RovingFocusGroup, XStack } from 'tamagui'



export default () => (

  <RovingFocusGroup orientation="horizontal" loop>

    <XStack gap="$2">

      <RovingFocusGroup.Item asChild>

        <Button>First</Button>

      </RovingFocusGroup.Item>

      <RovingFocusGroup.Item asChild>

        <Button>Second</Button>

      </RovingFocusGroup.Item>

      <RovingFocusGroup.Item asChild>

        <Button>Third</Button>

      </RovingFocusGroup.Item>

    </XStack>

  </RovingFocusGroup>

)

How It Works

The roving tabindex pattern allows a group of focusable elements to act as a single tab stop. When the user tabs into the group, focus moves to the currently active item. Arrow keys then navigate between items within the group.

This improves keyboard navigation by:

  • Reducing the number of tab stops on a page
  • Providing intuitive arrow key navigation within related controls
  • Maintaining focus state across the group

Orientation

Set orientation to control which arrow keys navigate:

import { Button, RovingFocusGroup, YStack } from 'tamagui'



export default () => (

  // Up/Down arrows navigate, Left/Right are ignored

  <RovingFocusGroup orientation="vertical">

    <YStack gap="$2">

      <RovingFocusGroup.Item asChild>

        <Button>Option 1</Button>

      </RovingFocusGroup.Item>

      <RovingFocusGroup.Item asChild>

        <Button>Option 2</Button>

      </RovingFocusGroup.Item>

      <RovingFocusGroup.Item asChild>

        <Button>Option 3</Button>

      </RovingFocusGroup.Item>

    </YStack>

  </RovingFocusGroup>

)

Looping Navigation

Enable loop to wrap focus from the last item back to the first:

import { Button, RovingFocusGroup, XStack } from 'tamagui'



export default () => (

  <RovingFocusGroup loop>

    <XStack gap="$2">

      <RovingFocusGroup.Item asChild>

        <Button>First</Button>

      </RovingFocusGroup.Item>

      <RovingFocusGroup.Item asChild>

        <Button>Middle</Button>

      </RovingFocusGroup.Item>

      <RovingFocusGroup.Item asChild>

        <Button>Last</Button>

      </RovingFocusGroup.Item>

      {/* Arrow right from "Last" goes to "First" */}

    </XStack>

  </RovingFocusGroup>

)

Controlled Tab Stop

Control which item is the current tab stop:

import { Button, RovingFocusGroup, XStack } from 'tamagui'

import { useState } from 'react'



export default () => {

  const [currentId, setCurrentId] = useState<string | null>('item-2')



  return (

    <RovingFocusGroup
      currentTabStopId={currentId}
      onCurrentTabStopIdChange={setCurrentId}
    >

      <XStack gap="$2">

        <RovingFocusGroup.Item tabStopId="item-1" asChild>

          <Button>First</Button>

        </RovingFocusGroup.Item>

        <RovingFocusGroup.Item tabStopId="item-2" asChild>

          <Button>Second (default)</Button>

        </RovingFocusGroup.Item>

        <RovingFocusGroup.Item tabStopId="item-3" asChild>

          <Button>Third</Button>

        </RovingFocusGroup.Item>

      </XStack>

    </RovingFocusGroup>

  )

}

Non-Focusable Items

Mark items as non-focusable to skip them during keyboard navigation:

import { Button, RovingFocusGroup, XStack } from 'tamagui'



export default () => (

  <RovingFocusGroup>

    <XStack gap="$2">

      <RovingFocusGroup.Item asChild>

        <Button>Enabled</Button>

      </RovingFocusGroup.Item>

      <RovingFocusGroup.Item focusable={false} asChild>

        <Button disabled>Disabled</Button>

      </RovingFocusGroup.Item>

      <RovingFocusGroup.Item asChild>

        <Button>Enabled</Button>

      </RovingFocusGroup.Item>

    </XStack>

  </RovingFocusGroup>

)

Entry Focus Control

Handle focus when the group first receives focus:

import { Button, RovingFocusGroup, XStack } from 'tamagui'



export default () => (

  <RovingFocusGroup
    onEntryFocus={(event) => {
      // Prevent default focus behavior
      // event.preventDefault()
      console.log('Group received focus')
    }}
  >

    <XStack gap="$2">

      <RovingFocusGroup.Item asChild>

        <Button>First</Button>

      </RovingFocusGroup.Item>

      <RovingFocusGroup.Item asChild>

        <Button>Second</Button>

      </RovingFocusGroup.Item>

    </XStack>

  </RovingFocusGroup>

)

API Reference

RovingFocusGroup

Props

  • orientation

    "horizontal" | "vertical"

    The orientation of the group. Determines which arrow keys are used for navigation (left/right vs up/down).

  • dir

    "ltr" | "rtl"

    The reading direction. When set to rtl, left and right arrow keys are reversed.

  • loop

    boolean

    Default: 

    false

    When true, keyboard navigation will loop from last to first and vice versa.

  • currentTabStopId

    string | null

    The controlled id of the current tab stop.

  • defaultCurrentTabStopId

    string

    The default id of the current tab stop for uncontrolled usage.

  • onCurrentTabStopIdChange

    (tabStopId: string | null) => void

    Callback when the current tab stop changes.

  • onEntryFocus

    (event: Event) => void

    Callback when focus enters the group via keyboard. Call event.preventDefault() to prevent default focus behavior.

  • asChild

    boolean

    Default: 

    false

    When true, renders as a Slot, merging props onto the child element.

    • RovingFocusGroup.Item

    Props

  • tabStopId

    string

    A unique identifier for this item. Auto-generated if not provided.

  • focusable

    boolean

    Default: 

    true

    Whether this item should be focusable. Set to false to skip during keyboard navigation.

  • active

    boolean

    Default: 

    false

    Whether this item is considered active. Active items receive focus priority when the group is entered.

  • asChild

    boolean

    Default: 

    false

    When true, renders as a Slot, merging props onto the child element.

    • Keyboard Navigation

    KeyAction
    TabMove focus into/out of the group
    Arrow Left/RightMove focus between items (horizontal orientation)
    Arrow Up/DownMove focus between items (vertical orientation)
    Home / Page UpMove focus to first item
    End / Page DownMove focus to last item

    Usage in Components

    RovingFocusGroup is used internally by several Tamagui components to provide keyboard navigation:

    RovingFocusGroup is primarily designed for web platforms. On React Native, it renders children without keyboard navigation management since native platforms handle focus differently.

    Previous

    Portal

    Next

    ScrollView

    Edit this page on GitHub.