@angular/animations

The animations DSL and runtime. @angular/animations defines the metadata authored on components (trigger, state, transition, animate, keyframes); @angular/animations/browser wires that metadata up to a renderer that actually mutates the DOM and the Web Animations API.

Purpose

• Provide the declarative animation DSL: trigger(), state(), style(), transition(), animate(), keyframes(), query(), stagger(), sequence(), group().
• Provide the matching runtime that listens for state-driven trigger changes, schedules animations, and respects the disable/enable infrastructure.
• Provide provideAnimations() and provideAnimationsAsync() to set up the runtime, plus provideNoopAnimations() for environments where animations are disabled (tests, SSR-by-default).

Directory layout

packages/animations/
├── src/
│   ├── animation_metadata.ts   # AST nodes for the DSL
│   ├── triggers/                # trigger(), state(), transition()
│   ├── players/                 # AnimationPlayer impls
│   └── ...
├── browser/
│   └── src/
│       ├── render/              # AnimationRenderer (the Renderer2 wrapper)
│       ├── dsl/                 # CSS keyframe / Web Animations bridge
│       ├── timeline_animation_engine.ts
│       └── ...
└── public_api.ts

browser/ is the runtime; the top-level package is mostly metadata definitions consumed at compile time.

Key abstractions

Type / function	File	What it is
trigger()	packages/animations/src/animation_metadata.ts	DSL builder that produces AnimationTriggerMetadata.
state(), style(), transition(), animate()	same	The other DSL functions.
AnimationBuilder	packages/animations/src/animation_builder.ts	Service that builds an AnimationFactory from metadata.
provideAnimations, provideAnimationsAsync, provideNoopAnimations	packages/platform-browser/src/animations/	The standalone-providers entry. (Lives in platform-browser because it wires DOM renderers.)
AnimationRendererFactory	packages/animations/browser/src/render/animation_renderer.ts	A RendererFactory2 that wraps the DOM renderer and adds animation hooks.
TimelineAnimationEngine	packages/animations/browser/src/timeline_animation_engine.ts	Schedules and reconciles concurrent animations.

Async vs sync providers

provideAnimationsAsync() lazy-loads the runtime; provideAnimations() includes it eagerly. Async is preferred for new apps so the animation runtime ships only when an animation actually fires.

Integration points

• @angular/platform-browser — owns the provider factories. The animation runtime substitutes its RendererFactory2 for the default DOM one.
• @angular/core — exposes the lifecycle hooks the animation runtime listens for.
• CSS-first patterns — the recent direction is to prefer CSS transitions and the Web Animations API directly when possible. The DSL still has its place for state-machine animations.

Migrations

packages/animations/schematics/ ships the migration that replaces eager provideAnimations() with provideAnimationsAsync() where safe.

Entry points for modification

• A new DSL function: add metadata constructors in animation_metadata.ts and the matching runtime AST visitor in browser/src/dsl/.
• A new player type: extend packages/animations/src/players/ and register it in the engine.
• A renderer-level integration: most extension points are in packages/animations/browser/src/render/.