Skip to content
HTML, CSS and JS accordion UI-component for scalable projects.
JavaScript CSS HTML
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Updated Issue Templates May 10, 2018
dist v2: expand accordions on init Dec 2, 2018
docs v2: expand accordions on init Dec 2, 2018
src v2: expand accordions on init Dec 2, 2018
.gitignore gitignore Sep 24, 2017
CODE_OF_CONDUCT.md Create CODE_OF_CONDUCT.md Jul 8, 2017
CONTRIBUTING.md v1.2.0 Dec 2, 2017
LICENSE.md
PULL_REQUEST_TEMPLATE.md v1.2.0 Dec 2, 2017
README.md v2: expand accordions on init Dec 2, 2018
gulpfile.js fix gulp Oct 27, 2018
package-lock.json fix gulp Oct 27, 2018
package.json v2: expand accordions on init Dec 2, 2018

README.md

ARIA ACCORDION

About

HTML, CSS and JS accordion UI-component for scalable projects. User-friendly and accessible: WAI ARIA 1.1 compliant. Go to demo page or check on npm.

  • Developed following BEM methodology
  • User-friendly and accessible
  • Only 5KB JS (minified)
  • JS plugin runs in strict mode
  • Compatible with UMD

Dependencies

jQuery

Developed and tested with jQuery 3.2.1

Cross-browsers tests

  • Google Chrome 57 / macOS Sierra 10
  • iPhone 5s Safari for iOS 10.3.2

Options

Name Default Type Description
accGroupIdPrefix accordion-group-- string Prefix used to generate the IDs of the accordion's widgets
accClass accordion-group__accordion string Class of single accordion elements. (This class is used from the plugin to select the elements in the markup).
headingClass accordion-group__accordion-heading string Class of accordion's heading elements. (This class is used from the plugin to select the elements in the markup).
btnClass accordion-group__accordion-btn string Class of accordion's buttons. (This class is used from the plugin to select the elements in the markup).
panelClass accordion-group__accordion-panel string Class of accordion's panels. (This class is used from the plugin to select the elements in the markup).
contentClass accordion-group__accordion-content string Class of accordion's content elements. (This class is used from the plugin to select the elements in the markup).
expandedClass accordion-group__accordion_expanded string Class added to an expanded accordions.
btnExpandedClass accordion-group__accordion-btn_expanded string Class added to the button of an expanded accordion.
panelExpandedClass accordion-group__accordion-panel_expanded string Class added to a panel of an expanded accordion.
contentRole document token, array of tokens Role of accordion's content. Accepted values: document, application. For more information see https://www.w3.org/TR/wai-aria-1.1/. To set different roles on each accordion, pass an array of tokens.
slideSpeed 300 int (>= 0) Duration of collapse/expand animations.
easing swing string The easing function used for the slide-up and slide-down animation of the accordions. Applies only if cssTransition is set to false, otherwise this option will not have any effect on the transition. Accepted values are swing and linear. For more timing functions a jQuery easing plugin is needed.
cssTransitions false bool Use css transitions to expand/collapse accordions instead of jQuery slide animations. Read section 'Using CSS transitions' for more informations.
expandOnlyOne false bool Only one accordion in the accordion's group can be expanded and one accordion must always be expanded.
keyboardNavigation true bool Allow user to move focus with arrow keys and other shortcuts. For more information see https://www.w3.org/TR/wai-aria-practices-1.1/#accordion.

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-accordion

Usage

  1. Include the JS script aria-accordion.js - or the minified production script aria-accordion.min.js - in the head or the body of your HTML file.
  2. Include the CSS file aria-accordion.css in the head of your HTML file or use the SCSS files in your project. Adapt the CSS rules to match your website's design.
  3. Initialise the widget within an inline script tag, or in an external JS file.

HTML

Use following HTML markup to implement an accordion widget:

