Interaction model

An interaction is a person directly controlling values through input. interanimate treats gestures and animation as two halves of the same system: an interaction owns values while input is active, then hands them to a motion — with no seam.

Inputs#

interanimate recognizes these input families. Each maps onto the same lifecycle.

The gesture lifecycle#

Every continuous interaction moves through the same states. Discrete inputs (a click, a keypress) pass through a subset.

          input start                 movement past threshold
  Rest ───────────────▶ Engaged ───────────────────────────▶ Tracking
   ▲                       │                                    │
   │      cancel           │ release without moving             │ release
   │◀──────────────────────┤ (it was a press)                   ▼
   │                       ▼                                 Released
   │                    Committed                               │
   │                                                            │ hand-off
   │              settled                                       ▼
   └───────────────────────────────────────────────────────  Settling
                         ▲                                      │
                         └──────── new input start ─────────────┘
                                 (interruption → Engaged)

Rest#

No interaction owns the values. Motions may be running.

Engaged#

Input has started (pointer-down, touch-down, key-down).

• Respond immediately. Visible acknowledgment happens on entering this state — within the 100 ms response budget (Principle 1). For a button, this is the press state. For a draggable card, it might be a subtle lift.
• Take ownership. If any motion owns the affected values, the interaction takes ownership now, at the current presentation value and velocity (Principle 5). The person has grabbed something that was moving; it stops in their hand.
• Remember the grab point. The offset between the input point and the object is recorded and preserved for the whole interaction.

Tracking#

The input has moved past the hysteresis threshold and committed to being a drag (or pinch, etc.).

• Hysteresis. A small movement threshold must be crossed before committing. This prevents taps from turning into accidental drags and lets the system detect direction. Apple's fluid-interface guidance uses roughly ten pixels; interanimate treats this as a tunable default that scales with input precision (a mouse needs less than a finger).
• Direction locking. For constrained interactions (a horizontal carousel inside a vertical page), the direction is decided at the threshold and held. Movement on the other axis goes to whoever owns that axis — typically page scroll. Resolving scroll-versus-drag conflicts is part of the interaction's definition, not left to chance.
• 1:1 tracking. Values follow the input exactly, preserving the grab offset (Principle 8). No smoothing, no lag, no easing while the person is in control.
• Continuous feedback. Feedback updates throughout, not just at the end — a drawer reveals progressively, a slider's value updates live.
• Resistance at boundaries. Past a limit, movement is progressively damped rather than stopped.
• Velocity tracking. A short history of recent positions and times is kept, so release velocity reflects the gesture's actual motion rather than a single noisy sample.

Released#

The input has ended.

• Measure velocity from recent history.
• Project where the gesture was heading (see Projection).
• Decide the outcome — which target, whether the action commits (e.g. dismiss) or reverts.
• Hand off to a motion that inherits position and velocity.

A gesture's outcome depends on its intent, not just its final position. A fast flick in a direction commits even with a short travel; a slow drag must travel further.

Committed#

For discrete inputs, or a press released without moving past the threshold: the action is performed. The press state releases — and releasing can be a little slower than pressing, so the acknowledgment remains perceptible on a quick tap.

Settling#

A motion owns the values and carries them to rest. Bounce is permitted here only if real velocity was handed off (Principle 10). If new input starts at any time, the lifecycle returns to Engaged immediately.

Cancelled#

The interaction was abandoned: the pointer left the target and released outside it, the person pressed Escape, the system interrupted (a call came in), or a second finger turned a drag into a different gesture. Values return to their pre-interaction target by spring, from where they are. Cancel is always available — a person who changes their mind mid-press should be able to slide off and release without triggering anything, and sliding back on re-engages.

Rules (normative)#

1. Acknowledgment occurs on input start, within 100 ms.
2. An interaction takes ownership from any motion immediately on input start.
3. Grab offset is preserved for the duration of the interaction.
4. Commitment to a drag requires crossing a hysteresis threshold.
5. While tracking, values follow input 1:1 with no added smoothing or delay.
6. Tracking continues even if the pointer leaves the element's bounds.
7. Extra simultaneous touch points that aren't part of the gesture are ignored rather than allowed to cause jumps.
8. Release velocity is computed from a short history, not a single sample.
9. Gesture outcomes are decided from projected position, not release position alone.
10. Every continuous interaction is cancellable, and cancellation returns values smoothly from their current state.
11. Every interaction has a non-gesture equivalent (a button, a key) so that no outcome is gesture-only.

Input modality#

Interactions adapt to the input that's driving them, because people's expectations differ by modality.

• Touch is direct: content is under the finger, so 1:1 tracking, momentum, and physical response carry the most weight. Larger hysteresis suits a less precise input.
• Fine pointer (mouse, trackpad) is indirect: response can be more subdued. Apple's guidance gives a concrete example — the same material responds to direct touch with more emphasis than to a trackpad. Hover exists, so hover affordances are allowed.
• Keyboard is discrete and frequent: by default keyboard-initiated actions resolve to instant tempo (Principle 3). Focus indication is always visible and never depends on motion to be noticed.
• No hover available — hover-triggered motion is disabled entirely rather than firing on tap, which would make it feel like a glitch.

Hand-off in practice (informative)#

Consider a bottom sheet the person drags down to dismiss.

1. Engaged. Finger touches the sheet mid-way through its opening animation. The opening spring releases ownership; the sheet stops under the finger. Nothing jumps.
2. Tracking. After a few pixels of downward movement, the drag commits vertically. The sheet follows the finger exactly. Dragging up past the fully-open position meets resistance.
3. Released. The finger lifts while moving downward quickly. Projection says the sheet would have come to rest below the closed threshold, so the outcome is dismiss — even though it was released above the halfway point.
4. Settling. A spring carries the sheet off-screen, starting at the finger's exact velocity. Because the person supplied that momentum, the motion feels thrown rather than animated.
5. Interruption. If the finger catches the sheet again on its way down, it stops in the hand and the cycle starts over.

Under reduced motion, steps 1–3 are identical — the person is in control, and that motion is essential. Step 4 becomes a short fade-out instead of a throw.