GitHub - angular-threejs/ngx-spring: @react-spring/core port

ngx-spring

Spring-physics based animations for Angular, inspired by react-spring.

Create fluid, natural-feeling animations using spring physics instead of durations and easing curves. Integrates seamlessly with Angular's signal-based reactivity.

Features

Spring Physics: Natural, physics-based animations that feel alive
Signal Reactive: Automatically animates when your signals change
Transform Shortcuts: Use x, y, scale, rotate instead of verbose CSS
SSR Safe: Only runs animations in the browser
TypeScript First: Full type safety with inferred types
Lightweight: Built on top of @react-spring/rafz for efficient frame scheduling

Requirements

Angular 21+ (@angular/core and @angular/common)

Installation

Quick Start

import { Component, signal } from '@angular/core';
import { spring, Spring } from 'ngx-spring/dom';

@Component({
  selector: 'app-animated-box',
  standalone: true,
  imports: [Spring],
  template: `
    <div [spring]="springValues" class="box">
      Hover me!
    </div>
  `,
  host: {
    '(mouseenter)': 'isHovered.set(true)',
    '(mouseleave)': 'isHovered.set(false)',
  },
})
export class AnimatedBoxComponent {
  isHovered = signal(false);

  // Spring automatically animates when isHovered changes
  springValues = spring({
    scale: () => this.isHovered() ? 1.1 : 1,
    rotate: () => this.isHovered() ? 5 : 0,
  });
}

API Overview

`spring()` Function

Creates reactive spring animations. Accepts getter functions that are tracked for signal changes.

import { spring, config } from 'ngx-spring/dom';

// Basic usage
springValues = spring({
  opacity: () => this.isVisible() ? 1 : 0,
  x: () => this.position().x,
});

// With custom spring physics
springValues = spring({
  y: () => this.isOpen() ? 0 : -100,
}, {
  config: config.wobbly,  // Bouncy animation
});

// From/to style
springValues = spring({
  from: { opacity: () => 0 },
  to: { opacity: () => this.isVisible() ? 1 : 0 },
});

`Spring` Directive

Applies spring animations to DOM elements.

<!-- Basic usage -->
<div [spring]="springValues">Animated content</div>

<!-- Custom target element -->
<div [spring]="springValues" [springHost]="targetRef">
  <div #targetRef>This element gets animated</div>
</div>

Transform Shortcuts

Use convenient shortcuts instead of writing CSS transforms:

Shortcut	CSS Transform
`x`, `y`, `z`	`translate()` / `translate3d()`
`scale`, `scaleX`, `scaleY`	`scale()` / `scaleX()` / `scaleY()`
`rotate`, `rotateX`, `rotateY`, `rotateZ`	`rotate()` / `rotateX()` / etc.
`skew`, `skewX`, `skewY`	`skew()` / `skewX()` / `skewY()`

Spring Presets

Built-in spring configurations:

import { config } from 'ngx-spring';

config.default   // tension: 170, friction: 26
config.gentle    // tension: 120, friction: 14
config.wobbly    // tension: 180, friction: 12
config.stiff     // tension: 210, friction: 20
config.slow      // tension: 280, friction: 60
config.molasses  // tension: 280, friction: 120

Package Structure

ngx-spring - Core animation primitives (SpringValue, config, easings)
ngx-spring/dom - DOM-specific utilities (spring(), Spring directive)

Credits

Inspired by react-spring - A spring-physics first animation library.

License

MIT - Chau Tran