Roving Focus

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

Tab to focus

<script setup lang="ts">
import { RovingFocusGroup, RovingFocusItem } from 'akar';
</script>

<template>
  <div class="akar-demo akar-demo-RovingFocus">
    <div class="flex flex-col gap-4 justify-center">
      <p class="text-xs dark:color-stone-200">
        Tab to focus
      </p>
      <RovingFocusGroup
        orientation="horizontal"
        class="flex gap-2 items-center"
      >
        <RovingFocusItem
          class="font-medium px-4 py-2 rounded-lg bg-neutral-700 transition dark:color-white focus:bg-neutral-800 hover:bg-neutral-800"
          as="button"
        >
          Button 1
        </RovingFocusItem>
        <RovingFocusItem
          class="font-medium px-4 py-2 rounded-lg bg-neutral-700 transition dark:color-white focus:bg-neutral-800 hover:bg-neutral-800"
          as="button"
        >
          Button 2
        </RovingFocusItem>
        <RovingFocusItem
          class="font-medium px-4 py-2 rounded-lg bg-neutral-700 transition dark:color-white focus:bg-neutral-800 hover:bg-neutral-800"
          as="button"
        >
          Button 3
        </RovingFocusItem>
      </RovingFocusGroup>
    </div>
  </div>
</template>

Learn more about roving tabindex in Keyboard Navigation Inside Composite Components

Anatomy

Import all parts and piece them together.

<script setup>
import { RovingFocusGroup, RovingFocusItem } from 'akar';
</script>

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

API Reference

Group

Contains all the parts of a Roving Focus

Prop	Default	Type
`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.

Event	Payload
`entryFocus`	`event: Event`
`update:currentTabStopId`	`value: string \| null`

Method	Type
`getItems`	`(includeDisabledItem?: boolean) => { ref: HTMLElement; value?: any; }[]`

RovingFocusGroup.vue source

Data attribute	Value
`[data-orientation]`	`"vertical" \| "horizontal" \| "null"`

Item

The item that would inherit the roving tabindex

Prop	Default	Type
`active`		`boolean` When `true`, item will 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 will not be focusable.
`tabStopId`		`string`

RovingFocusItem.vue source

Data attribute	Value
`[data-active]`	Present when not active
`[data-disabled]`	Present when not focusable
`[data-orientation]`	`"vertical" \| "horizontal" \| "null"`

Examples

Vertical orientation

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

Loop

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

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

Initial focus item

Set active prop to item to initially focused item.

<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.

<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

Key	Description
`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.
`Space`/`Enter`	Triggers click on the roving focus item.

Primitive

Compose Akar's functionality onto alternative element types or your own Vue components.

Slot

Merges its props onto its immediate child.