meTrapFocus is a small utility script to trap the focus within a container element.
Trapping the focus is for instance necessary for accessible modal dialogs (see http://www.w3.org/TR/wai-aria-practices/#make_modal). But many dialog-widgets out there don't support keyboard/focus-handling. To enhance the accessibility of those widgets, just initialize meTrapFocus on the container of the dialog (see "Usage").
meTrapFocus depends on meTools.
It also uses Element.prototype.matches
, so you need to include a polyfill for IE (see http://caniuse.com/#feat=matchesselector), which you can find at mePolyfills in the sources-folder.
- Either include all the dependencies yourself and include
me-trap-focus.min.js
from thedist
folder in your HTML page. - or use the standalone bundled
me-trap-focus.bundle.min.js
.
You can find the original JavaScript file in the src
folder of this package.
meTrapFocus has AMD support. This allows it to be lazy-loaded with an AMD loader, such as RequireJS.
In most cases you won't have to change anything in your HTML.
If you have an iFrame as first/last focusable element of the container, tabbing out of the container may not be noticed.
In this case add a tab-reachable dummy-element with the class me-tabout
as first/last element of the container to prevent tabbing out of the container.
If the iFrame has a cross-domain source it can not be focused via script in FireFox.
In this case wrap the iFrame in a focusable wrapper and initialize meTrapFocus with an adjusted focusableSelector
option to prevent the cross-domain-iFrame being detected as focusable.
Initialize meTrapFocus
/**
* Create a new instance
* @param container mixed; id or element; the container in which the focus should be maintained
* @param options object; optional; overwrite the default options
*/
var myFocusTrapper = new meTrapFocus(container [,options])
If the focusable elements within the container change (elements are added or removed) you need to update the list of focusable elements. To update the list of focusable elements, call
myFocusTrapper.update();
To get all possibly focusable elements, call
myFocusTrapper.getFocusables();
To get all elements reachable by tab, call
myFocusTrapper.getTabable();
To get all elements reachable by back-tab, call
myFocusTrapper.getTabable(true);
To destroy the instance, call
myFocusTrapper = myFocusTrapper.destroy();
{
// selector for elements which are focusable
focusableSelector: 'a,frame,iframe,input:not([type=hidden]),select,textarea,button,*[tabindex]',
// selector for an optional element placed before the 1st or after the last tabable element to prevent tabbing out of the page directly to the browser-window (e.g. placed after an iframe as last tabable element)
taboutIndicator: '.me-tabout'
}
You can install meTrapFocus using npm or Bower.
$ npm install me-trap-focus
or
$ bower install me-trap-focus
meTrapFocus is licenses under the MIT licence.