# @visactor/vrender-animate

> This module provides a graph-based animation system for VRender.

Latest version **1.1.12** (published 2026-10-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install @visactor/vrender-animate
pnpm add @visactor/vrender-animate
yarn add @visactor/vrender-animate
bun add @visactor/vrender-animate
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.1.12 |
| Published | 2026-10-13 |
| First published | 2025-03-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 3.3 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 264 |
| Author | VisActor |
| Maintainers | liufangfang, visactorowner, xuanhun, zamhown, chensiji.0517, youngwinds, purpose233, ssfxz, lixuefei.1313, ray_sun, xiaoluohe, simaq, xile611, da730, zhouxinyu66888, zexian_chen |
| Keywords | VisActor, graphics, renderer, vrender, vrender-kits |

## Links

- npm: https://www.npmjs.com/package/@visactor/vrender-animate
- Repository: https://github.com/VisActor/VRender
- Homepage: https://github.com/VisActor/VRender#readme
- Issues: https://github.com/VisActor/VRender/issues
- npm.io page: https://npm.io/package/@visactor/vrender-animate

## Dependencies (2)

- [@visactor/vutils](https://npm.io/package/@visactor/vutils.md) ~1.0.12
- [@visactor/vrender-core](https://npm.io/package/@visactor/vrender-core.md) 1.1.12

## Alternatives

- [d3-force-3d](https://npm.io/package/d3-force-3d.md) — 1.0M weekly downloads
- [ng2-charts](https://npm.io/package/ng2-charts.md) — 486.8K weekly downloads
- [@arcgis/core](https://npm.io/package/@arcgis/core.md) — 257.8K weekly downloads
- [react-sparklines](https://npm.io/package/react-sparklines.md) — 249.3K weekly downloads
- [react-native-gifted-charts](https://npm.io/package/react-native-gifted-charts.md) — 182.3K weekly downloads

## Recent versions

- 1.1.12 (latest) — 2026-10-13
- 1.1.11-alpha.1 (alpha) — 2026-09-17
- 1.1.11 — 2026-09-17
- 1.1.11-alpha.0 — 2026-09-16
- 1.1.10 — 2026-08-29
- 1.1.10-alpha.0 — 2026-08-28
- 1.1.9 — 2026-08-28
- 1.1.9-alpha.1 — 2026-08-28
- 1.1.9-alpha.0 — 2026-08-27
- 1.0.46-alpha.3 — 2026-08-20
- 1.1.8 — 2026-08-12
- 1.1.8-alpha.2 — 2026-08-07
- 1.1.8-alpha.1 — 2026-08-07
- 1.1.8-alpha.0 — 2026-08-03
- 1.1.7 — 2026-08-02
- … 168 more at https://npm.io/package/@visactor/vrender-animate/versions

## README

# VRender Animation Module

This module provides a graph-based animation system for VRender.

## Features

- Graph-based animation system
- Support for simple property animations
- Support for sequence and parallel animations
- Support for composite animations
- Support for custom animations
- Support for path animations
- Compatible with the legacy animation system
- Advanced composition capabilities for nested animations
- Proper propagation of animation events in complex choreography

## Recent Updates

- **Improved Animation Node Composition**: Fixed issues with propagation in `GraphAdapterNode` to ensure proper animation sequencing
- **Enhanced Duration Calculation**: Better handling of duration for sequence and parallel animations
- **Better Event Handling**: Improved monitoring of animation completion and successor activation

## Usage

### Runtime Registration

```typescript
import { registerAnimate } from '@visactor/vrender-animate/register';
import { registerBasicCustomAnimate } from '@visactor/vrender-animate/custom/register-basic';

registerAnimate();
registerBasicCustomAnimate();
```

`registerAnimate()` installs the base graphic animation runtime. Use
`@visactor/vrender-animate/custom/register-basic` when only the common built-in
custom animations are needed. Full bootstraps that need the whole story, rich
text, poptip, motion path, and disappearance effect set should continue to use
`@visactor/vrender-animate/custom/register`.
Use `@visactor/vrender-animate/custom/register-disappear` when only the
disappearance effect animations are needed.
Use `@visactor/vrender-animate/custom/register-richtext` when only text and
rich text input/output animations are needed.
Use `@visactor/vrender-animate/custom/register-story` when only story effects,
motion path, and stream light animations are needed.

Current custom register entries:

| Entry | Function | Scope |
| --- | --- | --- |
| `@visactor/vrender-animate/register` | `registerAnimate()` | Base animation runtime only |
| `@visactor/vrender-animate/custom/register-basic` | `registerBasicCustomAnimate()` | Common built-in custom animations |
| `@visactor/vrender-animate/custom/register-richtext` | `registerRichTextCustomAnimate()` | Text and rich text custom animations |
| `@visactor/vrender-animate/custom/register-disappear` | `registerDisappearCustomAnimate()` | Disappearance effect animations |
| `@visactor/vrender-animate/custom/register-story` | `registerStoryCustomAnimate()` | Story effects, `MotionPath`, and `streamLight` |
| `@visactor/vrender-animate/custom/register` | `registerCustomAnimate()` | Full custom animation compatibility |

### Basic Property Animation

```typescript
import { createAnimationNode, createGraphManager } from '@visactor/vrender-animate';

// Create a simple animation node
const moveNode = createAnimationNode({
  id: 'move',
  target: myRect,
  propertyName: 'x',
  toValue: 200,
  duration: 1000
});

// Create a graph manager
const graphManager = createGraphManager(moveNode, stage);

// Start the animation
graphManager.start();
```

### Sequence Animation

```typescript
import { createAnimationNode, createSequence, createGraphManager } from '@visactor/vrender-animate';

// Create animation nodes
const moveNode = createAnimationNode({
  id: 'move',
  target: myRect,
  propertyName: 'x',
  toValue: 200,
  duration: 1000
});

const colorNode = createAnimationNode({
  id: 'color',
  target: myRect,
  propertyName: 'fill',
  toValue: 'blue',
  duration: 1000
});

// Create a sequence
const sequence = createSequence([moveNode, colorNode]);

// Create a graph manager
const graphManager = createGraphManager(sequence, stage);

// Start the animation
graphManager.start();
```

### Nested Animations (Advanced Composition)

The animation system supports nesting of animations, allowing complex choreography:

```typescript
import { createAnimationNode, createSequence, createParallel, createGraphManager } from '@visactor/vrender-animate';

// Create simple animations for rectangle 1
const moveRect1 = createAnimationNode({
  target: rect1,
  propertyName: 'x',
  toValue: 500,
  duration: 2000
});

const colorRect1 = createAnimationNode({
  target: rect1,
  propertyName: 'fill',
  toValue: 'red',
  duration: 1000
});

// Create simple animations for rectangle 2
const moveRect2 = createAnimationNode({
  target: rect2,
  propertyName: 'y',
  toValue: 300,
  duration: 1500
});

const colorRect2 = createAnimationNode({
  target: rect2,
  propertyName: 'fill',
  toValue: 'blue',
  duration: 800
});

// Create sequences for each rectangle
const sequence1 = createSequence([moveRect1, colorRect1]);
const sequence2 = createSequence([moveRect2, colorRect2]);

// Run both sequences in parallel
const parallelAnimation = createParallel([sequence1, sequence2]);

// Create additional animations
const finalAnimation = createAnimationNode({
  target: rect3,
  propertyName: 'opacity',
  toValue: 0,
  duration: 1000
});

// Create a final sequence that runs the parallel animations and then the final animation
const fullAnimation = createSequence([parallelAnimation, finalAnimation]);

// Create graph manager and start the animation
const graphManager = createGraphManager(fullAnimation, stage);
graphManager.start();
```

### Cleanup Completed Animations

The animation system includes a mechanism to clean up completed animations to free memory and resources:

```typescript
import { createAnimationNode, createSequence, createGraphManager } from '@visactor/vrender-animate';

// Create animation nodes (as shown in previous examples)
// ...

// Create a graph manager
const graphManager = createGraphManager(myAnimationGraph, stage);

// Start the animation
graphManager.start();

// Later, when animations have completed, you can clean up:
graphManager.onAllComplete = () => {
  console.log('All animations completed');

  // Remove completed animation nodes
  const removed = graphManager.cleanupCompletedNodes();
  console.log(`Cleaned up ${removed} completed nodes`);
};

// You can also manually trigger cleanup at any time:
function handleCleanupButtonClick() {
  const removed = graphManager.cleanupCompletedNodes();
  console.log(`Cleaned up ${removed} completed nodes`);
}

// By default, the cleanup is performed in "safe mode", which only removes nodes
// that have no successors or whose successors have also completed.
// To forcibly remove all completed nodes:
graphManager.cleanupCompletedNodes(false);
```

## API

See the API documentation for more details.

---
_Source: https://npm.io/package/@visactor/vrender-animate · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._