{"id":18763468,"url":"https://github.com/fabiandev/css-animator","last_synced_at":"2025-06-12T21:36:36.329Z","repository":{"id":7058688,"uuid":"56085860","full_name":"fabiandev/css-animator","owner":"fabiandev","description":"Animate elements using CSS classes with support for Angular.","archived":false,"fork":false,"pushed_at":"2023-01-07T04:08:21.000Z","size":10055,"stargazers_count":80,"open_issues_count":10,"forks_count":13,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-11T06:39:03.188Z","etag":null,"topics":["angular","animation-builder","css-animations","javascript","typescript","web"],"latest_commit_sha":null,"homepage":"https://fabiandev.github.io/css-animator/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fabiandev.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":"2016-04-12T17:58:17.000Z","updated_at":"2024-02-21T10:42:53.000Z","dependencies_parsed_at":"2023-01-13T14:15:08.590Z","dependency_job_id":null,"html_url":"https://github.com/fabiandev/css-animator","commit_stats":null,"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiandev%2Fcss-animator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiandev%2Fcss-animator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiandev%2Fcss-animator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiandev%2Fcss-animator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fabiandev","download_url":"https://codeload.github.com/fabiandev/css-animator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253528884,"owners_count":21922625,"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":["angular","animation-builder","css-animations","javascript","typescript","web"],"created_at":"2024-11-07T18:26:15.195Z","updated_at":"2025-05-11T06:39:10.247Z","avatar_url":"https://github.com/fabiandev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# css-animator\n\nThis package was created out of the need for using CSS animations with a library like [animate.css](https://github.com/daneden/animate.css) in Angular2 when there was no useful animation builder available yet.  \n\ncss-animator works with any JavaScript application and takes the pain out of applying CSS animations\nmanually. It also takes care of positioning elements that are being animated, among other useful things.\n\nFeel free to [open an issue](https://github.com/fabianweb/css-animator/issues/new) if you're experiencing issues, or if you have any suggestions or comments.  \n\nThe package includes ES5 compiled files, alongside TypeScript typings and source maps. Also UMD bundle files are included.\n\n## Tutorials\n\n[Devdactic - How to Add Animations To Your Ionic App](http://devdactic.com/animations-ionic-app/) (Tutorial)  \n[Devdactic - How to Add Animations To Your Ionic App](https://www.youtube.com/watch?v=8pOsJDZbJk0) (Video Tutorial)  \n[Ionic Academy - Include CSS+JS Files from NPM Packages with Ionic](https://ionicacademy.com/ionic-include-css-files-from-npm/) (Tutorial)\n\n## TL;DR (if you are having positioning issues)\n\n*Question:* **Other elements jump around during animation or after showing/hiding**\n\n*Answer:* **Try to change the `pin` and `useVisibility` options** (and have a look at all the other customization options)\n\n```ts\nanimator.pin = false;\nanimator.useVisibility = true;\n```\n\n# Usage\n\nYou can install `css-animator` from `npm` or use one of the available `UMD` bundles.\n## Use as dependency\n\n```bash\n$ yarn add css-animator\n```\n\n```bash\n$ npm install --save css-animator\n```\n\n```bash\n$ jspm install npm:css-animator\n```\n\n## Use the `UMD` bundle\n\n| Name (to `require`) | Bundle | |\n| --- | --- | ---\n| `css-animator/builder` | `bundles/builder.min.js` | Includes `AnimationBuilder` only |\n| `css-animator` | `bundles/css-animator.min.js` | Requires `@angular/core` as peer dependency |\n\n\u003e See https://jsfiddle.net/4ec57wpb/1/ for a full basic example\n\n```html\n\u003chtml\u003e\n\u003chead\u003e\n  \u003cscript src=\"https://unpkg.com/css-animator@latest/bundles/builder.min.js\"\u003e\u003c/script\u003e\n  \u003clink rel=\"stylesheet\" href=\"https://cdnjs.cloudflare.com/ajax/libs/animate.css/3.7.2/animate.min.css\"/\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n  \u003c!-- ... --\u003e\n\n  \u003cscript\u003e\n    (function() {\n      const AnimationBuilder = window['css-animator/builder'].AnimationBuilder;\n      const animator = new AnimationBuilder();\n\n      // ...\n    })();\n  \u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n# Example\n\n`css-animator` is being used in the project [angular2-quiz-app](https://github.com/fabiandev/angular2-quiz-app).  \n\nA very basic example can be found in the [`docs/`](/docs) folder, which is also hosted on GitHub Pages: https://fabiandev.github.io/css-animator/\n\n# Usage\n\nUse this package in combination with CSS animations.  \nA library like [animate.css](https://github.com/daneden/animate.css) already offers a lot of great animations out of the box.  \n\nYou can install both packages by running:\n\n```bash\n$ yarn add css-animator animate.css\n```\n\n## Basic Usage\n\nYou can use css-animator without Angular2. Just import the class and animate any `HTMLElement`.\n\n```ts\nimport { AnimationBuilder } from 'css-animator/builder';\n\nlet animator = new AnimationBuilder();\n\nanimator.setType('shake').animate(element);\n```\n\nWant to know when an animation has finished? The AnimationBuilder instance returns a promise:\n\n```ts\nanimator\n  .setType('shake')\n  .animate(element)\n  .then(() =\u003e {\n    // Animation finished\n  })\n  .catch(() =\u003e {\n    // Animation interrupted\n  });\n```\n\nYou may also change the default options for every instance that is created once changed:\n\n```ts\nimport { AnimationBuilder } from 'css-animator/builder';\n\nAnimationBuilder.defaults.pin = false;\nAnimationBuilder.defaults.useVisibility = true;\n```\n\n\u003e Note: changing `pin` and `useVisibility` may be the way to go if you have issues with the possition of other elements during animation\n\n## Angular Usage\n\nBefore getting started and to make use of the directive and the service provided by css-animator,\nyou have to import its module:\n\n```ts\nimport { NgModule } from '@angular/core';\nimport { BrowserModule } from '@angular/platform-browser';\nimport { AppComponent } from './app.component';\nimport { AnimatorModule } from 'css-animator';\n\n@NgModule({\n  imports: [\n    BrowserModule,\n    AnimatorModule\n  ],\n  declarations: [\n    AppComponent\n  ],\n  bootstrap: [\n    AppComponent\n  ],\n})\nexport class AppModule { }\n```\n\n### Angular Service\n\nThere is a little Angular2 service included, that gives you the power of dependency injection out of the box.\n\n```ts\nimport { Component, OnInit } from '@angular/core';\nimport { AnimationService, AnimationBuilder } from 'css-animator';\n\n@Component({ ... })\nexport class SomeComponent implements OnInit {\n\n  private animator: AnimationBuilder;\n\n  constructor(animationService: AnimationService, private elementRef: ElementRef) {\n    this.animator = animationService.builder();\n  }\n\n  ngOnInit() {\n    this.animator.setType('fadeInUp').show(this.elementRef.nativeElement);\n  }\n\n}\n```\n\n### Angular Directive\n\nFeel free to create your own directive around css-animator. For you to get started, there is one included in this package.\n\n```ts\nimport { Component } from '@angular/core';\n\n@Component({\n  selector: 'my-app',\n  template: `\n    \u003cdiv animates #animation=\"animates\"\u003e\n      \u003cspan (click)=\"animation.start({type: 'bounce'})\"\u003eClick me!\u003c/span\u003e\n    \u003c/div\u003e\n  `\n})\nexport class AppComponent {\n\n}\n```\n\nIt is possible to default options on the element, that will be used if you call `animation.start()`.\nYou can pass any option that the interface `AnimationOptions` supports like this: `animation.start({type: 'bounce', duration: 800})`.\n\n```html\n\u003cdiv\nanimates\n#animation=\"animates\"\nanimates=\"{ type: 'wobble', duration: '2000' }\" // default options are optional\nanimatesInitMode=\"show\" // Can be used with [animatesOnInit] for \"show\" or \"hide\"\n[animatesOnInit]=\"{ type: 'fadeInUp' }\" // automatically animate on init (optional)\n(click)=\"animation.start()\"\n(mouseleave)=\"animation.pause()\"\n(mouseenter)=\"animation.resume()\"\n\u003e\n\u003c/div\u003e\n```\n\n\u003e You can also animate host elements with css-animator!\n\n# API\n\n## AnimationOptions\n\nBelow are all options supported by css-animator. You may notice, that all [CSS animation properties](https://developer.mozilla.org/en/docs/Web/CSS/animation) are included, so you can look up which values are supported, where the options `delay` and `duration` have to be set as numbers in `ms` (e.g. `1000` for one second).  \n\nThe `animation-name` is currently not supported, as `type` is as set as class.\n\n```ts\nexport interface AnimationOptions {\n\n  // General settings:\n  disabled?: boolean;\n  fixed?: boolean;\n  reject?: boolean;\n  useVisibility?: boolean;\n  pin?: boolean;\n\n  // Animation type set as class:\n  type?: string;\n\n  // Animation settings:\n  fillMode?: string;\n  timingFunction?: string;\n  playState?: string;\n  direction?: string;\n  duration?: number;\n  delay?: number;\n  iterationCount?: number|string;\n\n}\n```\n\n\u003e The `delay` option is an exception and won't be set as CSS animation property,\n\u003e as delays are handled via JavaScript timeouts. If you really want to\n\u003e use the CSS rule, you can call `applyDelayAsStyle` to apply the delay immediately on the element.  \n\n### Change Options\n\nYou can change the options on an `AnimationBuilder` instance in three different ways.\nYou can also change the defaults for future instances.\n\n#### Change defaults for future instances\n\n```ts\nimport { AnimationBuilder } from 'css-animator/builder';\n\nAnimationBuilder.defaults.type = 'bounce';\nAnimationBuilder.defaults.duration = '1500';\n\nlet animator = new AnimationBuilder();\n```\n\nChanging the defaults won't affect instances, that have already been created.\n\n#### Using chainable set functions\n\n```ts\nanimator\n  .setType('bounce')\n  .setDuration(1500);\n```\n\n#### Using setters\n\n```ts\nanimator.type = 'bounce';\n\nif (animator.duration \u003c 1500) {\n  animator.duration = 1500;\n}\n```\n\n#### Using setOptions\n\n```ts\nanimator.setOptions({\n  type: 'bounce',\n  duration: 1500\n});\n```\n\n#### Apply an option\n\nYou can apply options, that are related to the animation itself.\nSupported options are: `fillMode`, `timingFunction`, `playState`,\n`direction`, `duration` and `iterationCount`.  \n\nSettings that are applied are immediately set on the element, without the need for starting an animation or saving them on the instance. css-animator can't take care of resetting the element though, so be careful with this feature.\n\n```ts\nanimator\n  .applyIterationCount(element, 3);\n```\n\nYou can also save a value and apply it afterwards:\n\n```ts\nanimator\n  .setIterationCount(3)\n  .applyIterationCount(element);\n```\n\n### Options\n\n#### disabled (default: false)\n\nSetting this option to `true` on an `AnimationBuilder` instance bypasses animations and shows or hides an element immediately, while skipping animations entirely. It is also possible to disable animations for all instances by changing the global value:\n\n```ts\nimport { AnimationBuilder } from 'css-animator/builder';\n\nAnimationBuilder.disabled = true;\n```\n\n#### fixed (default: false)\n\nAs mentioned above, elements being animated are positioned `absolute`. If you want to change\nthe position mode to `fixed`, set the fixed option to `true`.\n\n\u003e Setting this option to true results in a more accurate positioning, as `css-animator`\n\u003e won't round to the nearest full pixel (integer instead of float). But keep in mind,\n\u003e that you might experience unexpected behavior when scrolling while an element is being animated.\n\n#### reject (default: true)\n\nThe promise for an animation is rejected with `animation_aborted`, if it is interrupted somehow. To change\nthis behavior, set the `reject` option to `false`.\n\n#### useVisibility\n\n`AnimationBuilder` uses the `hidden` attribute on elements to hide them. If you want to use the `visibility` CSS rule,\nset `useVisibility` to `true`.\n\n#### pin (default: true)\n\nBy default, an element will be positioned `absolute` while animating, to enable concurrent animations.\nAlso the relative position (`top` and `left`) will be calculated and set on the element and the `margin` is set to `0px`.\nFurthermore the element's calculated `width` and `height` will be set explicitly.\nIf you want css-animator to only apply the animation, without changing the element's style temporarily, set `pin` to `false`.\n\n#### type (default: 'shake')\n\nThe class that will be applied to the element alongside `animated` and `animated-show`, if the element is being shown, or `animated-hide`, if the element is being hidden.\n\n#### fillMode (default: 'none')\n\nSee [CSS animation properties](https://developer.mozilla.org/en/docs/Web/CSS/animation).\n\n#### timingFunction (default: 'ease')\n\nSee [CSS animation properties](https://developer.mozilla.org/en/docs/Web/CSS/animation).\n\n#### playState (default: 'running')\n\nSee [CSS animation properties](https://developer.mozilla.org/en/docs/Web/CSS/animation).\n\n#### direction (default: 'normal')\n\nSee [CSS animation properties](https://developer.mozilla.org/en/docs/Web/CSS/animation).\n\n#### duration (default: 1000)\n\nSet the animation duration as integer in ms.\n\n#### delay (default: 0)\n\nSet a delay, before the animation should start as integer in ms.\n\n#### iterationCount (default: 1)\n\nSee [CSS animation properties](https://developer.mozilla.org/en/docs/Web/CSS/animation).\n\n## AnimationBuilder\n\n#### animate\n\n```ts\nanimate(element: HTMLElement, mode = AnimationMode.Animate): Promise\u003cHTMLElement\u003e\n```\n\nSimply animate an element.\n\n#### show\n\n```ts\nshow(element: HTMLElement): Promise\u003cHTMLElement\u003e\n```\n\nAnimate an element, that was previously hidden.  \n\nCalling `show` is equivalent to:\n\n```ts\nimport { AnimationMode } from 'css-animator/builder';\nanimator.animate(element, AnimationMode.Show);\n```\n\n#### hide\n\n```ts\nhide(element: HTMLElement): Promise\u003cHTMLElement\u003e\n```\n\nAdds the attribute `hidden` to the element after the animation has finished.\nYou may need to add something like `[hidden] { display: none; }` to your CSS.  \n\nAgain you can also use the `animate` function by passing `AnimationMode.Hide`.\n\n#### stop\n\n```ts\nstop(element: HTMLElement, reset = true): Promise\u003cHTMLElement\u003e\n```\n\n#### setOptions\n\nStop the current animation on an element, reset it's position, reject the promise and remove the event listener that listens for animation end.\n\n```ts\nsetOptions(options: AnimationOptions): AnimationBuilder\n```\n\nSet multiple options at once.\n\n#### set{Option}\n\n```ts\nset{Option}(option: string|number|boolean): AnimationBuilder\n```\n\nYou may set options individually like `setDuration(500)`\n\n#### addAnimationClass\n\n```ts\naddAnimationClass(name: string): AnimationBuilder\n```\n\nAdds your custom classes while animating alongside the classes `animated` `animated-{mode}` (where mode is `show`, `hide` or `default`, unless you pass another string to the `animate` method).\n\n#### removeAnimationClass\n\n```ts\nremoveAnimationClass(name: string): AnimationBuilder\n```\n\nWon't add classes for future animations, previously added with `addAnimationClass`.\n\n\u003e You can also directly apply options without saving it to the animation builder by using `apply{Option}(options: string|number)`  \n\u003e Also there are getters and setters for each option, you can access with `animator.{option}`.\n\n#### reset\n\n```ts\nreset(element: HTMLElement, removePending = true, rejectTimeouts = false, rejectListeners = false): void\n```\n\n#### dispose\n\n```ts\ndispose(): void\n```\n\nRemoves all elements, timeouts and listeners. Call if you don't want to use the builder anymore:\n\n```ts\nlet animator = new AnimationBuilder();\nanimator.dispose();\nanimator = null;\n```\n\n## AnimatesDirective\n\n#### start\n\n```ts\nstart(options?: AnimationOptions): Promise\u003cHTMLElement\u003e\n```\n\nAnimates the element.\n\n#### show\n\n```ts\nshow(options?: AnimationOptions): Promise\u003cHTMLElement\u003e\n```\n\nShows an element that was hidden.\n\n#### hide\n\n```ts\nhide(options?: AnimationOptions): Promise\u003cHTMLElement\u003e\n```\n\nHides an element by adding the attribute `hidden` to the element after the animation has finished.\nYou may need to add something like `[hidden] { display: none; }` to your CSS.\n\n#### stop\n\n```ts\nstop(): void\n```\n\nStops the current animation on an element, resets it's position, and removes the event listener that listens for animation end.\n\n#### startOrStop\n\n```ts\nstartOrStop(options?: AnimationOptions)\n```\n\nCalls `start` if the element was already started and stop otherwise.\n\n#### pause\n\n```ts\npause(): void\n```\n\nPauses the animation (sets the playState option to `paused`).\n\n#### resume\n\n```ts\nresume(): void\n```\n\nResumes a previously paused animation (sets the playState option to `running`).\n\n#### toggle\n\n```ts\ntoggle(): void\n```\n\nSwitches between `pause()` and `resume()`.\n\n# Build css-animator\n\n```sh\n$ git clone https://github.com/fabiandev/css-animator.git\n$ cd css-animator\n$ yarn \u0026\u0026 yarn build\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabiandev%2Fcss-animator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffabiandev%2Fcss-animator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabiandev%2Fcss-animator/lists"}