{"id":19853890,"url":"https://github.com/magnetikonline/css-animation-event","last_synced_at":"2025-06-26T17:33:34.723Z","repository":{"id":8522389,"uuid":"10137500","full_name":"magnetikonline/css-animation-event","owner":"magnetikonline","description":"Cross browser library for handling CSS animation and transition DOM events with a fallback pattern for unsupported browsers.","archived":false,"fork":false,"pushed_at":"2022-01-11T23:19:15.000Z","size":46,"stargazers_count":91,"open_issues_count":0,"forks_count":9,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-06T20:25:04.078Z","etag":null,"topics":["browser","css-animations","css-transitions"],"latest_commit_sha":null,"homepage":"https://magnetikonline.github.io/css-animation-event/","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/magnetikonline.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}},"created_at":"2013-05-18T06:23:34.000Z","updated_at":"2024-03-13T14:42:37.000Z","dependencies_parsed_at":"2022-09-07T21:50:42.922Z","dependency_job_id":null,"html_url":"https://github.com/magnetikonline/css-animation-event","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magnetikonline%2Fcss-animation-event","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magnetikonline%2Fcss-animation-event/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magnetikonline%2Fcss-animation-event/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magnetikonline%2Fcss-animation-event/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/magnetikonline","download_url":"https://codeload.github.com/magnetikonline/css-animation-event/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251969232,"owners_count":21673180,"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":["browser","css-animations","css-transitions"],"created_at":"2024-11-12T14:07:58.568Z","updated_at":"2025-05-02T01:30:25.154Z","avatar_url":"https://github.com/magnetikonline.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CSS animation event\n\nA very small (approx **800 bytes** minified and gzipped) cross browser compatible library to handle CSS3 animation and transition DOM events with a fall back pattern for unsupported browsers.\n\nTested successfully with CSS animation/transition supported browsers of:\n\n- Google Chrome\n- Mozilla Firefox\n- Opera (12.10+)\n- IE10+\n\nLibrary supports Internet Explorer IE9 and above, a final version with IE8 support is [tagged here](https://github.com/magnetikonline/css-animation-event/tree/ie8-final).\n\n- [Why?](#why)\n- [Usage](#usage)\n- [Example](#example)\n- [Methods](#methods)\n\t- [onAnimationEnd(element,handler[,data])](#onanimationendelementhandlerdata)\n\t- [cancelAnimationEnd(element)](#cancelanimationendelement)\n\t- [onTransitionEnd(element,handler[,data])](#ontransitionendelementhandlerdata)\n\t- [cancelTransitionEnd(element)](#canceltransitionendelement)\n\t- [animationSupport()](#animationsupport)\n\t- [transitionSupport()](#transitionsupport)\n\t- [addAnimation{Start|Iteration|End}(element,handler)](#addanimationstartiterationendelementhandler)\n\t- [removeAnimation{Start|Iteration|End}(element,handler)](#removeanimationstartiterationendelementhandler)\n\t- [addTransitionEnd(element,handler)](#addtransitionendelementhandler)\n\t- [removeTransitionEnd(element,handler)](#removetransitionendelementhandler)\n\n## Why?\n\nThe CSS3 [animation](https://www.w3.org/TR/css3-animations/) and [transition](https://www.w3.org/TR/css3-transitions/) modules both provide useful DOM events which can be used to track the current state of an animation or transition - extremely useful for chaining future application logic as they progress and complete.\n\nWhilst support for these events is (thankfully) provided in virtually every browser that offers CSS [animations](https://caniuse.com/#feat=css-animation) and [transitions](https://caniuse.com/#feat=css-transitions), as a front-end developer you are still left with the issue of coding alternative program flows where support isn't available and therefore won't fire your animation/transition event handlers.\n\nConsider the following example:\n\n```css\n#movethis {\n  /* leaving out browser prefixes for brevity */\n  height: 100px;\n  transition: height 1.5s ease-in;\n}\n\n#movethis.nowmove {\n  height: 300px;\n}\n```\n\n```js\n// determineCSSTransitionSupport() would determine if browser supports CSS transitions\nvar supportCSSTransitions = determineCSSTransitionSupport();\n\n// move our element\nvar moveThisEl = document.getElementById('movethis');\nmoveThisEl.className += ' nowmove';\n\n// code around no transition support\nif (supportCSSTransitions) {\n  moveThisEl.addEventListener('transitionend',nextUIStep,false);\n} else {\n  nextUIStep();\n}\n\nfunction nextUIStep() {\n  // the transition ended, keep going\n}\n```\n\nHaving to continually make the decision to utilise DOM animation/transition events vs. a graceful fallback (via `supportCSSTransitions` in example above) throughout your UI code soon becomes clumsy and error prone.\n\n## Usage\n\n[CSSAnimEvent](cssanimevent.js) manages the above situation in a different way, relying on the fact that CSS transitions by design fall back gracefully with unsupported browsers handling element CSS property changes as instant, with a zero transition time.\n\nMethods `onAnimationEnd(element,handler)` and `onTransitionEnd(element,handler)` simply mimic this behaviour by instantaneously calling the given `handler` for browsers that don't provide animation and/or transition support.\n\nRewriting the above JavaScript example we can now do:\n\n```js\n// move our element\nvar moveThisEl = document.getElementById('movethis');\nmoveThisEl.className += ' nowmove';\n\n// browsers supporting CSS transitions will call nextUIStep() after the transition ends\n// ...otherwise it will be called as window.setTimeout(nextUIStep)\nCSSAnimEvent.onTransitionEnd(moveThisEl,nextUIStep);\n\nfunction nextUIStep() {\n  // the transition ended, keep going\n}\n```\n\nOne caveat to be aware of, both `onAnimationEnd()` and `onTransitionEnd()` create 'one shot' event handlers and should be called *just after* CSS updates have been applied to the element, allowing instant delegation back to the given callback handler for unsupported browsers.\n\nInternally `CSSAnimEvent` attaches singular `animationend` and `transitionend` event handlers to the `\u003chtml/\u003e` element and delegates to given callbacks as required.\n\nUsing CSS `animation/@keyframes` is *slightly* more work since animated elements will never reach their intended keyframe target within unsupported browsers, but a little CSS/JavaScript can handle this situation:\n\n```css\n@keyframes myanimation {\n  /* prior animation steps in here */\n\n  100% {\n    background: #f00;\n    height: 300px;\n  }\n}\n\n#movethis {\n  height: 100px;\n}\n\n#movethis.nowmove {\n  animation: myanimation 1s linear 1 forwards;\n}\n\n#movethis.finish {\n  /* faux the target of myanimation for older browsers */\n  background: #f00;\n  height: 300px;\n}\n```\n\n```js\n// move our element\nvar moveThisEl = document.getElementById('movethis');\nmoveThisEl.className += ' nowmove';\n\nCSSAnimEvent.onAnimationEnd(moveThisEl,nextUIStep);\n\nfunction nextUIStep(el) {\n  // faux the animation target, by adding 'finish' class to element\n  el.className += ' finish';\n\n  // keep going\n}\n```\n\n## Example\n\nView a very [basic example of this in action](https://magnetikonline.github.io/css-animation-event/) using animation and transition chaining.\n\nFor capable browsers the tweens will run as expected - alternatively the DOM elements will update instantly from start to finish, via the same event handler execution flow.\n\nAs a small bonus, `CSSAnimEvent` also adds a handy CSS styling hook; `cssanimactive`, which can be used for specific styling which is applied *only* during the animation/transition period.\n\n```html\n\u003c!-- our element before onAnimationEnd()/onTransitionEnd() --\u003e\n\u003cdiv id=\"movethis\" class=\"movethis-basestyle\"\u003e\n\n\u003c!-- our element after onAnimationEnd()/onTransitionEnd() called --\u003e\n\u003cdiv id=\"movethis\" class=\"movethis-basestyle cssanimactive\"\u003e\n\n\u003c!-- and finally, once the animation/transition ends --\u003e\n\u003cdiv id=\"movethis\" class=\"movethis-basestyle\"\u003e\n```\n\nThe [example](https://magnetikonline.github.io/css-animation-event/) uses this CSS styling hook to provide a red border to each box during it's animation/transition period.\n\n## Methods\n\nAll methods are under a `window.CSSAnimEvent` namespace.\n\n### `onAnimationEnd(element,handler[,data])`\n\n- Adds a 'one shot' event handler to the given DOM `element`, with `handler` executing either upon `animationend` or instantaneously if CSS animation support not detected.\n- The `handler` will be passed `element` that fired the event and an optional `data` payload as a second parameter.\n- The given DOM element will be decorated with a CSS class `cssanimactive`, removed upon animation completion which can be used as a CSS styling hook.\n\n### `cancelAnimationEnd(element)`\n\nCancel a 'one shot' event handler set by `onAnimationEnd()` on the given DOM `element`.\n\n### `onTransitionEnd(element,handler[,data])`\n\n- Adds a 'one shot' event handler to the given DOM `element`, with `handler` executing either upon `transitionend` or instantaneously if CSS transition support not detected.\n- The `handler` will be passed `element` that fired the event and an optional `data` payload as a second parameter.\n- The given DOM element will be decorated with a CSS class `cssanimactive`, removed upon transition completion which can be used as a CSS styling hook.\n\n### `cancelTransitionEnd(element)`\n\nCancel a 'one shot' event handler set by `onTransitionEnd()` on the given DOM `element`.\n\n### `animationSupport()`\n\nReturns `true` if CSS animation support is detected.\n\n### `transitionSupport()`\n\nReturns `true` if CSS transition support is detected.\n\n### `addAnimation{Start|Iteration|End}(element,handler)`\n\n- Add `animation{start|iteration|end}` native event handlers to DOM elements.\n- Provides a handy cross browser wrapper having done browser detection for you. Does **not** provide faux event firing for non-supported browsers.\n- Returns `true` where supported, `false` otherwise.\n\n### `removeAnimation{Start|Iteration|End}(element,handler)`\n\n- Remove `animation{start|iteration|end}` native event handlers for above.\n- Returns `true` where supported, otherwise `false`.\n\n### `addTransitionEnd(element,handler)`\n\n- Add `transitionend` native event handlers to DOM elements.\n- Provides a handy cross browser wrapper having done browser detection for you. Does **not** provide faux event firing for non-supported browsers.\n- Returns `true` on success/support, `false` otherwise.\n\n### `removeTransitionEnd(element,handler)`\n\n- Remove `transitionend` native event handlers for above.\n- Returns `true` where supported, otherwise `false`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagnetikonline%2Fcss-animation-event","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmagnetikonline%2Fcss-animation-event","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagnetikonline%2Fcss-animation-event/lists"}