Skip to content
Implements ARIA active descendant keyboard navigation
JavaScript
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs Check for Element instead of window Feb 26, 2020
src
test
.eslintrc
.gitignore
.npmrc first commit Nov 22, 2017
.travis.yml Swap Lasso for Webpack Jan 30, 2020
LICENSE first commit Nov 22, 2017
README.md Fix typo on README Jan 30, 2020
babel.config.json Swap Lasso for Webpack Jan 30, 2020
browser.json Fix require-run Jan 31, 2020
index.js Check for Element instead of window Feb 26, 2020
karma.conf.js Swap Lasso for Webpack Jan 30, 2020
package.json 0.3.7 Feb 26, 2020
webpack.docs.js
yarn.lock

README.md

makeup-active-descendant

Build Status Coverage Status Dependency status devDependency status

Implements ARIA active descendant keyboard navigation.

A vanilla JavaScript port of jquery-active-descendant.

Experimental

This CommonJS module is still in an experimental state, until it reaches v1.0.0 you must consider all minor releases as breaking changes. Patch releases may introduce new features, but will be backwards compatible.

Install

// via npm
npm install makeup-active-descendant

// via yarn
yarn add makeup-active-descendant

Example 1: Programmatic Relationship

In this example the focusable element is not an ancestor of the "descendant" elements. The module will add aria-owns to create a programmatic relationship between the two elements. This is typical of a combobox or date-picker type pattern.

Starting markup:

<div class="widget">
    <input type="text">
    <ul>
        <li>Item 1</li>
        <li>Item 2</li>
        <li>Item 3</li>
    </ul>
</div>
// require the module
const ActiveDescendant = require('makeup-active-descendant');

// get the widget root element reference
const widgetEl = document.querySelector('.widget');

// get the focus element reference
const focusEl = widgetEl.querySelector('input');

// get the element that contains the "descendant" items.
// This element will be programmatically "owned" by the focus element.
const containerEl = widgetEl.querySelector('ul');

// create an activeDescendant widget instance on the element
const activeDescendant = ActiveDescendant.createLinear(widgetEl, focusEl, containerEl, 'li');

// listen for events (optional)
widgetEl.addEventListener('activeDescendantChange', function(e) {
    console.log(e.detail);
});

Markup after instantiation:

<div class="widget" id="widget-0">
    <input type="text" aria-owns="widget-0-list-0">
    <ul id="widget-0-list-0">
        <li id="widget-0-item-0" data-makeup-index="0">Item 1</li>
        <li id="widget-0-item-1" data-makeup-index="1">Item 2</li>
        <li id="widget-0-item-2" data-makeup-index="2">Item 3</li>
    </ul>
</div>

Markup after pressing down arrow key on focusable element:

<div class="widget" id="widget-0">
    <input type="text" aria-activedescendant="widget-0-item-0" aria-owns="widget-0-list-0">
    <ul id="widget-0-list-0">
        <li class="active-descendant" id="widget-0-item-0" data-makeup-index="0">Item 1</li>
        <li id="widget-0-item-1" data-makeup-index="1">Item 2</li>
        <li id="widget-0-item-2" data-makeup-index="2">Item 3</li>
    </ul>
</div>

Use CSS to style the active descendant however you wish:

.widget .active-descendant {
    font-weight: bold;
}

Example 2: Hierarchy Relationship

In this example the focusable element is an ancestor of the list items and therefore the "descendant" relationship can be automatically determined from the DOM hierarchy. This is typical of a standalone listbox or grid widget.

NOTE: this module does not add any ARIA roles; only states and properties.

Starting markup:

<div class="widget">
    <ul tabindex="0">
        <li>Item 1</li>
        <li>Item 2</li>
        <li>Item 3</li>
    </ul>
</div>
// require the module
const ActiveDescendant = require('makeup-active-descendant');

// get the widget root element reference
const widgetEl = document.querySelector('.widget');

// get the focus element reference
const focusEl = widgetEl.querySelector('ul');

// in this scenario the container element is the same as the focusable element
const containerEl = focusEL;

// create an activeDescendant widget instance on the element
const activeDescendant = ActiveDescendant.createLinear(widgetEl, focusEl, containerEl, 'li');

// listen for events (optional)
widgetEl.addEventListener('activeDescendantChange', function(e) {
    console.log(e.detail);
});

Markup after instantiation:

<div class="widget" id="widget-0">
    <ul id="widget-0-list-0" tabindex="0">
        <li id="widget-0-item-0" data-makeup-index="0">Item 1</li>
        <li id="widget-0-item-1" data-makeup-index="1">Item 2</li>
        <li id="widget-0-item-2" data-makeup-index="2">Item 3</li>
    </ul>
</div>

Markup after pressing down arrow key on focusable element:

<div class="widget" id="widget-0">
    <ul id="widget-0-list-0" aria-activedescendant="widget-0-item-0" tabindex="0">
        <li class="active-descendant" id="widget-0-item-0" data-makeup-index="0">Item 1</li>
        <li id="widget-0-item-1" data-makeup-index="1">Item 2</li>
        <li id="widget-0-item-2" data-makeup-index="2">Item 3</li>
    </ul>
</div>

Use CSS to style the active descendant however you wish:

.widget .active-descendant {
    font-weight: bold;
}

Options

  • activeDescendantClassName: the HTML class name that will be applied to the ARIA active descendant element (default: 'active-descendant')
  • autoInit: specify an integer or -1 for initial index (default: 0) (see makeup-navigation-emitter)
  • autoReset: specify an integer or -1 for index position when focus exits widget (default: null) (see makeup-navigation-emitter)
  • autoScroll : Specify true to scroll the container as activeDescendant changes (default: false)
  • axis : specify 'x' for left/right arrow keys, 'y' for up/down arrow keys, or 'both' (default: 'both')

Custom Events

  • activeDescendantChange
    • detail
      • fromIndex
      • toIndex

Properties

  • filteredItems: returns filtered items (e.g. non-hidden items)
  • index: the index position of the current active descendant
  • items: returns all items that match item selector

Methods

  • destroy: destroys all event listeners
  • reset: will force a reset to the value specified by autoReset

Dependencies

CI Build

https://travis-ci.org/makeup-js/makeup-active-descendant

Code Coverage

https://coveralls.io/github/makeup-js/makeup-active-descendant

You can’t perform that action at this time.