Keyboard Navigation
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:
- The entire composite widget is a single tab stop in the overall document sequence.
- Pressing Tab moves into or out of the widget.
- Arrow keys navigate between items inside the widget.
- 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-visibleoutlines 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:
| Key | Context | Behavior |
|---|---|---|
ArrowDown | Vertical list | Moves focus to the next enabled item. |
ArrowUp | Vertical list | Moves focus to the previous enabled item. |
ArrowRight | Horizontal list | Moves focus to the next enabled item (or previous in RTL). |
ArrowLeft | Horizontal list | Moves focus to the previous enabled item (or next in RTL). |
Home | Any orientation | Moves focus directly to the first enabled item. |
End | Any orientation | Moves focus directly to the last enabled item. |
PageDown | Any orientation | Jumps downward by pageSize (default 10). |
PageUp | Any orientation | Jumps 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 pressingArrowDownopens the menu and focuses the first item, whileArrowUpopens the menu and focuses the last item. - Combobox inputs:
useAriaActivedescendantenables disclosure by default. PressingArrowDownopens suggestions and selects the first option, whileAlt+ArrowDownopens 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(orArrowLeftin RTL) firesonEnter. Use this to set the child node'sopen.value = trueand focus its first item. - Returning to the parent menu: When inside a child submenu, pressing
ArrowLeft(orArrowRightin RTL) firesonExit. Use this to set the child node'sopen.value = falseand restore focus to the parent trigger.
For a complete walkthrough of nested submenus and tree coordination, read Hierarchy.
Official specifications
- WAI-ARIA APG: Keyboard Navigation Conventions: Fundamental standards for composite widgets and single tab stops.
- WAI-ARIA APG: Menu Pattern: Authoring practices for menu buttons, action menus, and submenus.
- WAI-ARIA APG: Combobox Pattern: Authoring practices for autocomplete and suggestion pickers with virtual focus.
Where to go next
- Hover & Dismissal: Learn how to meet WCAG 2.1 SC 1.4.13 for hover corridors and Escape key handling.
- Hierarchy: Connect parent-child floating nodes and manage multi-level tree hierarchies.
useRovingFocusAPI: Complete options and methods.useAriaActivedescendantAPI: Complete options and methods.