T-aria-dropdown NPM

ARIA DROPDOWN

About

HTML, CSS and JS UI-components for user-friendly and accessible drop-downs: WAI ARIA 1.1 compliant. Go to demo page or check on npm.

Developed following BEM methodology
User-friendly and accessible
Supports nested drop-downs (>= v2.0.0)
Supports mouse toggling (>= 2.0.0)
Only 5KB JS (minified)
JS plugin runs in strict mode
Compatible with UMD

Dependencies

jQuery

Developed and tested with jQuery 3.2.1

Cross-browser tests

Tested on Google Chrome 57 / macOS Sierra 10.
Tested on Google Chrome 60 / Windows 10.

Options

Name	Default	Type	Description
btnClass	dropdown__btn	string	Class used to select dropdown's buttons.
menuClass	dropdown__menu	string	Class used to select dropdown's collapsible region
dropdownExpandedClass	dropdown_expanded	string	Class added to dropdown when expanded
btnExpandedClass	dropdown__btn_expanded	string	Class added to dropdown's button when dropdown is expanded.
menuExpandedClass	dropdown__collapse_expanded	string	Class added to dropdown's collapsible region when expanded.
slideSpeed	300	int (>= 0)	Slide-up and slide-down animation duration.
easing	swing	string	The easing function to use for the dropdown animation. Applies only for jQuery transitions, if cssTransitions is set to true, this option will not have any effect on the transition. Accepted values are `swing` and `linear`. For more easing functions a jQuery easing plugin is needed.
collapseOnOutsideClick	true	bool	Collapse dropdown, when user clicks on any region of the page which is not part of a dropdown.
collapseOnMenuClick	false	bool	Collapse dropdown even when user clicks inside of it. Useful for non-navigational dropdown, like a dropdown in a toolbar, which should collapse automatically after an option has been selected from user.
expandOnlyOne	true	bool	Automatically collapse dropdown if another dropdown is expanded by user
cssTransitions	false	bool	Use css transitions to expand/collapse drop-downs instead of jQuery slide animation. Read section 'Using CSS transitions' for more informations
expandZIndex	10	int	Z-index of dropdown during expand animation and while expanded.
collapseZIndex	1	int	Z-index set to dropdown just before collapsing.
mouse	false	bool	Toggle dropdown on `mousenter` and `mouseleave` (dropdown remains operable with keyboard)
dynamicBtnLabel	false	bool or string (selector)	Define 'dynamic' labels for the dropdown button. Set the text for the expanded and collapsed status of a dropdown by adding the `data-ariadropdown-expandlabel` and `data-ariadropdown-collapselabel` attributes to the button and setting this option to true (or pass a selector - like `> span` - if you want to inject the text in a specific child element of the button).

Installation

Download the package from GitHub and get the compiled files from the dist folder.

The plugin is also available on npm:

npm install t-aria-dropdown

Usage

Include the JS script dropdown.js - or the minified production script aria-dropdown.min.js - in the head or the body of your HTML file.
Include the CSS file dropdown.css in the head of your HTML file, or include the SCSS files in your project.

HTML

Use following HTML markup to implement a dropdown:

<div class="dropdown">
  <button type="button" class="dropdown__btn">Dropdown</button>
  <div class="dropdown__menu">
    <ul>
      <li>Link 1</li>
      <li>Link 2</li>
      <li>Link 3</li>
      <li>Link 4</li>
      <li>Link 5</li>
    </ul>
    <button type="button" class="dropdown__dismiss-btn">Close dropdown</button>
  </div>
</div>

By default the menu is aligned on the left side with the button. Use modifier classes .dropdown__menu_center or .dropdown__menu_right to change menu alignment.

JS: Initialise

Initialise the plugin as follows:

$('.dropdown').ariaDropdown({
  option1: value1,
  option2: value2
});

Methods:

Methods can be called on an initialised dropdown using following syntax:

$('#my-dropdown').ariaDropdown('methodName');

The plugin supports following methods: slideDown, slideUp, toggle and destroy.

slideDown

The method slideDown expands a dropdown, if currently collapsed

$('#my-dropdown').ariaDropdown('slideDown');

slideUp

The method slideUp collapses a dropdown, if currently expanded.

$('#my-dropdown').ariaDropdown('slideUp');

toggle

Toggle expands or collapses a dropdown based on the current state of the dropdown.

$('#my-dropdown').ariaDropdown('toggle');

destroy

Destroy destroys a dropdown by removing the attributes, classes and event listeners added by the plugin. Also the jQuery data object is removed from the jQuery element's object.

$('#my-dropdown').ariaDropdown('destroy');

Custom events

The plugin triggers following events:

ariaDropdown.initialised after a dropdown is initialised
ariaDropdown.slideDown when a dropdown is expanded
ariaDropdown.slideUp when a dropdown is collapsed
ariaDropdown.destroyed when a dropdown is destroyed

The events are triggered on window and return the dropdown's data object as arguments.

//listen for ariaDropdowns.slideDown
$(window).on('ariaDropdown.slideDown', function(event, dropdown){
  console.log('The dropdown ' + dropdown.element + ' was expanded');
});

Using CSS transitions

By default the plugin is configured to use the jQuery methods slideDown() and slideUp() to expand/collapse drop-downs. Setting the option cssTransitions to 'true' will disable the JS animations. This makes possible to implement the transitions directly with css. In fact, the plugin toggles the classes passed along with the options dropdownExpandedClass, btnExpandedClass and menuExpandedClass, when a dropdown is toggled.