onion
v1.0.0
Published
Toggle elements with CSS transitions and animations the easy way.
Downloads
431
Readme
Onion🧅
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/
Features
- Toggles
is-open
,is-opening
andis-closing
classes at the exact right times to ensure that CSS transitions and animations can be used while togglingdisplay: 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
Installation
Onion can be bundled with your project or added directly to the browser.
Bundle install
Add onion to your project
# NPM
npm install onion
# yarn
yarn add onion
# pnpm
pnpm add onion
Import the package to your script
// ESM
import onion from "onion";
// CommonJS
const onion = require("onion");
Browser install
From unpkg CDN
<script src="https://unpkg.com/onion@latest/dist/onion.umd.js"></script>
Self-hosted
<script src="/path/to/onion.umd.js"></script>
Usage
See /example
for a more detailed example.
HTML
<button class="toggle">Toggle</div>
<div class="box">Example</div>
CSS
.box {
display: none;
opacity: 0;
transition: opacity 0.4s ease-out;
}
.box.is-open {
display: block;
}
.box.is-opening {
opacity: 1;
}
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 display: none;
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
onion.show(el, token?);
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| el
| HTMLElement
| The element to be shown |
| token
| string
| Optional. A custom class to be added while opening |
Hide an element
onion.hide(el, token?);
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| el
| HTMLElement
| The element to be hidden |
| token
| string
| Optional. A custom class to be added while closing |
Toggle an element
onion.toggle(el, force?, openingToken?, closingToken?);
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| el
| 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.