jquery-roving-tabindex

jQuery collection plugin that implements one or two dimensional roving tabindex keyboard navigation

Usage no npm install needed!

<script type="module">
  import jqueryRovingTabindex from 'https://cdn.skypack.dev/jquery-roving-tabindex';
</script>

README

jquery-roving-tabindex

Build Status Coverage Status Dependency status devDependency status

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

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.