FocusTrap
An unstyled component that traps keyboard focus within its container.
Build accessible modal regions that keep keyboard focus confined within a defined boundary.
Register
basic-demo
Pre-styled Versions
Choose a pre-styled library to use FocusTrap with ready-made designs.
For hook-based usage without components, see the Headless API.
Features#
- Focus cycling: Tab wraps from last to first focusable element, Shift+Tab wraps from first to last
- Auto-focus on mount with support for
initialFocusRef,[autofocus], and[data-autofocus] - Escape key handling via
onEscapecallback - MutationObserver detects DOM changes and refocuses appropriately
- Uses VisuallyHidden sentinel elements for invisible focus boundaries
Usage#
import { FocusTrap } from 'primereact/focustrap';<FocusTrap>
<input type="text" />
<button type="submit"></button>
</FocusTrap>Behavior#
Polymorphic Rendering#
Use as to change the rendered container element. Defaults to div.
<FocusTrap as="section">...</FocusTrap>Render Function Children#
<FocusTrap>{(instance) => <div>Trapped: {String(instance.props.trapped)}</div>}</FocusTrap>Pass Through#
Some parts may not be visible in the preview depending on the component's current state.
Loading...
/* Select a part to see its CSS selector for custom styling */API#
FocusTrap#
| Name | Type | Default |
|---|---|---|
ref | Ref<unknown> | — |
| The reference to the component instance. | ||
pIf | boolean | true |
| Whether the component should be rendered. | ||
style | CSSProperties | ((instance?: FocusTrapInstance) => CSSProperties) | — |
| The style to apply to the component. | ||
className | string | ((instance?: FocusTrapInstance) => string) | — |
| The class name to apply to the component. | ||
as | string | number | bigint | boolean | ComponentClass<any, any> | FunctionComponent<any> | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode, any, any> | ReactPortal | Promise<AwaitedReactNode> | — |
| The component type to render. | ||
asChild | boolean | false |
| Whether the component should be rendered as a child component. | ||
instance | FocusTrapInstance | — |
| The instance to pass to the component. | ||
pt | SafeRecord<FocusTrapPassThrough> | — |
| The pass-through props to pass to the component. | ||
ptOptions | PassThroughOptions | — |
| The pass-through options to pass to the component. | ||
unstyled | boolean | — |
| Whether the component should be rendered without classes. | ||
dt | unknown | — |
| The design token to use for the component. | ||
styles | StylesOptions<ComponentInstance> | — |
| The styles to use for the component. | ||
render | (instance: FocusTrapInstance) => ReactNode | — |
| The render function to render the component with instance access. | ||
children | any | — |
| The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates. | ||
trapped | boolean | true |
| When enabled, focus is trapped within the container element. | ||
autoFocus | boolean | true |
| When enabled, the first focusable element receives focus on mount. | ||
initialFocusRef | RefObject<HTMLElement> | — |
| Reference to the element that should receive focus when the trap activates. Takes priority over autoFocus and [autofocus] attribute detection. | ||
onEscape | (event: KeyboardEvent) => void | — |
| Callback invoked when the Escape key is pressed inside the trap. | ||
onTabFirst | (event: FocusEvent<HTMLElement>) => void | — |
| Callback invoked when Shift+Tab is pressed before the first focusable element. When provided, overrides the default cycling behavior. | ||
onTabLast | (event: FocusEvent<HTMLElement>) => void | — |
| Callback invoked when Tab is pressed past the last focusable element. When provided, overrides the default cycling behavior. | ||
[key: string] | any | — |
pt-{optionName}-* | - | — |
| Pass through attributes for customizing component. For more info, see Pass Through tab. | ||
| Attribute | Value |
|---|---|
data-focus-trap | Present on the container when active |
Defines passthrough(pt) options of FocusTrap component.
| label | type | description |
|---|---|---|
| root | FocusTrapPassThroughType<HTMLAttributes<HTMLDivElement>> | Used to pass attributes to the root's DOM element. |
| hiddenElement | FocusTrapPassThroughType<HTMLAttributes<HTMLSpanElement>> | Used to pass attributes to the hiddenElement's DOM element. |
| pcVisibleHidden | FocusTrapPassThroughType<HTMLAttributes<HTMLSpanElement>> | Used to pass attributes to the pcVisibleHidden's DOM element. |
Accessibility#
Screen Reader#
FocusTrap uses VisuallyHidden sentinel elements before and after the content to cycle focus. These sentinels have role="presentation" and aria-hidden="true" so they are ignored by screen readers.
Keyboard Support#
| Key | Function |
|---|---|
tab | Moves focus to the next focusable element inside the trap. Wraps to the first when at the end. |
shift + tab | Moves focus to the previous focusable element inside the trap. Wraps to the last when at the start. |
escape | Calls the onEscape callback when defined. |