Accessibility

Keyboard Navigation

Implement accessible keyboard interaction patterns for menus, comboboxes, and composite lists following WAI-ARIA APG standards.

Keyboard accessibility is more than allowing the Tab key to reach a button.

In accessible web applications, composite widgets (such as menus, listboxes, comboboxes, and toolbars) must follow standard WAI-ARIA Authoring Practices Guide (APG) keyboard patterns.

This guide explains the single tab stop principle, how to choose between physical roving focus and virtual focus, and how to implement typeahead search and tree navigation.

The single tab stop principle

In standard HTML document flow, every interactive element is a separate tab stop. If a menu contains 25 actions, pressing Tab 25 times to move through the menu creates severe keyboard fatigue and disrupts page navigation.

The WAI-ARIA APG keyboard interface conventions establish a clear contract:

  1. The entire composite widget is a single tab stop in the overall document sequence.
  2. Pressing Tab moves into or out of the widget.
  3. Arrow keys navigate between items inside the widget.
  4. Pressing Enter or Space activates the currently focused item.

To implement this contract, VFloat separates keyboard navigation into two distinct models based on whether the component requires continuous text input:

  • Physical Roving Focus (useRovingFocus): For standalone composite widgets without text inputs (menus, tabs, toolbars). Focus lands directly on each item element.
  • Virtual Focus (useAriaActivedescendant): For text input widgets (comboboxes, search autocompletes, mention pickers). Focus remains locked inside the <input>, while active suggestions are signaled to screen readers virtually.

Physical roving focus for menus and toolbars

In this pattern, physical DOM focus moves to each list item following the WAI-ARIA APG Roving Tabindex Pattern.

Only the active item has tabindex="0", making it reachable if the user tabs away and returns. All other items have tabindex="-1", preventing them from cluttering the document tab sequence. When the user presses an arrow key, useRovingFocus moves tabindex="0" to the new item and immediately calls .focus().

Here is an accessible vertical menu using roving focus:

<script setup lang="ts">
import { ref, shallowRef } from "vue";
import {
  useClick,
  useEscapeKey,
  useFloatingNode,
  useOutsideClick,
  usePosition,
  useRole,
  useRovingFocus,
} from "v-float";

interface MenuItem {
  id: string;
  label: string;
  disabled?: boolean;
}

const items = ref<MenuItem[]>([
  { id: "edit", label: "Edit Item" },
  { id: "duplicate", label: "Duplicate" },
  { id: "archive", label: "Archive Item", disabled: true },
  { id: "delete", label: "Delete" },
]);

const anchorEl = ref<HTMLElement | null>(null);
const floatingEl = ref<HTMLElement | null>(null);
const itemEls = shallowRef<(HTMLElement | null)[]>([]);

const node = useFloatingNode({ anchorEl, floatingEl });
usePosition(node, { placement: "bottom-start" });

useClick(node);
useOutsideClick(node);
useEscapeKey(node);

// 1. Move physical DOM focus across items using arrow keys
const { activeIndex, getTabindex } = useRovingFocus(node, {
  elementsList: itemEls,
  orientation: "vertical",
  loop: true,
});

// 2. Synchronize menu and menuitem ARIA roles
useRole(node, {
  role: "menu",
  listRef: itemEls,
  disabledIndices: (index) => !!items.value[index]?.disabled,
});
</script>

<template>
  <button ref="anchorEl" type="button">Options</button>

  <ul v-if="node.open.value" ref="floatingEl">
    <li
      v-for="(item, index) in items"
      :key="item.id"
      :ref="(el) => (itemEls[index] = el as HTMLElement | null)"
      :tabindex="getTabindex(index)"
      :class="{ active: activeIndex === index }"
    >
      {{ item.label }}
    </li>
  </ul>
</template>

Why roving focus is chosen for menus

Roving focus provides three key accessibility benefits for standalone widgets (WAI-ARIA APG Menu Pattern):

  • Native focus styles: Browsers apply standard :focus-visible outlines directly to the active item without custom CSS hacks.
  • Automatic scroll alignment: Browsers scroll the container automatically whenever an off-screen item receives focus.
  • Screen reader announcements: Screen readers announce each item naturally as the active DOM focus target.

Virtual focus for comboboxes and text inputs

When a component includes a search input, moving physical DOM focus out of the input field breaks user input:

  • The blinking text cursor disappears.
  • Typing is interrupted.
  • International Input Method Editors (IME for Chinese, Japanese, or Korean) are terminated.
  • Mobile software keyboards close unexpectedly.

To avoid this, follow the WAI-ARIA APG Combobox Pattern and use useAriaActivedescendant.

In this model, DOM focus stays pinned inside the <input> element. When the user presses Arrow keys, the composable tracks the active item index and sets aria-activedescendant on the input, pointing to the unique ID of the currently highlighted option. Screen readers announce the active suggestion while the user continues typing.

Here is an accessible combobox using virtual focus:

<script setup lang="ts">
import { computed, ref, shallowRef } from "vue";
import {
  useAriaActivedescendant,
  useEscapeKey,
  useFloatingNode,
  useOutsideClick,
  usePosition,
  useRole,
} from "v-float";

interface SearchOption {
  value: string;
  label: string;
}

