Angular Movement

Animate Angular with a single attribute.

Declarative, signals-native motion for Angular 21 and 22 — presets, variants, gestures, spring physics, drag, scroll-linked animation, layout transitions, presence orchestration, motion values & SVG path-drawing. SSR-safe, zoneless-ready. Zero @angular/animations.

🌐 Live Demo  ·  📚 Docs  ·  📦 npm  ·  🗺️ Roadmap

Why Angular Movement?

UI animation in Angular tends to sprawl: enter/leave transitions rewritten per component, imperative logic tangled into templates, inconsistent timings across a team, and no clean way to orchestrate staggered lists or exit animations.

Angular Movement replaces that boilerplate with declarative directives and one global config, so motion stays consistent, composable, and SSR-safe. Playback runs on the browser's native Web Animations API (with an optional spring physics engine) — no @angular/animations setup required.

<h2 [move]="'fade-up'">Hello movement</h2>
<button [moveWhileHover]="{ scale: [1, 1.05] }">Hover me</button>

✨ Features

🚀 Quick start

npm install angular-movement
# or: pnpm add angular-movement · yarn add angular-movement

Peer dependencies: @angular/core and @angular/common — ^21.2.0 || ^22.0.0. Every supported major is compiled against the packed package in CI (pnpm validate:consumer).

1. Provide global defaults (optional)

import { ApplicationConfig } from '@angular/core';
import { provideMovement } from 'angular-movement';

export const appConfig: ApplicationConfig = {
  providers: [
    provideMovement({
      duration: '320ms', // or 320 — numbers are milliseconds
      easing: 'cubic-bezier(0.16, 1, 0.3, 1)',
    }),
  ],
};

prefers-reduced-motion is honoured automatically — there is nothing to configure for it. disabled is an app-level kill switch (a user setting, screenshot tests), not the reduced-motion mechanism, and SSR needs nothing either: every directive is a no-op on the server.

2. Import only the directives you use

Standalone components tree-shake per route, but only if you import what you actually use — a directive that's never imported anywhere never ships.

import { Component } from '@angular/core';
import { MoveAnimateDirective, MoveHoverDirective, MoveTapDirective } from 'angular-movement';

@Component({
  selector: 'app-demo-card',
  imports: [MoveAnimateDirective, MoveHoverDirective, MoveTapDirective],
  template: `
    <h2 move="fade-up">Hello movement</h2>
    <button moveWhileHover="lift" moveWhileTap="press">Hover or press me</button>
  `,
})
export class DemoCardComponent {}

MOVEMENT_DIRECTIVES (all 21, spread into imports) is still exported as a convenience for prototyping or a component that genuinely uses most of the library — just know it pulls in everything, including directives that component doesn't use and every experimental one (moveLayout, moveDrag, moveSmoothScroll, moveTarget, moveTrigger). If you want a spread that can never silently start pulling in an experimental directive, use MOVEMENT_STABLE_DIRECTIVES instead (there's also a standalone MOVEMENT_EXPERIMENTAL_DIRECTIVES for the other five).

🧩 Pick the right primitive

Start with the smallest primitive that matches the job:

moveLeave plays only while a parent movePresence keeps the view alive during removal. A plain @if removes the element immediately, so there is no node left to animate.

Several of these look interchangeable at first glance. They're not — each covers a distinct job:

• [move] / moveAnimate vs [moveAnimation]. Both describe a single element's own enter/leave. [move]/moveAnimate take a preset name or MoveKeyframes pairs ({ opacity: [0, 1] }); [moveAnimation] takes Framer-style single-value state objects ({ initial, animate, exit }) and is reactive to animate changing. Reach for [moveAnimation] when you're already thinking in initial/animate/exit state, otherwise [move] is the simpler default.
• moveVariants vs moveTarget/moveTrigger. moveVariants propagates a named state down through DI to nested [moveVariants] children — the tool for a shared state (idle, open, active) driving a subtree, with staggerChildren/delayChildren/when orchestration. moveTarget/moveTrigger (experimental) instead connect two elements that do not share a parent — a boolean signal flips an animation on a target elsewhere in the DOM, with no DI propagation. Prefer moveVariants whenever the elements involved share an ancestor.
• moveStagger vs staggerChildren. [moveStagger] delays its direct animated children in DOM order — the tool for a flat list. staggerChildren (a moveVariants state property) staggers nested [moveVariants] subtrees on a variant change — the tool when the staggered items are themselves stateful, not just entering once.

🎛️ Explore the interactive playground

Every directive has a focused page with a live config panel and copy-paste HTML output.

