@cloudfour/transition-hidden-element
v2.0.2
Published
A JavaScript utility to help you use CSS transitions when showing and hiding elements with the `hidden` attribute.
Downloads
1,625
Readme
Transition Hidden Element
A JavaScript utility to help you use CSS transitions when showing and hiding elements with the hidden
attribute or display: none;
.
Demos
- An example showing this library in action.
- A more complex example showing using this library with staggered child transitions and toggling.
Why was this created?
To properly hide elements from all users including screen reader users, elements should be hidden using the hidden
attribute or display: none;
. However, this prevents elements from being transitioned with CSS. If you'd like to use CSS transitions to show and hide these elements you'll need to use JavaScript to do so. This utility wraps that JavaScript into a small, easy-to-use module.
I also wrote a blog post going into more detail about why this was created and how it works.
How it Works
Showing Elements
To allow transitions when showing an element the utility performs a few steps:
- Remove the
hidden
attribute (ordisplay: none;
). - Trigger a browser reflow.
- Apply a class to trigger the transition(s).
Hiding Elements
To allow transitions when hiding an element the utility performs a few steps:
- Remove a class to trigger the transition(s).
- Wait for the transition to complete, or wait for a timeout to complete. (Depending on initialization settings.)
- Add the
hidden
attribute (ordisplay: none;
).
Animated Children
This library can be used to show or hide an element with transitioned children. For example, when opening a menu, each child link may animate in one-by-one in a staggered fashion. This utility includes API options to support this use case.
Prefers Reduced Motion
Animation can cause health consequences for some users and they may prefer reduced motion. If a user's OS settings signal they prefer reduced motion you should disable your CSS transitions:
@media (prefers-reduced-motion: reduce) {
* {
transition: none !important;
}
}
Getting Started
First, install the package from npm:
npm i @cloudfour/transition-hidden-element --save
Then you can get started. Here's a simple example showing importing the module, initializing a menu, and then showing and hiding it based on user interaction:
// Import our dependency
import { transitionHiddenElement } from '@cloudfour/transition-hidden-element';
// Initialize our menu
const menuTransitioner = transitionHiddenElement({
element: document.querySelector('#menu'),
visibleClass: 'is-open',
});
document.querySelector('#open-menu-button').addEventListener('click', () => {
menuTransitioner.show();
});
document.querySelector('#close-menu-button').addEventListener('click', () => {
menuTransitioner.close();
});
Initialization Options
When initializing transitionHiddenElement
, there are two required parameters and four optional parameters:
const simpleFader = transitionHiddenElement({
element: document.querySelector('.js-simple-fade'), // Required
visibleClass: 'is-shown', // Required
waitMode: 'transitionend', // Optional — defaults to `'transitionend'`
timeoutDuration: null // Optional — defaults to `null`
hideMode: 'hidden', // Optional — defaults to `'hidden'`
displayValue: null // Optional — defaults to `'block'`
});
element {HTMLElement}
element
should be the primary element we're showing and hiding. It will be the element that we'll be adding and removing classes and the hidden
attribute (or display: none;
) from.
visibleClass {String}
visibleClass
is the class that will be added when showing our element
. Adding the class should trigger a transition on our element
or its child elements.
waitMode {String}
waitMode
determines when the utility should re-apply the hidden
attribute (or display: none;
) when hiding. It defaults to transitionend
but has a few options:
transitionend
— Wait for theelement
'stransitionend
event to fire. This works if the element has a transition that will be triggered by removing thevisibleClass
.timeout
— Wait a certain number of milliseconds. This is useful when yourelement
is not the only element transitioning. For example, if removing yourvisibleClass
triggers transitions on child elements, then you should use this option. When using this option be sure to pass in a number for thetimeoutDuration
parameter.immediate
— Don't wait at all.
Regardless of which setting you choose, it will be converted to immediate
if a user's OS settings signal they prefer reduced motion. You should disable other transitions in your CSS for these users as mentioned above.
timeoutDuration {Number}
When using the timeout
option for waitMode
you should be sure to pass in the length of the timeout in milliseconds.
hideMode {String}
hideMode
determines whether elements are hidden by applying the hidden
attribute, or using CSS's display: none;
. It has two options:
hidden
— use thehidden
attribute (this is the default)display
— use CSS'sdisplay: none;
displayValue {String}
When using the display
option for hideMode
, this option determines what display
should be set to when showing elements. e.g. block
, inline
, inline-block
, etc.
Object Methods
After initializing your transitionHiddenElement
it will return an object with a few methods.
show()
Shows your element
. Removes hidden
(or display: none;
), triggers a document reflow, and applies your visibleClass
.
hide()
Hides your element
. Removes your visibleClass
and adds hidden
(or display: none;
).
toggle()
Toggles the visibility of your element
. Shows it if it's hidden and hides it if it's visible.
isHidden()
Returns the current hidden status of your element
. It returns true
if the element has the hidden
attribute, is display: none;
or is missing the visibleClass
.
Development
Feel free to fork the repo and submit a PR with any helpful additions or changes. After cloning the repository run the following commands:
npm i
— Install dependenciesnpm start
- Build and serve a demo server with hot reloading.- View the demo server at
localhost:3000
Testing
Testing is done in the browser using Cypress, since virtual DOM libraries like jsdom don't handle transitions well.
In order to run the tests do the following:
npm start
— launch the servernpm test
— launch Cypress
Tests will also automatically be run when pull requests are created.