Focus Trap

Trap focus within a specified container.

Motivation

Focus trapping is essential for modal interfaces and other interactive elements that require user attention.

The FocusTrap component helps maintain accessibility by ensuring keyboard focus remains within a designated container until explicitly released.

Examples

Example not found

Example not found

Example not found

Example not found

Autofocus

The focus trap respects elements with the autofocus attribute.

Example not found

Example not found

Example not found

Example not found

Initial Focus

Use the initialFocus prop to set the element that should receive initial focus when the trap is activated.

Example not found

Example not found

Example not found

Example not found

API Reference

FocusTrap

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`disabled`		`boolean` Whether the focus trap is disabled.
`fallbackFocus`		`FocusTarget` By default, an error will be thrown if the focus trap contains no elements in its tab order. With this option you can specify a fallback element to programmatically receive focus if no other tabbable elements are found. For example, you may want a popover's `<div>` to receive focus if the popover's content includes no tabbable elements. *Make sure the fallback element has a negative `tabindex` so it can be programmatically focused. NOTE: If `initialFocus` is `false` (or a function that returns `false`), this function will not be called when the trap is activated, and no element will be initially focused. This function may still be called while the trap is active if things change such that there are no longer any tabbable nodes in the trap.
`initialFocus`		`VoidFunction \| FocusTargetOrFalse` By default, when a focus trap is activated the first element in the focus trap's tab order will receive focus. With this option you can specify a different element to receive that initial focus, or use `false` for no initially focused element at all. NOTE: Setting this option to `false` (or a function that returns `false`) will prevent the `fallbackFocus` option from being used. Setting this option to `undefined` (or a function that returns `undefined`) will result in the default behavior.
`onActivate`		`VoidFunction` A function that will be called before sending focus to the target element upon activation.
`onDeactivate`		`VoidFunction` A function that will be called before sending focus to the trigger element upon deactivation.
`returnFocusOnDeactivate`		`boolean` Default: `true`. If `false`, when the trap is deactivated, focus will not return to the element that had focus before activation.
`setReturnFocus`		`type ONLY_FOR_FORMAT = \| FocusTargetValueOrFalse \| ((nodeFocusedBeforeActivation: HTMLElement \| SVGElement) => FocusTargetValueOrFalse)` By default, focus trap on deactivation will return to the element that was focused before activation.