<!-- WIDGET BEGIN / GROUP OF ACCORDIONS -->
<div class="accordion-group" id="accordion-group-1">

    <!-- ACCORDION BEGIN -->
    <section class="accordion-group__accordion">
      <header class="accordion-group__accordion-head">
        <h3 class="accordion-group__accordion-heading"><button type="button" class="accordion-group__accordion-btn">Accordion 1</button></h3>
      </header>
      <div class="accordion-group__accordion-panel">
        <div class="accordion-group__accordion-content">
          <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
          <button type="button">Test focus</button>
        </div>
      </div>
    </section>
    <!-- ACCORDION END -->


    <!-- ACCORDION BEGIN -->
    <section class="accordion-group__accordion">
      <header class="accordion-group__accordion-head">
        <h3 class="accordion-group__accordion-heading"><button type="button" class="accordion-group__accordion-btn">Accordion 1</button></h3>
      </header>
      <div class="accordion-group__accordion-panel">
        <div class="accordion-group__accordion-content">
          <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
          <button type="button">Test focus</button>
        </div>
      </div>
    </section>
    <!-- ACCORDION END -->

  </div>

IMPORTANT: do not replace the <button> and do not use any other html element than heading to wrap the button. More information are available at https://www.w3.org/TR/wai-aria-practices-1.1/#accordion.

JS: Initialise

Use following code to initalize the widget:

$('.accordion-group').ariaAccordion({
  option1: value1,
  option2: value2
});

Methods:

Methods can be called on an initialised accordion widget with following syntax:

$('#my-accordion-group').ariaAccordion('methodName', parameter);

The plugin supports following methods: toggle, toggleNoAnimate. The second parameter of the function can be the index (starting from 0) of the accordion, a jQuery selector, or a jQuery element. Methods can be called just on one element at a time: when passing a selector make sure this matches only one element. When passing a jQuery object the length of the object should be 1.

//The following are all valid method's call and lead to the same result

$('#my-accordion-group').ariaAccordion('toggle', 1);
$('#my-accordion-group').ariaAccordion('toggle', '#my-accordion');
$('#my-accordion-group').ariaAccordion('toggle', $('#my-accordion'));

toggle and toggleNoAnimate

toggle expands or collapses an accordion based on the current state of the accordion performing a slide-down or slide-up animation.

$('#my-accordion-group').ariaAccordion('toggle', 1);

toggleNoAnimate also expands or collapses an accordion based on the current state, but instead does not perform any animation.

$('#my-accordion-group').ariaAccordion('toggleNoAnimate', 1);

Custom events

The plugin triggers following events:

  • ariaAccordion.initialised after an accordion's group is initialised
  • ariaAccordion.slideDown when an accordion is expanded
  • ariaAccordion.slideUp when an accordion is collapsed

ariaAccordion.initialised

This event is triggered on window and returns the accordion's group object as arguments.

//listen for ariaAccordion.initialised
$(window).on('ariaAccordion.initialised', function(event, accordionGroup){
  //When an accordion's group is initialised, perform an action
  accordionGroup.element.addClass('aria-accordion_initialised');
});

//Initialise the accordion's groups
$('.accordion-group').ariaAccordion();

ariaAccordion.slideDown and ariaAccordion.slideUp

This events are triggered on window and return the accordion's group object and the index of the toggled accordion as arguments.

//listen for ariaAccordion.slideDown
$(window).on('ariaAccordion.slideDown', function(event, accordionGroup, index){
  console.log('Accordion ' + index + ' in accordion group ' + accordionGroup.element + ' was expanded');
});

Using CSS transitions

By default the plugin is configured to use the jQuery methods slideDown(), slideUp() to expand/collapse accordions. Setting the option cssTransitions to 'true' will disable the JS animations. This will make possible to implement the transitions with css. In fact, the plugin toggles the classes passed along with the options expandedClass, btnExpandedClass and panelExpandedClass when an accordion is toggled.

Open accordions on init

Add the expandedClass (.accordion-group__accordion_expanded) to the accordion element in order to expand it when the widget is initialised. IMPORTANT: works only if expandOnlyOne is set to false.

LICENSE

Aria accordion is licensed under the terms of the MIT license.

See LICENSE.md for detailed informations.

You can’t perform that action at this time.