Roving Focus

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

Tab to focus

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

<template>
  <div class="flex flex-col gap-4 justify-center">
    <p class="text-xs color-text-muted">
      Tab to focus
    </p>
    <ARovingFocusGroup
      orientation="horizontal"
      class="flex gap-2 items-center"
    >
      <ARovingFocusItem
        class="font-medium px-4 py-2 rounded-lg bg-background-muted transition-colors-280 focus:bg-background-accented hover:bg-background-accented"
        as="button"
      >
        Button 1
      </ARovingFocusItem>
      <ARovingFocusItem
        class="font-medium px-4 py-2 rounded-lg bg-background-muted transition-colors-280 focus:bg-background-accented hover:bg-background-accented"
        as="button"
      >
        Button 2
      </ARovingFocusItem>
      <ARovingFocusItem
        class="font-medium px-4 py-2 rounded-lg bg-background-muted transition-colors-280 focus:bg-background-accented hover:bg-background-accented"
        as="button"
      >
        Button 3
      </ARovingFocusItem>
    </ARovingFocusGroup>
  </div>
</template>

Learn more about roving tabindex in Keyboard Navigation Inside Composite Components

Anatomy

Import all parts and piece them together.

<script setup>
import { ARovingFocusGroup, ARovingFocusItem } from 'akar';
</script>

<template>
  <ARovingFocusGroup>
    <ARovingFocusItem />
  </ARovingFocusGroup>
</template>

API Reference

Group

Contains all the parts of a Roving Focus

Props

Prop	Default	Type
`as`	`'div'`	`APrimitiveAsTag \| 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`
`defaultCurrentTabStopId`		`string`
`dir`		`'ltr' \| 'rtl'` The direction of navigation between items.
`loop`	`false`	`boolean` Whether keyboard navigation should loop around
`orientation`		`'horizontal' \| 'vertical'` The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down)
`preventScrollOnEntryFocus`	`false`	`boolean`

Emits

Event	Type
`entryFocus`	`[event: Event]` Event handler called when container is being focused. Can be prevented.
`update:currentTabStopId`	`[value: string \| null]`

Data Attributes

Attribute	Value
`[data-orientation]`	`'vertical' \| 'horizontal' \| 'undefined'`

Item

The item that would inherit the roving tabindex

Props

Prop	Default	Type
`as`	`'span'`	`APrimitiveAsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`active`		`boolean` When `true`, item will be initially focused.
`allowShiftKey`		`boolean` When `true`, shift + arrow key will allow focusing on next/previous item.
`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 be not be focusable.
`tabStopId`		`string`

Data Attributes

Attribute	Value
`[data-active]`	Present when not active
`[data-disabled]`	Present when not focusable
`[data-orientation]`	`'vertical' \| 'horizontal' \| 'undefined'`

Examples

Vertical orientation

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

Loop

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

<template>
  <ARovingFocusGroup loop>
    …
  </ARovingFocusGroup>
</template>

Initial focus item

Set active prop to item to initially focused item.

<template>
  <ARovingFocusGroup>
    <ARovingFocusItem>1</ARovingFocusItem>
    <ARovingFocusItem active>2</ARovingFocusItem>
    <ARovingFocusItem>3</ARovingFocusItem>
  </ARovingFocusGroup>
</template>

Unfocusable item

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

<template>
  <ARovingFocusGroup>
    <ARovingFocusItem>1</ARovingFocusItem>
    <ARovingFocusItem :focusable="false">2</ARovingFocusItem>
    <ARovingFocusItem>3</ARovingFocusItem>
  </ARovingFocusGroup>
</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.
`SpaceEnter`	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.