handorgel

Accessible W3C conform accordion written in ES6.

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
handorgel
26031.0.0a year ago7 years agoMinified + gzip package size for handorgel in KB

Readme

Handorgel
!NPM versionnpm-imagenpm-url !Coding Stylestyle-imagestyle-url !MIT Licenselicense-imagelicense-url
Accessible W3C conform accordion written in ES6. Handorgel is the Swiss German name for accordion.
Visit the demo

Features

  • ARIA accessible
  • Keyboard interaction
  • Extensive API
  • Animated collapsing
  • Fully customizable via CSS
  • No external dependencies
  • Lightweight (~3kb minified and gziped)

Installation

Package manager

Manager | Command --- | --- npm | npm install handorgel yarn | yarn add handorgel

CDN / Download

File | CDN --- | --- CSS | handorgel.css CSS (minified) | handorgel.min.css JS | handorgel.js JS (minified) | handorgel.min.js

Usage

Markup

<div class="handorgel">
  <h3 class="handorgel__header">
    <button class="handorgel__header__button">
      Title
    </button>
  </h3>
  <div class="handorgel__content" data-open>
    <div class="handorgel__content__inner">
      Content openened by default
    </div>
  </div>
  <h3 class="handorgel__header">
    <button class="handorgel__header__button">
      Title 2
    </button>
  </h3>
  <div class="handorgel__content">
    <div class="handorgel__content__inner">
      Content closed by default
    </div>
  </div>

  ...

</div>

Note: Use the heading tags that fit into your content to output semantic markup.

CSS

Import the SASS file from your node_modules folder to make use of the variables:
// e.g. changing opening/closing transition times
$handorgel__content--open-transition-height-time: .1s;
$handorgel__content--open-transition-opacity-time: .2s;
$handorgel__content-transition-height-time: .05s;
$handorgel__content-transition-opacity-time: .05s;
//...

@import '~handorgel/src/scss/style';

Alternatively you can just include the built CSS file inside the /lib folder file or from the CDN.

Javascript

Initialization (with all options and their defaults):
var accordion = new handorgel(document.querySelector('.handorgel'), {

  // whether multiple folds can be opened at once
  multiSelectable: true,
  // whether the folds are collapsible
  collapsible: true,

  // whether ARIA attributes are enabled
  ariaEnabled: true,
  // whether W3C keyboard shortcuts are enabled
  keyboardInteraction: true,
  // whether to loop header focus (sets focus back to first/last header when end/start reached)
  carouselFocus: true,

  // attribute for the header or content to open folds at initialization
  initialOpenAttribute: 'data-open',
  // whether to use transition at initial open
  initialOpenTransition: true,
  // delay used to show initial transition
  initialOpenTransitionDelay: 200,

  // header/content element selectors or array of elements
  headerElements: '.handorgel__header',
  contentElements: '.handorgel__content',

  // header/content class if fold is open
  headerOpenClass: 'handorgel__header--open',
  contentOpenClass: 'handorgel__content--open',

  // header/content class if fold has been opened (transition finished)
  headerOpenedClass: 'handorgel__header--opened',
  contentOpenedClass: 'handorgel__content--opened',

  // header/content class if fold has been focused
  headerFocusClass: 'handorgel__header--focus',
  contentFocusClass: 'handorgel__content--focus',

  // header/content class if fold is disabled
  headerDisabledClass: 'handorgel__header--disabled',
  contentDisabledClass: 'handorgel__content--disabled',

})

API

Events

Event | Description | Parameters --- | --- | --- destroy | Accordeon is about to be destroyed. | destroyed | Accordeon has been destroyed. | fold:open | Fold is about to be opened. | HandorgelFold: Fold instance fold:opened | Fold has opened. | HandorgelFold: Fold instance fold:close | Fold is about to be closed. | HandorgelFold: Fold instance fold:closed | Fold has closed. | HandorgelFold: Fold instance fold:focus | Fold button has been focused. | HandorgelFold: Fold instance fold:blur | Fold button has lost focus. | HandorgelFold: Fold instance
How to listen for events:
var accordion = new handorgel(document.querySelector('.handorgel'))

// listen for event
accordion.on('fold:open', (fold) => {
  // ...
})

// listen for event once
accordion.once('fold:open', (fold) => {
  // ...
})

// remove event listener
accordion.off('fold:open', fn)

Methods

Handorgel Class

Method | Description | Parameters --- | --- | --- update | Update fold instances (use if you dynamically append/remove DOM nodes). | focus | Set focus to a new header button (you can also directly use the native focus() method on the button). | target: New header button to focus (next, previous, last or first) destroy | Destroy fold instances, remove event listeners and ARIA attributes. |
Example:
var accordion = new handorgel(document.querySelector('.handorgel'))

// destroy
accordion.destroy()

HandorgelFold Class

Method | Description | Parameters --- | --- | --- open | Open content. | transition: Whether transition should be active during opening (default: true). close | Close content. | transition: Whether transition should be active during closing (default: true). toggle | Toggle content. | transition: Whether transition should be active during toggling (default: true). disable | Disable fold. | enable | Enable fold. | focus | Set focus to fold button. | blur | Remove focus from fold button. | destroy | Remove event listeners and ARIA attributes. |
Example:
var accordion = new handorgel(document.querySelector('.handorgel'))

// close first fold
accordion.folds[0].close()

Browser compatibility

  • Newest two browser versions of Chrome, Firefox, Safari and Edge

Development

  • npm run build - Build production version of the feature.
  • npm run demo - Build demo of the feature, run watchers and start browser-sync.
  • npm run test - Test the feature.

License

MIT LICENSE