Focus Trap
Constrains Tab/Shift+Tab focus cycling within a container element. Useful for dialogs, sidebars, and any overlay that should capture keyboard focus.
import { createFocusTrap } from "phoundry-ui";Interactive Focus Trap
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { TextInput } from "phoundry-ui"; import { createFocusTrap } from "phoundry-ui";
let trapActive = $state(false);
const trap = createFocusTrap({ escapeDeactivates: true, onEscape: () => (trapActive = false), });</script>
<div class="space-y-3"> {#if !trapActive} <Button onclick={() => (trapActive = true)} variant="primary" >Activate Trap</Button > <p class="text-xs text-txt-tertiary"> Click to open a focus-trapped panel. </p> {/if}
{#if trapActive} <div use:trap.action class="space-y-3 rounded-lg border border-accent-primary bg-surface-sunken/50 p-4" > <TextInput value="" placeholder="First input (auto-focused)" /> <TextInput value="" placeholder="Second input" /> <div class="flex gap-2"> <Button variant="primary">Confirm</Button> <Button onclick={() => (trapActive = false)}>Cancel</Button> </div> <p class="text-[11px] text-txt-tertiary"> Tab cycles within this panel. Press <kbd>Escape</kbd> to exit. </p> </div> {/if}</div>FocusTrapOptions
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
autoFocus | boolean | undefined | — | Auto-focus the first focusable element when the trap activates. |
returnFocusOnDeactivate | boolean | undefined | — | Return focus to the previously focused element on deactivation. |
escapeDeactivates | boolean | undefined | — | Allow Escape key to deactivate the trap. |
onEscape | (() => void) | undefined | — | Called when Escape is pressed (if escapeDeactivates is true). |
Return Value
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
action | (node: HTMLElement, params?: FocusTrapActionParams) => { update?: (params: FocusTrapActionParams) => void; destroy: () => void; } | — | Svelte action: use:trap.action or use:trap.action={{ enabled: boolean }}. When enabled is false, Tab capture is off (e.g. stacked modals not on top) without restoring focus. |
activate | () => void | — | Manually activate the trap (called automatically by the action when enabled). |
deactivate | (options?: FocusTrapDeactivateOptions) => void | — | Manually deactivate. Pass restoreFocus: false to pause without moving focus (stacked overlays). Defaults to the trap’s returnFocusOnDeactivate when omitted. |
active | boolean | — | Whether the trap is currently active. |
FocusTrapActionParams (use:trap.action parameter)
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
enabled | boolean | undefined | — | When false, the action does not activate Tab capture until set true again (see action update). |
Usage tips
- Used internally by
Modaland the modal manager overlay - you only need this directly for custom dialogs or sidebar panels. - The action activates the trap when applied (if
enabledis not false) and cleans up ondestroy. - Focus returns to the previously focused element when the trap deactivates (unless
returnFocusOnDeactivateis false). - Only visible, non-disabled focusable elements participate in the cycle.
- Set
escapeDeactivates: trueand provide anonEscapecallback to handle closing.