Reka UI logoReka
backdrop
Examples
Utilities

Roving Focus

Utility component that implements the roving tabindex method to manage focus between items.

Tab to focus

info

Learn more about roving tabindex in Keyboard Navigation Inside Composite Components

Anatomy

Import all parts and piece them together.

vue
<script setup>
import { RovingFocusGroup, RovingFocusItem } from 'reka-ui'
</script>

<template>
  <RovingFocusGroup>
    <RovingFocusItem />
  </RovingFocusGroup>
</template>

API Reference

Group

Contains all the parts of a Roving Focus

PropDefaultType
as
'div'
AsTag | Component

The element or component this component should render as. Can be overwritten by asChild.

asChild
boolean

Change the default rendered element for the one passed as a child, merging their props and behavior.

Read our Composition guide for more details.

currentTabStopId
string | null

The controlled value of the current stop item. Can be binded as v-model.

defaultCurrentTabStopId
string

The value of the current stop item.

Use when you do not need to control the state of the stop item.

dir
'ltr' | 'rtl'

The direction of navigation between items.

loop
false
boolean

Whether keyboard navigation should loop around

orientation
'vertical' | 'horizontal'

The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down)

preventScrollOnEntryFocus
false
boolean

When true, will prevent scrolling to the focus item when focused.

EmitPayload
entryFocus
[event: Event]

Event handler called when container is being focused. Can be prevented.

update:currentTabStopId
[value: string | null]
MethodsType
getItems
(includeDisabledItem?: boolean) => { ref: HTMLElement; value?: any; }[]
Data AttributeValue
[data-orientation]"vertical" | "horizontal" | "undefined"

Item

The item that would inherit the roving tabindex

PropDefaultType
active
boolean

When true, item wil be initially focused.

allowShiftKey
boolean

When true, shift + arrow key will allow focusing on next/previous item.

as
'span'
AsTag | Component

The element or component this component should render as. Can be overwritten by asChild.

asChild
boolean

Change the default rendered element for the one passed as a child, merging their props and behavior.

Read our Composition guide for more details.

focusable
true
boolean

When false, item wil be not be focusable.

tabStopId
string
Data AttributeValue
[data-active]Present when not active
[data-disabled]Present when not focusable
[data-orientation]"vertical" | "horizontal" | "undefined"

Examples

Vertical orientation

vue
<template>
  <RovingFocusGroup :orientation="'vertical'">
    …
  </RovingFocusGroup>
</template>

Loop

Use loop property to enable roving from last item to the first item, and vice versa.

vue
<template>
  <RovingFocusGroup loop>
    …
  </RovingFocusGroup>
</template>

Initial focus item

Set active prop to item to initially focused item.

vue
<template>
  <RovingFocusGroup>
    <RovingFocusItem>1</RovingFocusItem>
    <RovingFocusItem active>2</RovingFocusItem>
    <RovingFocusItem>3</RovingFocusItem>
  </RovingFocusGroup>
</template>

Unfocusable item

Set focusable="false" prop to item will prevent them from being focused.

vue
<template>
  <RovingFocusGroup>
    <RovingFocusItem>1</RovingFocusItem>
    <RovingFocusItem :focusable="false">2</RovingFocusItem>
    <RovingFocusItem>3</RovingFocusItem>
  </RovingFocusGroup>
</template>

Accessibility

Adheres to the Keyboard Navigation Inside Composite Components.

Keyboard Interactions

KeyDescription
ArrowDown
Moves focus to the next roving focus item in the group.
ArrowRight
Moves focus to the next roving focus item in the group.
ArrowUp
Moves focus to the previous roving focus item in the group.
ArrowLeft
Moves focus to the previous roving focus item in the group.
SpaceEnter
Triggers click on the roving focus item.