HapplyUI

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.

PropTypeDefaultDescription
containerRefReact.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.

PropTypeDefaultDescription
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.

Previous
useFilterBar