FocusTrap – Once UI

FocusTrap cycles Tab and Shift+Tab within its subtree while active, and returns focus to wherever it came from when deactivated. It is the piece that makes a dialog keyboard-safe: without it Tab walks straight out of the panel into the page behind, which for a screen-reader or keyboard user means the dialog effectively is not modal.

DropdownWrapper uses it, and so does ArrowNavigation when you set trapFocus. Reach for it directly when you are building an overlay of your own.

FocusTrap

const [open, setOpen] = useState(false);

<FocusTrap active={open} onEscape={() => setOpen(false)}>
<Column background="surface" radius="l" padding="24" gap="16">
  <Heading variant="heading-strong-m">Rename project</Heading>
  <Input id="name" label="Name" />
  <Row gap="8" horizontal="end">
    <Button variant="secondary" onClick={() => setOpen(false)}>Cancel</Button>
    <Button onClick={save}>Save</Button>
  </Row>
</Column>
</FocusTrap>

What it traps

Focusable elements are found with button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"]), in DOM order. Two consequences worth knowing:

A region with no focusable elements focuses the container itself, so focus is still inside rather than left on the page behind.
Arrow keys are deliberately not handled — they pass through, so ArrowNavigation can own them. The two compose: FocusTrap decides what Tab may reach, ArrowNavigation decides what the arrows move between.

Controlling where focus lands

By default the trap focuses the first focusable element on activation and restores the previously focused element on deactivation. Both ends can be pointed somewhere specific.

Focus targets

const input = useRef<HTMLInputElement>(null);
const trigger = useRef<HTMLButtonElement>(null);

// Open on the field rather than the first button, and hand focus back to the
// trigger even if it was not what opened the panel.
<FocusTrap
active={open}
initialFocusRef={input}
returnFocusRef={trigger}
onEscape={close}
>
{children}
</FocusTrap>

Set autoFocus={false} when the region should open without stealing focus — an inline editor revealed under the cursor, say. Set restoreFocus={false} when the element that opened the region is gone by the time it closes, and returning focus to it would throw the user to the top of the document.

Escape

onEscape fires on the Escape key and nothing else — the trap never closes itself. Owning the open state in the caller is what lets a confirm step or an unsaved-changes prompt sit in between.

API reference

	Type	Default
childrenrequired	React.ReactNode	—
activerequired Whether the trap is on. Required.	boolean	—
onEscape Called on the Escape key. The trap does not close itself.	() => void	—
containerRef Supply the container ref when the caller also needs it.	RefObject<HTMLDivElement \| null>	—
className	string	—
style	React.CSSProperties	—
initialFocusRef Element to focus on activation, instead of the first focusable one.	RefObject<HTMLElement \| null>	—
returnFocusRef Element to focus on deactivation, instead of the previously focused one.	RefObject<HTMLElement \| null>	—
restoreFocus Return focus when it deactivates.	boolean	true
autoFocus Move focus into the region when it activates.	boolean	true