docs.md

Classes

focusTrap

deepFocusTrap

focusTrap

Kind: global class

• focusTrap
  • new focusTrap(config)
  • .elements ⇒ Array.<HTMLElement> | NodeList
  • .setReturnFocusEl([el])
  • .updateElements([els])
  • .setElements([els])
  • .activate()
  • .deactivate()

new focusTrap(config)

used to trap focus on a group of elements, can be an unordered list of elements and can also pierce the shadow dom (though has trouble preserving order if elements are of different type due to limitations with query-shadow-dom library)

Param	Type	Default	Description
config	object
config.el	string | HTMLElement		A selector or element used to trap focus within
[config.returnFocus]	boolean	true	An option when set to true returns focus upon deactivation to the last element that had focus before the trap was activated. Defaults to true.
[config.focusElement]	HTMLElement		An element to focus on as soon as the focus trap is activated.
[config.escCallback]	callback		A callback to be called when the user presses the escape key. Note his automatically calls deactivate() after escCallback
[config.includeActiveElement]	boolean	false	Includes element currently in focus when focusTrap is activated within the focusable elements.
[config.unordered]	boolean	false	Allows for elements to be in an order in the dom. Then follows the order of appearance in the focusableElements array instead.

focusTrap.elements ⇒ Array.<HTMLElement> | NodeList

Gets the focusable elements that focusTrap will cycle focus onn

Kind: instance property of focusTrap
Returns: Array.<HTMLElement> | NodeList - A list of elements that focusTrap will cycle focus on

focusTrap.setReturnFocusEl([el])

Sets the returnFocusEl or defaults to the current focused element (before focus trap is activated)

Kind: instance method of focusTrap

Param	Type	Description
[el]	HTMLElement	An element to set focus upon the deactivation of the focus trap

focusTrap.updateElements([els])

A alias for setElements.

• Set the elements to cycle focus on within the focus trap. Uses the config.el selector to get its focusable children or takes a custom list of elements to cycle focus on.

Kind: instance method of focusTrap

Param	Type	Description
[els]	Array.<HTMLElement> | NodeList	An array of elements or Nodelist of the elements to cycle through in the focus trap.

focusTrap.setElements([els])

Set the elements to cycle focus on within the focus trap. Uses the config.el selector to get its focusable children or takes a custom list of elements to cycle focus on.

Kind: instance method of focusTrap

Param	Type	Description
[els]	Array.<HTMLElement> | NodeList	An array of elements or Nodelist of the elements to cycle through in the focus trap.

focusTrap.activate()

Activates the focus trap, by listening for keydown events on the focusTrap element or window for unordered elements

Kind: instance method of focusTrap

focusTrap.deactivate()

Deactivates the focus trap and returns focus to the last element in focus before focus trap was activated (if the config.returnFocus option is set to true - which is the default)

Kind: instance method of focusTrap

deepFocusTrap

Kind: global class

• deepFocusTrap
  • new deepFocusTrap(config)
  • .setElements([els])

new deepFocusTrap(config)

Used as a focus trap that can pierce the shadow dom. Meaning if you are using native web components and you have a component within a component. This focus trap will be able to peirce through the shadow dom and make a focus trap out of the child components as well.

Param	Type	Default	Description
config	object
config.el	string | HTMLElement		A selector or element used to trap focus within
[config.returnFocus]	boolean	true	An option when set to true returns focus upon deactivation to the last element that had focus before the trap was activated. Defaults to true.
[config.focusElement]	HTMLElement		An element to focus on as soon as the focus trap is activated.
[config.deep]	boolean	true	When set to false focusTrap will not peirce the shadowDOM.
[config.escCallback]	callback		A callback to be called when the user presses the escape key.
[config.includeActiveElement]	boolean	false	Includes element currently in focus when focusTrap is activated within the focusable elements.
[config.unordered]	boolean	false	Allows for elements to be in an order in the dom. Then follows the order of appearance in the focusableElements array instead.

deepFocusTrap.setElements([els])

Set the elements to cycle focus on within the focus trap. Uses the config.el selector to get its focusable children or takes a custom list of elements to cycle focus on.

Kind: instance method of deepFocusTrap

Param	Type	Description
[els]	Array.<HTMLElement> | NodeList	An array of elements or Nodelist of the elements to cycle through in the focus trap.