Toggle elements with CSS transitions and animations the easy way.
> Toggle elements with CSS transitions and animations the easy way.
This library addresses the issue of not being able to transition/animate an element while toggling the display property at the same time. See here for a full explanation: https://www.impressivewebs.com/animate-display-block-none/
- Toggles is-open, is-opening and is-closing classes at the exact right times to ensure that CSS transitions and animations can be used while toggling display: none;
- Supports custom CSS classes for easy integration with CSS animation libraries such as animate.css
- Handles rapid toggling properly by aborting any ongoing animations/transitions
- Has built-in 2 second timeout in case of missing CSS transition/animation
- Ignores bubbled transition/animation events
- Written in TypeScript
Onion can be bundled with your project or added directly to the browser.
#### Bundle install
Add onion to your project
``bashNPM
npm install onion
Import the package to your script
js
// ESM
import onion from "onion";// CommonJS
const onion = require("onion");
`#### Browser install
From unpkg CDN
html
`Self-hosted
html
`Usage
See
for a more detailed example.#### HTML
`html
#### CSS
css
.box {
display: none;
opacity: 0;
transition: opacity 0.4s ease-out;
}.box.is-open {
display: block;
}
.box.is-opening {
opacity: 1;
}
`#### JS
js
const toggle = document.querySelector(".toggle");
const box = document.querySelector(".box");toggle.addEventListener("click", function() {
onion.toggle(box);
});
`How it works
Onion does not ship with any CSS styles. You should add your own stylesheet to make it work.
#### 1. Default styles
You should add
to the element by default, as well as any styles for the initial closed state.#### 2. is-open
The
is-open class is added when the element is shown. You should override the default display: none; with display: block;, for example.#### 3. is-opening
The
is-opening class is added on the next event cycle after is-open is added. A CSS transition or animation should be added to this class. The 1-cycle delay ensures that the transition/animation can be played immediately after display: none; is removed.Note:
is-opening is kept on the element until it is closing.#### 4. is-closing
The
is-closing class is added when the element is hiding. A CSS transition or animation should be added to this class. The is-open class will not be removed until the transition or animation ends.
API Reference
#### Show an element
`js
onion.show(el, token?);
`| Parameter | Type | Description |
| --------- | ---- | ----------- |
|
| HTMLElement | The element to be shown |
| token | string | Optional. A custom class to be added while opening |#### Hide an element
`js
onion.hide(el, token?);
`| Parameter | Type | Description |
| --------- | ---- | ----------- |
|
| HTMLElement | The element to be hidden |
| token | string | Optional. A custom class to be added while closing |#### Toggle an element
`js
onion.toggle(el, force?, openingToken?, closingToken?);
`| Parameter | Type | Description |
| --------- | ---- | ----------- |
|
| HTMLElement | The element to be toggled |
| force | boolean | Optional. If true, the element will be shown. Otherwise, it will be hidden. |
| openingToken | string | Optional. A custom class to be added while opening |
| closingToken | string | Optional. A custom class to be added while closing |Note: you can pass
undefined` to skip an optional argument.