Astryx Design System

useFocusTrap@astryxdesign/core v0.0.15 · useFocusTrap

Usage

Traps focus within a container element following the WAI-ARIA dialog focus trap pattern. Listens to focus events on the document and redirects focus back into the container if it escapes via keyboard navigation. Handles both Tab and Shift+Tab wrapping. Mouse clicks outside the container are not intercepted; use a light-dismiss handler for that.

ts
import {useFocusTrap} from '@astryxdesign/core/hooks'

Best practices

Guidance	Practices
Do	Call focusFirst() when opening a dialog/modal to move focus into the trapped region.
Do	Provide an onEscape callback to close the dialog when Escape is pressed.
Don't	Use on non-modal content like tooltips or dropdowns; those need light-dismiss, not focus trapping.

Parameters

Param	Type	Description
optionsrequired	UseFocusTrapOptions	Configuration object for the focus trap.
options.isActiverequired	boolean	Whether the focus trap is currently active.
options.onEscape	() => void	Callback when Escape key is pressed inside the trapped container.

Returns

Field	Type	Description
containerRef	React.RefObject<HTMLElement \| null>	Ref to attach to the container element that should trap focus.
focusFirst	() => void	Focuses the first focusable element inside the container.