Shows an ephemeral "← → to navigate" hint anchored to the focused item the first time a roving-tabindex composite (Toolbar, TabList, SegmentedControl, etc.) receives keyboard focus. It teaches sighted keyboard users that arrow keys move within the group. The hint renders in the top layer (popover="manual") and is CSS-anchor-positioned to the focused element, so overflow containers never clip it. It auto-dismisses on the first arrow press, on timeout, or on blur, and does not re-show for that instance. Toolbar, TabList, and SegmentedControl wire this in automatically — reach for the hook directly only when building a custom roving-tabindex widget.
ts
| Guidance | Practices |
|---|---|
| Do | Compose the returned onFocus/onKeyDown with your existing focus handlers rather than replacing them — call onKeyDown first (it only dismisses, never prevents), then your navigation handler. |
| Do | Render hintElement as the last child of the composite container; it is position:fixed in the top layer and aria-hidden, so it never affects layout or the accessibility tree. |
| Do | Match orientation to the arrow keys your widget actually responds to so the hint shows the correct icons. |
| Don't | Use for single controls or widgets without roving-tabindex navigation — the hint only makes sense where arrows move focus within a group. |
| Param | Type | Description |
|---|---|---|
options | UseKeyboardHintOptions | Configuration object for the keyboard hint. |
options.orientation | 'horizontal' | 'vertical' | 'both' (default: 'horizontal') | Which arrow-key axis the composite navigates, controlling which arrow icons the hint shows (← → for horizontal, ↑ ↓ for vertical, all four for both). |
options.dismissAfterMs | number (default: 3000) | Milliseconds before the hint auto-dismisses after appearing. |
options.isEnabled | boolean (default: true) | Whether the hint is enabled. Set to false to suppress it for a specific instance (e.g. a disabled or read-only widget). |
| Field | Type | Description |
|---|---|---|
| hintElement | ReactNode | The popover hint element to render inside the composite container (as the last child). Portals to the top layer via popover="manual" and manages its own visibility — render it unconditionally. |
| onFocus | (e: React.FocusEvent) => void | Attach to the container onFocus. Shows the hint on the first keyboard-focus (:focus-visible) entry from outside the composite. |
| onBlur | (e: React.FocusEvent) => void | Attach to the container onBlur. Hides the hint when focus leaves the composite entirely, and re-anchors when focus moves within. |
| onKeyDown | (e: React.KeyboardEvent) => void | Attach to the container onKeyDown. Dismisses the hint on the first arrow press (the user has discovered the interaction). Never prevents default or stops propagation. |
Toolbar shows an ephemeral "← → to navigate" hint on first keyboard focus via useKeyboardHint, teaching sighted keyboard users that arrows move within the group.