Skip to content

Commit 34597e7

Browse files
committed
docs(use-roving-focus): add comparison table vs useVirtualFocus to guide pattern selection
1 parent 80b6034 commit 34597e7

1 file changed

Lines changed: 14 additions & 0 deletions

File tree

apps/docs/src/pages/composables/system/use-roving-focus.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,20 @@ Keyboard navigation for composite widgets where arrow keys move focus between it
6666
</template>
6767
```
6868

69+
## useRovingFocus vs useVirtualFocus
70+
71+
Both manage keyboard navigation, but they use different focus strategies:
72+
73+
| | `useRovingFocus` | `useVirtualFocus` |
74+
|-|------------------|-------------------|
75+
| **DOM focus** | Moves to each item | Stays on the control (e.g., `<input>`) |
76+
| **tabindex** | Managed per item | Not used |
77+
| **ARIA** | Items receive focus directly | `aria-activedescendant` on control |
78+
| **Use for** | Toolbars, menus, grids, tabs | Comboboxes, autocompletes, searchable selects |
79+
| **Keyboard pattern** | Items are real focusable elements | Items are virtual — only one DOM node has focus |
80+
81+
Choose `useRovingFocus` when items are real interactive elements (buttons, links). Choose `useVirtualFocus` when a single input drives a list of options that aren't individually focusable.
82+
6983
## Architecture
7084

7185
`useRovingFocus` builds on `useEventListener` for keydown handling. It is a standalone composable — not part of the registry/selection hierarchy — making it composable alongside `createSingle` or `createSelection` for widgets that separate focus from selection (e.g., listboxes, selects).

0 commit comments

Comments
 (0)