useFocusTrap@xds/core · hooks
Preview coming soon
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.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. |
Import
ts