Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/levimcg/accordion-container-element
A generic Custom Element wrapper that turns some headings and other content into an accordion
https://github.com/levimcg/accordion-container-element
accessibility accordion custom-elements progressive-enhancement webcomponents
Last synced: about 8 hours ago
JSON representation
A generic Custom Element wrapper that turns some headings and other content into an accordion
- Host: GitHub
- URL: https://github.com/levimcg/accordion-container-element
- Owner: levimcg
- License: mit
- Created: 2019-12-30T23:05:55.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-05T03:55:55.000Z (almost 2 years ago)
- Last Synced: 2024-04-09T15:11:03.421Z (7 months ago)
- Topics: accessibility, accordion, custom-elements, progressive-enhancement, webcomponents
- Language: JavaScript
- Homepage: https://codepen.io/levimcg/pen/ZEYapRY
- Size: 1.33 MB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 19
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Accordion Container Element
An accessible [Custom Element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) wrapper that adds accordion functionality with keyboard support to a group of headings and panels.
## Overview
- ✅ Follows progressive enhancement best practices. E.g. if `customElements` aren't supported, content falls back to headings and text/panel content.
- ✅ Follows the [ARIA Authoring Practices recommendations for accordions](https://w3c.github.io/aria-practices/#accordion).
- 🙌 Inspired by GitHub's [tab-container-element](https://github.com/github/tab-container-element).
- ✨[**See a demo on CodePen**](https://codepen.io/levimcg/pen/ZEYapRY)✨
## Using the Accordion Container Element
The accordion container is published to npm. To install it in your project, run:
```bash
npm install accordion-container-element
```
If you want to use it inside a JS module, you can import the accordion container. The accordion container element defines itself using `customElements.define()`, so you will not need to use any kind of named import.
```js
import 'accordion-container-element';
```
You can use it in a regular script tag with the `module` attribute.
```html
```
## Accordion markup
By default, the accordion container element has no styling so that you can apply styles however they wish. There are only a couple of requirements for the way the markup inside must be structured.
1. All "summaries" must be a heading (h1-h6) and have a `data-summary` attribute.
1. All "panels" can be (almost) any HTML element, but must have a `data-accordion-panel` attribute.
### 💪 Progressive enhancement
When the accordion container is connected to the DOM the headings inside will be progressively enhanced by wrapping the heading's `textContent` with a button used for toggling the visibility of each panel. This means that if there's an error loading the script or JavaScript is not available for some reason, all the accordion content will still be accessible as some regular headings and text. 🙌
```html
<accordion-container>
<h2 data-summary>Panel one summary</h2>
<div data-panel>
<p>Panel one content...</p>
</div>
<h2 data-summary>Panel two summary</h2>
<div data-panel>
<p>Panel two content...</p>
</div>
<h2 data-summary>Panel three summary</h2>
<div data-panel>
<p>Panel three content...</p>
</div>
</accordion-container>
```
## Events
The accordion container emits one `CustomEvent` called `accordion-container-toggled`. The custom event has a `detail` object with the following keys/values:
- `event.detail.toggle` - The summary toggle button that will be toggled if the event is not canceled.
- `event.detail.panel` - The corresponding panel that will be toggled if the event is not canceled.
Example:
```js
document.addEventListener('accordion-container-toggled', () => {
if (event.detail.toggle.textContent == 'Panel two summary') {
console.log('Second panel!');
// Do stuff only if the second accordion panel was toggled
}
});
```
## About bundling polyfils, etc.
This element is written in standard ES2017 and does not come transpiled or polyfilled in any way. Depending on your use case and browser support needs you may wish to use the [webcomponentsjs](https://github.com/webcomponents/polyfills/tree/master/packages/webcomponentsjs) polyfill.
## Development
To start a local development server that serves the `demo/` folder and watches for changes to `index.js` run the following command in your terminal while in at the root of the repository.
```bash
npm start
```
### Tests
This project uses the very excellent [Open Web Components testing recommendations](https://open-wc.org/testing/).
To run all test run:
```bash
npm run test
```
### Test watch mode
To run test in watch mode, run:
```bash
npm run test:watch
```
This will watch all `*.test.js` files and automatically run tests every time a file changes.