Trap Focus

Note: Spartacus 4.x is no longer maintained. Please upgrade to the latest version.

Note: Spartacus 4.x was tested with SAP Commerce Cloud versions 1905 to 2205. Spartacus 4.x has not been verified to work with (and is not guaranteed to work with) SAP Commerce Cloud 2211 or later releases.

Note: This feature is introduced with version 2.0 of the Spartacus libraries.

The cxFocus directive provides functionality to trap the focus of a group of focusable elements. Trap focus (that is, focus-trap) is often required in dialogs, such as modals. As long as the dialog is open, the focus should not leave the dialog when the user keeps tabbing through the focusable elements. Typically, when the focus leaves the last element, the focus should move to the first element. And vice versa, when SHIFT + TAB is pressed, when the focus leaves the first element, the last element should be focused.

Trapping is driven by intercepting the keydown event for the TAB, SHIFT + TAB, arrow UP, and arrow DOWN keys.

Configuration

The trap focus is configurable so that trapping works in both directions, or only for the start or the end of the group. The configuration is provided by the TrapFocusConfig typing and supports three modes.

Trap in Both Directions

The default configuration traps the focus in both directions, at the start and at the end of the form. In the following form, the focus moves automatically to the first element if the user presses TAB (or MOUSE DOWN) on the last element. And vice versa, if the first element is focused, and the user presses SHIFT + TAB (or ARROW UP), the focus moves to the last element:

<form [cx-focus]="{ trap: true }">
  <input name="first" />
  <input name="second" />
  <input name="last" />
</form>

Trap End

When the trap configuration is set to end, the focus is only trapped at the end. This means that if the user presses SHIFT + TAB on the first element, the focus is not trapped in the form. The following is an example:

<form [cx-focus]="{ trap: 'end' }">
  <input name="first" />
  <input name="second" />
  <input name="last" />
</form>

Trap Start

When the trap configuration is set to start, the focus is only trapped at the start. This means that if the user presses TAB on the last element, the focus is not trapped in the form. The following is an example:

<form [cx-focus]="{ trap: 'start' }">
  <input name="first" />
  <input name="second" />
  <input name="last" />
</form>

Extensibility

The trap focus logic is driven by the TrapFocusService. This service can be customized.