# pmndrs/react-spring architecture

> Architecture diagram of the GitHub repository pmndrs/react-spring, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pmndrs/react-spring
- Repository: https://github.com/pmndrs/react-spring

## Overview

react-spring is a cross-platform, spring-physics-first animation library. A typical workflow starts when an application configures an animation with a hook, the hook creates or updates controllers, and spring values schedule and advance animation state; animated host components then apply values to rendered elements. The README also documents imperative control and duration/easing animations. The graph includes transition/presence, platform targets, parallax, and shared timing support; some subsystem links are omitted where sampled evidence does not establish the runtime connection.

Main entry points: [`packages/core/src/SpringValue.ts`](https://github.com/pmndrs/react-spring/blob/next/packages/core/src/SpringValue.ts) (Spring Values), [`packages/core/src/Controller.ts`](https://github.com/pmndrs/react-spring/blob/next/packages/core/src/Controller.ts) (Controller), [`packages/core/src/hooks/useSprings.ts`](https://github.com/pmndrs/react-spring/blob/next/packages/core/src/hooks/useSprings.ts) (Spring Collections), [`packages/animated/src/createHost.ts`](https://github.com/pmndrs/react-spring/blob/next/packages/animated/src/createHost.ts) (Animated Host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Animation APIs"]
  node_hooks["Spring Hooks<br/>[useSpring.ts]"]
  node_multi_hooks["Spring Collections<br/>[useSprings.ts]"]
  node_transition["Transitions<br/>[useTransition.tsx]"]
  node_presence["Presence Lists<br/>[usePresence.ts]"]
  node_components["Spring Components"]
end

subgraph group_engine["Animation Engine"]
  node_controller["Controller<br/>[Controller.ts]"]
  node_spring["Spring Values<br/>[SpringValue.ts]"]
  node_frame_value["Frame Values<br/>[FrameValue.ts]"]
  node_async["Async Updates<br/>[runAsync.ts]"]
  node_scheduler["Prop Scheduling<br/>[scheduleProps.ts]"]
  node_spring_ref["Imperative Refs<br/>[SpringRef.ts]"]
end

subgraph group_render["Animated Rendering"]
  node_animated_values["Animated Values<br/>[AnimatedObject.ts]"]
  node_animated_host["Animated Host<br/>[createHost.ts]"]
end

subgraph group_platforms["Platform Targets"]
  node_web["Web Target<br/>[animated.ts]"]
  node_three["Three Target<br/>[animated.ts]"]
  node_parallax["Parallax<br/>[index.tsx]"]
end

subgraph group_support["Shared Utilities"]
  node_frame_loop["Frame Loop<br/>[FrameLoop.ts]"]
  node_rafz["Frame Scheduler<br/>[index.ts]"]
  node_shared["Shared Helpers<br/>[helpers.ts]"]
end

node_app(("Application"))

node_app -->|"configures"| node_hooks
node_hooks -->|"delegates to"| node_multi_hooks
node_multi_hooks -->|"updates"| node_controller
node_multi_hooks -->|"creates values"| node_spring
node_transition -->|"updates"| node_controller
node_presence -->|"creates controllers"| node_controller
node_controller -->|"manages"| node_spring
node_controller -->|"runs sequences"| node_async
node_spring -->|"schedules props"| node_scheduler
node_spring -->|"runs async goals"| node_async
node_spring -->|"extends"| node_frame_value
node_spring -->|"reads animated node"| node_animated_values
node_spring_ref -->|"controls"| node_controller
node_animated_host -->|"observes"| node_animated_values
node_web -->|"creates host"| node_animated_host
node_three -.->|"creates host"| node_animated_host
node_parallax -->|"uses helpers"| node_shared
node_spring -->|"advances values"| node_frame_loop
node_app -.->|"controls imperatively"| node_spring_ref

click node_hooks "https://github.com/pmndrs/react-spring/blob/next/packages/core/src/hooks/useSpring.ts"
click node_multi_hooks "https://github.com/pmndrs/react-spring/blob/next/packages/core/src/hooks/useSprings.ts"
click node_transition "https://github.com/pmndrs/react-spring/blob/next/packages/core/src/hooks/useTransition.tsx"
click node_presence "https://github.com/pmndrs/react-spring/blob/next/packages/core/src/hooks/usePresence.ts"
click node_components "https://github.com/pmndrs/react-spring/tree/next/packages/core/src/components"
click node_controller "https://github.com/pmndrs/react-spring/blob/next/packages/core/src/Controller.ts"
click node_spring "https://github.com/pmndrs/react-spring/blob/next/packages/core/src/SpringValue.ts"
click node_frame_value "https://github.com/pmndrs/react-spring/blob/next/packages/core/src/FrameValue.ts"
click node_async "https://github.com/pmndrs/react-spring/blob/next/packages/core/src/runAsync.ts"
click node_scheduler "https://github.com/pmndrs/react-spring/blob/next/packages/core/src/scheduleProps.ts"
click node_spring_ref "https://github.com/pmndrs/react-spring/blob/next/packages/core/src/SpringRef.ts"
click node_animated_values "https://github.com/pmndrs/react-spring/blob/next/packages/animated/src/AnimatedObject.ts"
click node_animated_host "https://github.com/pmndrs/react-spring/blob/next/packages/animated/src/createHost.ts"
click node_web "https://github.com/pmndrs/react-spring/blob/next/targets/web/src/animated.ts"
click node_three "https://github.com/pmndrs/react-spring/blob/next/targets/three/src/animated.ts"
click node_parallax "https://github.com/pmndrs/react-spring/blob/next/packages/parallax/src/index.tsx"
click node_frame_loop "https://github.com/pmndrs/react-spring/blob/next/packages/shared/src/FrameLoop.ts"
click node_rafz "https://github.com/pmndrs/react-spring/blob/next/packages/rafz/src/index.ts"
click node_shared "https://github.com/pmndrs/react-spring/blob/next/packages/shared/src/helpers.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hooks,node_multi_hooks,node_transition,node_presence,node_components toneBlue
class node_controller,node_spring,node_frame_value,node_async,node_scheduler,node_spring_ref toneAmber
class node_animated_values,node_animated_host toneMint
class node_web,node_three,node_parallax toneRose
class node_frame_loop,node_rafz,node_shared,node_app toneIndigo
```

## Components

### Animation APIs

- [Spring Hooks](https://github.com/pmndrs/react-spring/blob/next/packages/core/src/hooks/useSpring.ts): `packages/core/src/hooks/useSpring.ts`
- [Spring Collections](https://github.com/pmndrs/react-spring/blob/next/packages/core/src/hooks/useSprings.ts): `packages/core/src/hooks/useSprings.ts`
- [Transitions](https://github.com/pmndrs/react-spring/blob/next/packages/core/src/hooks/useTransition.tsx): `packages/core/src/hooks/useTransition.tsx`
- [Presence Lists](https://github.com/pmndrs/react-spring/blob/next/packages/core/src/hooks/usePresence.ts): `packages/core/src/hooks/usePresence.ts`
- [Spring Components](https://github.com/pmndrs/react-spring/tree/next/packages/core/src/components): `packages/core/src/components`

### Animation Engine

- [Controller](https://github.com/pmndrs/react-spring/blob/next/packages/core/src/Controller.ts): `packages/core/src/Controller.ts`
- [Spring Values](https://github.com/pmndrs/react-spring/blob/next/packages/core/src/SpringValue.ts): `packages/core/src/SpringValue.ts`
- [Frame Values](https://github.com/pmndrs/react-spring/blob/next/packages/core/src/FrameValue.ts): `packages/core/src/FrameValue.ts`
- [Async Updates](https://github.com/pmndrs/react-spring/blob/next/packages/core/src/runAsync.ts): `packages/core/src/runAsync.ts`
- [Prop Scheduling](https://github.com/pmndrs/react-spring/blob/next/packages/core/src/scheduleProps.ts): `packages/core/src/scheduleProps.ts`
- [Imperative Refs](https://github.com/pmndrs/react-spring/blob/next/packages/core/src/SpringRef.ts): `packages/core/src/SpringRef.ts`

### Animated Rendering

- [Animated Values](https://github.com/pmndrs/react-spring/blob/next/packages/animated/src/AnimatedObject.ts): `packages/animated/src/AnimatedObject.ts`
- [Animated Host](https://github.com/pmndrs/react-spring/blob/next/packages/animated/src/createHost.ts): `packages/animated/src/createHost.ts`

### Platform Targets

- [Web Target](https://github.com/pmndrs/react-spring/blob/next/targets/web/src/animated.ts): `targets/web/src/animated.ts`
- [Three Target](https://github.com/pmndrs/react-spring/blob/next/targets/three/src/animated.ts): `targets/three/src/animated.ts`
- [Parallax](https://github.com/pmndrs/react-spring/blob/next/packages/parallax/src/index.tsx): `packages/parallax/src/index.tsx`

### Shared Utilities

- [Frame Loop](https://github.com/pmndrs/react-spring/blob/next/packages/shared/src/FrameLoop.ts): `packages/shared/src/FrameLoop.ts`
- [Frame Scheduler](https://github.com/pmndrs/react-spring/blob/next/packages/rafz/src/index.ts): `packages/rafz/src/index.ts`
- [Shared Helpers](https://github.com/pmndrs/react-spring/blob/next/packages/shared/src/helpers.ts): `packages/shared/src/helpers.ts`

### Other components

- **Application**

## Connections

- Application → Spring Hooks: configures (evidence: `README.md`)
- Spring Hooks → Spring Collections: delegates to (evidence: `packages/core/src/hooks/useSpring.ts`)
- Spring Collections → Controller: updates (evidence: `packages/core/src/hooks/useSprings.ts`)
- Spring Collections → Spring Values: creates values (evidence: `packages/core/src/hooks/useSprings.ts`)
- Transitions → Controller: updates (evidence: `packages/core/src/hooks/useTransition.tsx`)
- Presence Lists → Controller: creates controllers (evidence: `packages/core/src/hooks/usePresence.ts`)
- Controller → Spring Values: manages (evidence: `packages/core/src/Controller.ts`)
- Controller → Async Updates: runs sequences (evidence: `packages/core/src/Controller.ts`)
- Spring Values → Prop Scheduling: schedules props (evidence: `packages/core/src/SpringValue.ts`)
- Spring Values → Async Updates: runs async goals (evidence: `packages/core/src/SpringValue.ts`)
- Spring Values → Frame Values: extends (evidence: `packages/core/src/SpringValue.ts`)
- Spring Values → Animated Values: reads animated node (evidence: `packages/core/src/SpringValue.ts`)
- Imperative Refs → Controller: controls (evidence: `packages/core/src/SpringRef.ts`)
- Animated Host → Animated Values: observes (evidence: `packages/animated/src/createHost.ts`)
- Web Target → Animated Host: creates host (evidence: `packages/animated/src/createHost.ts`)
- Three Target → Animated Host: creates host
- Parallax → Shared Helpers: uses helpers (evidence: `packages/parallax/src/index.tsx`)
- Spring Values → Frame Loop: advances values (evidence: `packages/core/src/SpringValue.ts`)
- Application → Imperative Refs: controls imperatively (evidence: `README.md`)