Demo pages: Animate · Animation (object API) · Enter & Leave · Hover & Tap · Focus · In-View · Scroll & Parallax · Presence · Layout · Drag · Variants · Text · SVG Icons

🧭 Common patterns

The shapes real apps use most — full explanations on the patterns page.

<!-- Product card: reveal in view, lift on hover -->
<article moveInView="fade-up" moveWhileHover="lift">…</article>

<!-- Button or link: lift (translate) + press (scale) compose on one element.
     Hover is mouse/pen only; touch gets moveWhileTap. Taps and scrolling stay native. -->
<a routerLink="/pricing" moveWhileHover="lift" moveWhileTap="press">Pricing</a>

<!-- Staggered grid: numbers are ms; strings say their unit -->
<ul moveStagger moveStaggerStep="80ms">
  @for (item of items(); track item.id) {
  <li moveInView="fade-up">{{ item.label }}</li>
  }
</ul>

// Imperative: MoveAnimator takes an Element or the ElementRef from viewChild()
const animator = inject(MoveAnimator);
await animator.animate(this.panel(), { opacity: [0, 1], y: [12, 0] }, { duration: '240ms' })
  ?.finished;
animator.set(this.panel(), { opacity: 1 }); // commit a state instantly; clear() removes it

// View Transition: animate the pseudo-element through the same API
animator.animate(
  document.documentElement,
  { clipPath: ['circle(0px at 40px 40px)', 'circle(1500px at 40px 40px)'] },
  { duration: '520ms', pseudoElement: '::view-transition-new(root)' },
);

• Timing: every duration/delay/stagger takes 80, "80ms" or "0.08s". A bound 0.08 is 0.08 milliseconds — dev mode warns and suggests "80ms" / "0.08s".
• Reduced motion: OS preference (automatic) → provideMovement({ disabled }) (app kill switch) → moveDisabled (one element).
• Cancellation: finished and moveTrigger.play() always resolve, never reject — no try/catch around await.
• Any CSS property passes through: { clipPath: [...] }, { filter: [...] }, { borderRadius: [...] }.
• First paint: an above-the-fold entrance that must move before hydration belongs in CSS; the library takes over once the app runs.

📖 Recipes

<ng-container *movePresence="isOpen">
  <article
    [moveInitial]="{ opacity: 0, y: 24 }"
    [moveAnimate]="{ opacity: 1, y: 0 }"
    [moveExit]="{ opacity: 0, y: -16 }"
    moveDuration="300ms"
  >
    Card
  </article>
</ng-container>

<div
  moveDrag="x"
  [moveDragConstraints]="{ left: -120, right: 120 }"
  [moveDragElastic]="0.35"
  [moveDragMomentum]="true"
  [moveDragSnapPoints]="[{ x: -120, y: 0 }, { x: 0, y: 0 }, { x: 120, y: 0 }]"
  (moveDragStart)="onDragStart($event)"
  (moveDragMove)="onDragMove($event)"
  (moveDragEnd)="onDragEnd($event)"
>
  Drag me
</div>

<svg width="24" height="24" viewBox="0 0 24 24">
  <path
    [moveTarget]="animate()"
    [moveFrames]="{ pathLength: [0, 1], opacity: [0, 1] }"
    moveDuration="700ms"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    d="M4 12l4-4 4 4 8-8"
  />
</svg>

import { movePathDraw, moveIconPulse } from 'angular-movement';

<svg [moveTarget]="animate()" movePreset="icon-bounce" moveDuration="500ms">
  <!-- icon paths -->
</svg>

<div
  [moveVariants]="{
    idle: { scale: 1, rotate: 0 },
    active: { scale: 1.08, rotate: 4 }
  }"
  [moveVariant]="isActive ? 'active' : 'idle'"
>
  Card
</div>

<ng-container *movePresence="isOpen">
  <aside
    [moveVariants]="{
      visible: { opacity: 1, x: 0 },
      hidden: { opacity: 0, x: 24 }
    }"
    moveVariant="visible"
    moveExitVariant="hidden"
  >
    Panel
  </aside>
</ng-container>

import { Component, computed } from '@angular/core';
import { moveSpringValue, moveTransform, moveValue } from 'angular-movement';

@Component({ selector: 'app-card', template: `...` })
class CardComponent {
  progress = moveValue(0);
  x = moveTransform(this.progress, [0, 1], [0, 120]);
  scale = moveSpringValue(moveTransform(this.progress, [0, 1], [0.9, 1]));
  transform = computed(() => `translateX(${this.x()}px) scale(${this.scale()})`);
}

