npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@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

  1. An example showing this library in action.
  2. 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:

  1. Remove the hidden attribute (or display: none;).
  2. Trigger a browser reflow.
  3. Apply a class to trigger the transition(s).

Hiding Elements

To allow transitions when hiding an element the utility performs a few steps:

  1. Remove a class to trigger the transition(s).
  2. Wait for the transition to complete, or wait for a timeout to complete. (Depending on initialization settings.)
  3. Add the hidden attribute (or display: 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:

  1. transitionend — Wait for the element's transitionend event to fire. This works if the element has a transition that will be triggered by removing the visibleClass.
  2. timeout — Wait a certain number of milliseconds. This is useful when your element is not the only element transitioning. For example, if removing your visibleClass triggers transitions on child elements, then you should use this option. When using this option be sure to pass in a number for the timeoutDuration parameter.
  3. 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:

  1. hidden — use the hidden attribute (this is the default)
  2. display — use CSS's display: 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:

  1. npm i — Install dependencies
  2. npm start - Build and serve a demo server with hot reloading.
  3. 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:

  1. npm start — launch the server
  2. npm test — launch Cypress

Tests will also automatically be run when pull requests are created.