{"id":21192967,"url":"https://github.com/cloudfour/transition-hidden-element","last_synced_at":"2025-04-06T07:10:32.240Z","repository":{"id":36933978,"uuid":"229844646","full_name":"cloudfour/transition-hidden-element","owner":"cloudfour","description":"A JavaScript utility to help you use CSS transitions when showing and hiding elements with the `hidden` attribute.","archived":false,"fork":false,"pushed_at":"2025-03-26T23:10:23.000Z","size":2300,"stargazers_count":52,"open_issues_count":1,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-30T06:07:30.203Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudfour.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-12-24T00:53:53.000Z","updated_at":"2025-03-26T23:10:25.000Z","dependencies_parsed_at":"2024-01-21T10:26:17.739Z","dependency_job_id":"119228d9-747e-4b62-afcc-ad0235280e86","html_url":"https://github.com/cloudfour/transition-hidden-element","commit_stats":{"total_commits":279,"total_committers":6,"mean_commits":46.5,"dds":0.5125448028673836,"last_synced_commit":"bece6502426021026a91735bbfa1352b50723bf9"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfour%2Ftransition-hidden-element","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfour%2Ftransition-hidden-element/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfour%2Ftransition-hidden-element/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfour%2Ftransition-hidden-element/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudfour","download_url":"https://codeload.github.com/cloudfour/transition-hidden-element/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247445668,"owners_count":20939958,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-20T19:12:14.638Z","updated_at":"2025-04-06T07:10:32.217Z","avatar_url":"https://github.com/cloudfour.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Transition Hidden Element\n\n[![NPM version](http://img.shields.io/npm/v/@cloudfour/transition-hidden-element.svg)](https://www.npmjs.org/package/@cloudfour/transition-hidden-element) [![Build Status](https://github.com/cloudfour/transition-hidden-element/workflows/CI/badge.svg)](https://github.com/cloudfour/transition-hidden-element/actions?query=workflow%3ACI) [![Renovate](https://img.shields.io/badge/renovate-enabled-brightgreen.svg)](https://renovatebot.com)\n\n\u003e A JavaScript utility to help you use CSS transitions when showing and hiding elements with the `hidden` attribute or `display: none;`.\n\n## Demos\n\n1. [An example](https://codepen.io/phebert/pen/yLybwWY) showing this library in action.\n2. [A more complex example](https://codepen.io/phebert/pen/QWwONMy) showing using this library with staggered child transitions and toggling.\n\n## Why was this created?\n\nTo [properly hide elements from all users including screen reader users](https://cloudfour.com/thinks/see-no-evil-hidden-content-and-accessibility/), 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.\n\nI also [wrote a blog post](https://cloudfour.com/thinks/transitioning-hidden-elements/) going into more detail about why this was created and how it works.\n\n## How it Works\n\n### Showing Elements\n\nTo allow transitions when showing an element the utility performs a few steps:\n\n1. Remove the `hidden` attribute (or `display: none;`).\n2. Trigger a browser reflow.\n3. Apply a class to trigger the transition(s).\n\n### Hiding Elements\n\nTo allow transitions when hiding an element the utility performs a few steps:\n\n1. Remove a class to trigger the transition(s).\n2. Wait for the transition to complete, or wait for a timeout to complete. (Depending on initialization settings.)\n3. Add the `hidden` attribute (or `display: none;`).\n\n### Animated Children\n\nThis 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.\n\n### Prefers Reduced Motion\n\nAnimation can cause health consequences for some users and they may [prefer reduced motion](https://developers.google.com/web/updates/2019/03/prefers-reduced-motion). If a user's OS settings signal they prefer reduced motion you should disable your CSS transitions:\n\n```css\n@media (prefers-reduced-motion: reduce) {\n  * {\n    transition: none !important;\n  }\n}\n```\n\n## Getting Started\n\nFirst, install the package from npm:\n\n```\nnpm i @cloudfour/transition-hidden-element --save\n```\n\nThen 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:\n\n```js\n// Import our dependency\nimport { transitionHiddenElement } from '@cloudfour/transition-hidden-element';\n\n// Initialize our menu\nconst menuTransitioner = transitionHiddenElement({\n  element: document.querySelector('#menu'),\n  visibleClass: 'is-open',\n});\n\ndocument.querySelector('#open-menu-button').addEventListener('click', () =\u003e {\n  menuTransitioner.show();\n});\n\ndocument.querySelector('#close-menu-button').addEventListener('click', () =\u003e {\n  menuTransitioner.close();\n});\n```\n\n## Initialization Options\n\nWhen initializing `transitionHiddenElement`, there are two required parameters and four optional parameters:\n\n```js\nconst simpleFader = transitionHiddenElement({\n  element: document.querySelector('.js-simple-fade'), // Required\n  visibleClass: 'is-shown', // Required\n  waitMode: 'transitionend', // Optional — defaults to `'transitionend'`\n  timeoutDuration: null // Optional — defaults to `null`\n  hideMode: 'hidden', // Optional — defaults to `'hidden'`\n  displayValue: null // Optional — defaults to `'block'`\n});\n```\n\n### element `{HTMLElement}`\n\n`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.\n\n### visibleClass `{String}`\n\n`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.\n\n### waitMode `{String}`\n\n`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:\n\n1. `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`.\n2. `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.\n3. `immediate` — Don't wait at all.\n\nRegardless 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.\n\n### timeoutDuration `{Number}`\n\nWhen using the `timeout` option for `waitMode` you should be sure to pass in the length of the timeout in milliseconds.\n\n### hideMode `{String}`\n\n`hideMode` determines whether elements are hidden by applying the `hidden` attribute, or using CSS's `display: none;`. It has two options:\n\n1. `hidden` — use the `hidden` attribute (this is the default)\n1. `display` — use CSS's `display: none;`\n\n### displayValue `{String}`\n\nWhen 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.\n\n## Object Methods\n\nAfter initializing your `transitionHiddenElement` it will return an object with a few methods.\n\n### show()\n\nShows your `element`. Removes `hidden` (or `display: none;`), triggers a document reflow, and applies your `visibleClass`.\n\n### hide()\n\nHides your `element`. Removes your `visibleClass` and adds `hidden` (or `display: none;`).\n\n### toggle()\n\nToggles the visibility of your `element`. Shows it if it's hidden and hides it if it's visible.\n\n### isHidden()\n\nReturns 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`.\n\n## Development\n\nFeel free to fork the repo and submit a PR with any helpful additions or changes. After cloning the repository run the following commands:\n\n1. `npm i` — Install dependencies\n2. `npm start` - Build and serve a demo server with hot reloading.\n3. View the demo server at `localhost:3000`\n\n### Testing\n\nTesting is done in the browser using Cypress, since [virtual DOM libraries like jsdom don't handle transitions well](https://github.com/jsdom/jsdom/issues/1781).\n\nIn order to run the tests do the following:\n\n1. `npm start` — launch the server\n2. `npm test` — launch Cypress\n\nTests will also automatically be run when pull requests are created.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudfour%2Ftransition-hidden-element","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudfour%2Ftransition-hidden-element","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudfour%2Ftransition-hidden-element/lists"}