Hooks
useRovingTablist
A React hook that implements the ARIA Authoring Practices tabs keyboard model over the DOM nodes of a tablist container. Arrow keys move focus between enabled tabs (wrapping, RTL-aware), Home/End jump to the first/last, and the tablist keeps exactly one Tab stop — on the focused tab, otherwise the selected tab, otherwise the first enabled one. Works with tabs that are cloned children of arbitrary depth, which the container cannot address individually.
Installation
bunx @happlyui/cli@latest add use-roving-tablist
Usage
import { useRovingTablist } from "@/hooks/use-roving-tablist"
const containerRef = React.useRef<HTMLDivElement>(null)
const { onKeyDown, syncTabStop } = useRovingTablist(containerRef)
<div ref={containerRef} role="tablist" onKeyDown={onKeyDown}>
{tabs}
</div>
API Reference
useRovingTablist Parameters
Arguments passed to the hook.
| Prop | Type | Default | Description |
|---|---|---|---|
containerRef | React.RefObject<T | null> | - | Ref to the element carrying role="tablist". Its `[role="tab"]` descendants are the tabs; tabs with `disabled` or `aria-disabled="true"` are skipped. |
useRovingTablist Return Value
The object returned by the hook.
| Prop | Type | Default | Description |
|---|---|---|---|
onKeyDown | (event: React.KeyboardEvent<HTMLElement>) => void | - | Keydown handler for the container. Handles ArrowLeft/ArrowRight (direction-aware), Home and End; ignores every other key so activation stays with the native button. |
syncTabStop | () => void | - | Re-applies the single Tab stop. Called automatically after every render; call it from a ResizeObserver or MutationObserver that already watches the tab nodes. |