const options = ref<SearchOption[]>([
  { value: "vue", label: "Vue.js" },
  { value: "react", label: "React" },
  { value: "svelte", label: "Svelte" },
]);

const query = ref("");
const inputEl = ref<HTMLInputElement | null>(null);
const floatingEl = ref<HTMLElement | null>(null);
const itemEls = shallowRef<(HTMLElement | null)[]>([]);

const node = useFloatingNode({ anchorEl: inputEl, floatingEl });

usePosition(node, {
  placement: "bottom-start",
  middlewares: { offset: 4, matchWidth: true },
});

useOutsideClick(node);
useEscapeKey(node);

const filteredOptions = computed(() =>
  options.value.filter((o) => o.label.toLowerCase().includes(query.value.toLowerCase())),
);

// Pinned DOM focus on input with virtual ARIA focus on options
const { activeIndex, getItemId } = useAriaActivedescendant(node, {
  elementsList: itemEls,
  onSelect: (index) => {
    query.value = filteredOptions.value[index]!.label;
    node.open.value = false;
  },
});

useRole(node, { role: "listbox", listRef: itemEls });
</script>

<template>
  <input
    ref="inputEl"
    v-model="query"
    type="text"
    role="combobox"
    aria-autocomplete="list"
    @focus="node.open.value = true"
  />

  <ul v-if="node.open.value" ref="floatingEl">
    <li
      v-for="(item, index) in filteredOptions"
      :key="item.value"
      :id="getItemId(index)"
      :ref="(el) => (itemEls[index] = el as HTMLElement | null)"
      :class="{ active: activeIndex === index }"
    >
      {{ item.label }}
    </li>
  </ul>
</template>

In the template, binding :id="getItemId(index)" gives each option element a stable ID. useAriaActivedescendant synchronizes aria-activedescendant="[id]" on the <input> automatically.

Typeahead search within lists

When navigating long lists, pressing the down arrow repeatedly is slow.

useTypeahead captures rapid keystroke sequences and jumps focus directly to the matching item according to WAI-ARIA APG Typeahead specifications (for example, typing "c" jumps to "California").

Here is how to combine typeahead search with roving focus:

<script setup lang="ts">
import { ref, shallowRef } from "vue";
import { useFloatingNode, usePosition, useRovingFocus, useTypeahead } from "v-float";

const items = ref(["Apple", "Banana", "Cherry", "Date", "Elderberry"]);
const anchorEl = ref<HTMLElement | null>(null);
const floatingEl = ref<HTMLElement | null>(null);
const itemEls = shallowRef<(HTMLElement | null)[]>([]);

const node = useFloatingNode({ anchorEl, floatingEl });
usePosition(node, { placement: "bottom-start" });

const { activeIndex, getTabindex } = useRovingFocus(node, {
  elementsList: itemEls,
  orientation: "vertical",
});

// Buffer typing sequences and update active index
useTypeahead(node, {
  elementsList: itemEls,
  activeIndex,
  onMatch: (index) => {
    activeIndex.value = index;
    itemEls.value[index]?.focus();
  },
});
</script>

useTypeahead buffers consecutive keypresses within a configurable reset window (defaulting to 750ms). If a user types the same letter repeatedly, it cycles through matching items starting with that letter.

Keyboard navigation contract

VFloat's keyboard composables handle standard navigation keys automatically:

KeyContextBehavior
ArrowDownVertical listMoves focus to the next enabled item.
ArrowUpVertical listMoves focus to the previous enabled item.
ArrowRightHorizontal listMoves focus to the next enabled item (or previous in RTL).
ArrowLeftHorizontal listMoves focus to the previous enabled item (or next in RTL).
HomeAny orientationMoves focus directly to the first enabled item.
EndAny orientationMoves focus directly to the last enabled item.
PageDownAny orientationJumps downward by pageSize (default 10).
PageUpAny orientationJumps upward by pageSize (default 10).

Right-to-left (RTL) localization

When an interface renders inside a container with dir="rtl", horizontal arrow key directions must invert.

VFloat composables detect the surrounding text direction automatically. In RTL mode, pressing ArrowLeft navigates to the next item and ArrowRight navigates to the previous item, preserving natural reading order.

Opening closed surfaces on arrow keys

When a menu button or combobox input is focused and the surface is closed, users expect standard arrow keys to disclose the list:

  • Menu triggers: Configure useRovingFocus({ openOnArrowKeyDown: true }) so pressing ArrowDown opens the menu and focuses the first item, while ArrowUp opens the menu and focuses the last item.
  • Combobox inputs: useAriaActivedescendant enables disclosure by default. Pressing ArrowDown opens suggestions and selects the first option, while Alt+ArrowDown opens suggestions without selecting an option.

Hierarchical tree navigation for submenus

In nested menu trees, arrow keys govern moving between parent and child menus:

  • Entering a child submenu: When focused on a menuitem that acts as a submenu trigger, pressing ArrowRight (or ArrowLeft in RTL) fires onEnter. Use this to set the child node's open.value = true and focus its first item.
  • Returning to the parent menu: When inside a child submenu, pressing ArrowLeft (or ArrowRight in RTL) fires onExit. Use this to set the child node's open.value = false and restore focus to the parent trigger.

For a complete walkthrough of nested submenus and tree coordination, read Hierarchy.

Official specifications

Where to go next

Released under the MIT License. Copyright © 2026