jquery-roving-tabindex

jQuery collection plugin that implements one or two dimensional roving keyboard tabindex on the items of a widget.

$(widgetSelector).rovingTabindex(rovingItemsSelector, [options]);

Install

npm install jquery-roving-tabindex

Example - One Dimensional

HTML:

<ul role="tablist">
    <li role="tab">Tab 1</li>
    <li role="tab">Tab 2</li>
    <li role="tab">Tab 3</li>
</ul>

Execute plugin:

$('[role=tablist]').rovingTabindex('[role=tab]');

Output:

<ul role="tablist">
    <li role="tab" tabindex="0">Tab 0</li>
    <li role="tab">Tab 1</li>
    <li role="tab">Tab 2</li>
</ul>

First down arrow key will update DOM to:

<ul role="tablist">
    <li role="tab">Tab 0</li>
    <li role="tab" tabindex="0">Tab 1</li>
    <li role="tab">Tab 2</li>
</ul>

Next down arrow key will update DOM to:

<ul role="tablist">
    <li role="tab">Tab 0</li>
    <li role="tab" tabindex="-1">Tab 1</li>
    <li role="tab">Tab 2</li>
</ul>

To listen for roving tabindex changes:

$('.widget').on('rovingTabindexChange', 'li', function(e, data) {
    // this = new roving tab li element
    // data = {fromIndex: n, toIndex: n}
});

Example - Two Dimensional

HTML:

<div class="widget">
    <table>
        <tbody>
            <tr><td>1</td><td>2</td><td>3</td></tr>
            <tr><td>4</td><td>5</td><td>6</td></tr>
            <tr><td>7</td><td>8</td><td>9</td></tr>
        </tbody>
    </table>
</div>

Execute plugin:

$('.widget').rovingTabindex('td', {isGrid: true});

Params

• rovingItemsSelector: selector that identifies the descendant collection that requires a roving tab index
• options.activeIndex: index of the item that receives tabindex on init (default: 0)
• options.autoFocus: set focus when roving tabindex changes (default: true)
• options.autoInit: set initial tabindex state (but not focus) when plugin executes (default: true)
• options.autoReset: reset tabindex state when focus exits widget (default: false)
• options.autoWrap: reaching end of collection will wrap back to beginning, and vice versa (default: false)
• options.axis: x, y or both (default: 'both')
• options.disableHomeAndEndKeys: disable HOME and END key functionality (default: false)
• options.isGrid: specify two-dimensional navigation (default: false)

Triggers

• rovingTabindexChange : fired when collection's roving tabindex changes

Listens

• domChange : trigger on widget when underlying dom changes. For example, new roving items are added.

Dependencies

• jquery
• jquery-linear-navigation
• jquery-grid-navigation
• jquery-prevent-scroll-keys

Development

Useful NPM task runners:

• npm start for local browser-sync development.
• npm test runs tests & generates reports (see reports section below)
• npm run tdd test driven development: watches code and re-tests after any change
• npm run build cleans, lints, tests and minifies

Execute npm run to view all available CLI scripts.

CI Build

https://travis-ci.org/makeup-jquery/jquery-roving-tabindex

Code Coverage

https://coveralls.io/github/makeup-jquery/jquery-roving-tabindex?branch=master

Test Reports

Local test reports are generated under test_reports folder.

JSDocs

Local JSDocs are generated under jsdoc folder.