Overlays@knitui/components
FocusTrap
FocusTrap is a purely behavioural component — it clones its single child and attaches a focus-trap ref so that keyboard focus stays within the wrapped region while active is true. On web, Tab cycles within the trapped element; Tab order restores when active becomes false. Rendering and styling are delegated entirely to the child.
import { FocusTrap } from "@knitui/components";Playground
Loading playground…
<FocusTrap
active
refProp="ref"
/>Examples
Active
Active trap — Tab key stays within the wrapped region until active is set to false.
Loading example…
Inactive
Inactive trap — active={false} disables trapping; Tab moves freely through the page.
Loading example…
With Initial Focus
FocusTrap.InitialFocus — the hidden marker receives focus first; useful in modals and dialogs to prevent focus jumping to the first interactive element unexpectedly.
Loading example…
Controlled Toggle
Controlled toggle — a button outside the trap enables/disables it at runtime, demonstrating the active prop change.
Loading example…
Modal Like
Modal-like overlay — demonstrates the canonical use-case: a dialog that traps focus while open and restores it on close.
Loading example…
Props
| Prop | Type | Default | Description |
|---|---|---|---|
children required | ReactElement<FocusTrapChildProps, string | JSXElementConstructor<any>> | — | Single element child to trap focus within. Must accept a ref. |
active | boolean | undefined | true | When `false`, focus trapping is disabled and Tab behaves normally. |
innerRef | Ref<TamaguiElement> | undefined | — | Ref combined with the internal focus-trap ref. |
refProp | string | undefined | 'ref' | Prop name used to forward the internal ref into the child element. |