import { inject, Injector } from '@angular/core';
import { moveSpringValue } from 'angular-movement';

function buildScale(source: Signal<number>, injector: Injector) {
  return moveSpringValue(source, { injector });
}

<section
  #scroll="moveScroll"
  [moveScroll]="{ opacity: [0, 1] }"
  [style.--progress]="scroll.progress()"
>
  Scroll-linked content
</section>

🧪 API stability

MOVEMENT_DIRECTIVES itself is stable — spreading it always compiles and its own shape follows SemVer — but its contents are not stability-pure: it includes all five experimental directives above. Use MOVEMENT_STABLE_DIRECTIVES instead if you want a spread that can never silently start pulling in an experimental directive, or MOVEMENT_EXPERIMENTAL_DIRECTIVES for just those five.

Stable APIs follow semantic-versioning expectations. Candidate APIs are feature-complete but may receive small naming or behavior adjustments. Experimental APIs can change significantly between minor versions — see the versioning policy below for exactly what that means going into 1.x.

Every exported type mirrors the stability of the API it supports — MoveKeyframes is stable because the directives that take it are stable, MoveDragEvent is experimental because moveDrag is. AnimationControls (the return type shared by MoveAnimator and every directive internally) and the MovementConfig family (behind provideMovement) are stable on their own: their shape hasn't changed since 0.5 and both are load-bearing for everything else. moveActiveVariant is @deprecated in favor of moveVariant (same value, one name) but stays a permanent, fully-supported alias — it will not be removed without a major version.

Each level is also declared in the source as a @stability JSDoc tag (stable / candidate / experimental), so your editor shows the guarantee at the point of use — check the tag on the specific declaration you're using for the authoritative answer. Experimental declarations additionally carry the standard @experimental tag.

Experimental compatibility policy (going into 1.x)

There is no secondary angular-movement/experimental entry point — every experimental export ships from the same package. This is the one deliberate exception to normal SemVer:

• Experimental exports may change or be removed in any 1.x minor, including breaking changes to inputs, outputs, or behavior — the same convention Angular CDK uses for its own experimental APIs.
• Every experimental-only breaking change is called out under its own ### Changed (experimental) CHANGELOG heading, separate from the normal ### Changed, so you can safely ignore it if you don't use experimental APIs.
• Where practical, an experimental API gets a deprecation warning (dev-mode console warning or @deprecated tag) for at least one minor version before removal.

If you only use [move], moveVariants, *movePresenceFor, moveScroll, and the rest of the Stable row above, normal SemVer applies to your app without exception.

This "no secondary entry point" decision was reaffirmed in the post-1.0 hardening pass (spec 013): the experimental surface still needs no dependency stable consumers shouldn't pay for, so splitting the package would be migration churn with no architectural win. It remains open for a future minor if a concrete reason appears.

🔄 Input reactivity

Two deliberate groups, frozen for 1.0:

• Reactive — changing an input while the directive is alive updates or replays the animation: moveWhileHover, moveWhileTap, moveWhileFocus, moveVariants, moveTarget, moveTrigger, moveScroll, moveParallax, moveDrag, moveLoop, moveText, and [moveAnimation]'s animate state.
• One-shot by design — these describe a single entrance or exit, so they play once and ignore later input changes: moveAnimate / [move], moveEnter, moveLeave, moveInView, moveSmoothScroll. To play one again, wrap the element in *movePresence / *movePresenceFor or re-create the view.

[moveAnimation] compares its animate state by value, so binding an object literal straight in the template does not replay the animation on every change detection pass.

🏗️ Repository structure

This is a pnpm monorepo with two parts:

The demo site imports the library via a Vite path alias, so library changes are reflected live without a build step.

pnpm dev            # run the demo site
pnpm test           # library unit tests (Vitest)
ng build movement   # build the library → dist/movement
pnpm build          # build the demo site (client + SSR)

🚢 Deployment

The demo site deploys to Cloudflare Pages — a single source of truth for hosting.

• Automatic: every push to main runs .github/workflows/deploy-cloudflare.yml.
• Manual: pnpm deploy builds and ships dist/analog/public via Wrangler.

Live at angular-movement.andersseen.dev.

🤝 Contributing

Contributions are welcome through issues and pull requests. When proposing changes, include a problem statement, any public-API impact, and tests or demo updates for new behavior.

• 📋 Contributing guide
• 🤝 Code of conduct
• 🔒 Security policy
• 🗺️ Roadmap
• ✅ Release checklist

📄 License

MIT © Andersseen