onion

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

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.