Skip to content

Latest commit

 

History

History
56 lines (41 loc) · 3.93 KB

focus-trap.md

File metadata and controls

56 lines (41 loc) · 3.93 KB
Raw

Focus Trap

The focusTrap behavior is used prevent focus from leaving a particular element. This is useful for implementing modal dialogs: only the content within the dialog should be interactive, even though the UI underneath may still be visible.

Behavior

  • Activation: As soon as the focus trap is activated, it will ensure that an element within the container has focus. If it doesn't, it will focus the first focusable element within the container, or, if provided, the element indicated by the initialFocus parameter (see API below).
  • External focus changes: If an external cause (e.g. mouse click, scripts, or accessibility software) results in an element outside the container to be focused, focus will immediately be redirected to the last-focused element that is inside the container.
  • Circular tab focus: Using the TAB key on the last focusable element within the container will result in the first focusable element within the container receiving focus. Similarly, Shift+TAB can be used to focus the last element from the first.
  • Global: Only one focus trap can be active at a time. When a focus trap is enabled, if there is already an active focus trap, it becomes suspended and pushed onto a stack. Once the newly-active focus trap is disabled, the most recently-suspended trap will reactivate. Suspended focus traps can be disabled, causing them to be removed from the stack of suspended traps.

Usage

function showDialog() {
  const dialog = document.getElementById('myDialog')
  if (dialog instanceof HTMLElement) {
    dialog.style.display = ''
    return focusTrap(dialog)
  }
}
function hideDialog(controller: AbortController) {
  document.getElementById('myDialog')?.style.display = 'none'
  controller.abort()
}
const dialogController = showDialog()

// later
if (dialogController) {
  hideDialog(dialogController)
}

API

The focusTrap function takes the following arguments.

Name Type Default Description
container HTMLElement When active, only elements within this container (along with the container itself) can be focused.
initialFocus HTMLElement Specifies the element which will receive focus when the focus trap is activated. Defaults to the first tabbable element inside the container.
signal AbortSignal? undefined Optional abort signal to control the focus trap. If one is not provided, an AbortController will be returned, which can be used to disable the focus trap.

Return value

If the signal argument is omitted, focusTrap() will return an AbortController. This object has an abort() method, which can be called to disable the focus trap.

Best practices

  • Focus management is an important consideration for accessible applications. Sometimes poor focus management can make certain tasks impossible to complete for users not using a mouse. To learn more, read the ARIA guidelines for keyboard focus.
  • Only activate a focus trap if all UI outside of the trap container should be inert (non-interactive).
  • Avoid situations where multiple focus traps may be active (e.g. dialogs that open more dialogs). This behavior handles those situations, but the pattern may indicate poor UX.

A note on performance

When focus trap is activated, it must perform reflow to discover focusable elements. Use caution not to rapidly enable and disable focus traps.