Skip to content

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
interactive-focus-trap.svelte
<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

NameTypeDefaultDescription
autoFocusboolean | undefined—Auto-focus the first focusable element when the trap activates.
returnFocusOnDeactivateboolean | undefined—Return focus to the previously focused element on deactivation.
escapeDeactivatesboolean | 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

NameTypeDefaultDescription
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.
activeboolean—Whether the trap is currently active.

FocusTrapActionParams (use:trap.action parameter)

From phoundry-ui@0.4.21

NameTypeDefaultDescription
enabledboolean | undefined—When false, the action does not activate Tab capture until set true again (see action update).

Usage tips

  • Used internally by Modal and the modal manager overlay - you only need this directly for custom dialogs or sidebar panels.
  • The action activates the trap when applied (if enabled is not false) and cleans up on destroy.
  • Focus returns to the previously focused element when the trap deactivates (unless returnFocusOnDeactivate is false).
  • Only visible, non-disabled focusable elements participate in the cycle.
  • Set escapeDeactivates: true and provide an onEscape callback to handle closing.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.