🎬 react-native-animation-scenario

A lightweight, declarative animation timeline hook for React Native — perfect for scenarios like onboarding, tutorials, interactive demos, and more. Easily control complex UI animations step-by-step or automatically.

Works with React Native and Expo.

---

✨ Features

• ✅ Declarative animation timeline with step-by-step control
• 🧠 Supports set, move, delay, parallel, callback, vibrate, hold, label, goto, resume, use, ifJump, ifThen and use steps
• 🎛 Works in both "auto" and "manual" step modes
• 🔁 Loopable scenarios
• 📦 Minimal dependencies – just React Native + Animated
• 🧩 Drop-in TimelineView for debug or dev overlay
• 🔐 Safe callback and ref validation

---

⚡ Try it live

Snack demo on Expo

---

🔥 What's New in 1.4.3

• ✅ documentation added.

🔥 What's New in 1.4.2 Patch Release

• 🛠 Fixed an issue where the `stop() step didn’t always correctly interrupt the scenario execution.
• ✅ Improved overall code structure and performance with internal refactoring.

🔥 What's New in 1.4.0

• ✅ ifThen, ifElse, ifEnd: New block-style conditional logic, familiar to developers. Example:

ifThen(() => score.current > 5),
  move("x", 100, 500),
ifElse(),
  move("x", -100, 500),
ifEnd()

• ✅ Nested conditionals are supported and validated at compile time.
• ✅ Improved compiler validation to detect malformed blocks or unclosed conditionals.
• ✅ Relative values in move() using helper functions like inc(value) or dec(value). Example:

move("x", inc(50), 500)

• ✅ Arguments in callback() steps now supported.
• ✅ Jump to label in nextStep(label): You can resume or redirect flow from UI or interaction code.

🔥 What's New in 1.3.0

• ✅ resume step: jump back to the point after the last goto() call
• ✅ set step: set a value directly or from a function
• ✅ stop step: stop and reset the animation
• ✅ ifJump(condition, labelTrue, labelFalse?) step: jump based on condition
• 🛡 Label validation for goto and ifJump steps now included in scenario compilation
• ⚙️ Cleaned and centralized all validation logic in compileScenario()

🔥 What's New in 1.2.0

• ✅ goto("label") step: jump to a specific label in your scenario
• ✅ label("name") step: define named labels
• ✅ Nested reusable blocks with use("blockName")
• ✅ Full reset() and stop() logic
• ✅ TimelineView for visual debug
• ✅ useScreenLifecycle(onFocus, onBlur) helper

---

📦 Installation

npm install react-native-animation-scenario

---

📦 Exports

useAnimationScenario();             // Main hook
defineScenario([]);                 // Safely define your scenario
move(), delay(), callback(), ...    // Step helpers
useScreenLifecycle();               // Hook for screen focus lifecycle

---

🛠 Usage

import {
  useAnimationScenario,
  defineScenario,
  move,
  delay,
  parallel,
  callback,
  hold,
} from "react-native-animation-scenario";

const scenario = defineScenario([
  move("opacity", 1, 500),
  delay(300),
  parallel([
    move("scale", 1.1, 500),
    move("translateY", 50, 500),
  ]),
  hold("waitForTap"),
  callback("onFinish"),
]);

const MyComponent = () => {
  const {
    refs,
    start,
    reset,
    nextStep,
    TimelineView,
  } = useAnimationScenario({
    scenario,
    initialValues: {
      opacity: 0,
      scale: 1,
      translateY: 0,
    },
    callbacks: {
      onFinish: () => console.log("Done!"),
    },
  });

  useEffect(() => { start(); }, []);

  return (
    <Animated.View style={{
      opacity: refs.opacity,
      transform: [
        { scale: refs.scale },
        { translateY: refs.translateY }
      ]
    }}>
      <Text>Hello Animation</Text>
      <TimelineView />
    </Animated.View>
  );
};

---

🔧 Step Types

Type	Description	Version
move	Animate a ref value to a target	1.0
delay	Pause for a given duration	1.0
parallel	Animate multiple values simultaneously	1.0
callback	Run external logic (sync or async)	1.0
vibrate	Trigger haptic feedback	1.0
hold	Pause animation until nextStep() is called	1.0
label	Mark jump targets	1.2
goto	Jump to a label	1.2
use	Insert a block	1.2
set	Set a value directly or from a function	1.3
stop	Stop and reset the animation	1.3
resume	Continue from the point after last goto()	1.3
ifJump	Conditionally jump to a label	1.3
ifThen	Block-style conditional logic	1.4

---

🧠 Modes

• mode: "auto" – steps play sequentially
• mode: "manual" – steps only run via nextStep()
• loop: true – repeat the scenario forever

---

🧩 Reusable Blocks

const blocks = {
bounce: defineScenario([
move("y", -30, 200),
move("y", 0, 200),
]),
};

const scenario = defineScenario([
callback("showStart"),
use("bounce"),
delay(500),
use("bounce"),
]);

---

🤖 Conditional Branching with ifJump()

Use ifJump() to dynamically choose the next step at runtime.

const MyComponent = () => {
  const directionRef = useRef(1);

  const scenario = defineScenario([
    hold(), // Wait for user input before branching
    ifJump(() => directionRef.current === 1, "moveRight", "moveLeft"),
    label("moveRight"),
    move("x", 200, 500),
    goto("resumePoint"),
    label("moveLeft"),
    move("x", 0, 500),
    label("resumePoint"),
  ]);

  const { refs, start, nextStep } = useAnimationScenario({
    scenario,
    initialValues: { x: 100 },
  });

  useEffect(() => { start(); }, []);

  return (
    <View>
      <Animated.View
        style={{
          width: 50,
          height: 50,
          backgroundColor: "blue",
          transform: [{ translateX: refs.x }],
          marginBottom: 20,
        }}
      />
      <Text>Choose Direction:</Text>
      <View style={{ flexDirection: "row", gap: 10 }}>
        <Button title="Left" onPress={() => {
          directionRef.current = 0;
          nextStep();
        }} />
        <Button title="Right" onPress={() => {
          directionRef.current = 1;
          nextStep();
        }} />
      </View>
    </View>
  );
};

🔁 ifJump() using a named callback

You can define reusable branching logic in callbacks:

const scenario = defineScenario([
  hold(),
  ifJump("checkDirection", "goRight", "goLeft"),
  label("goRight"),
  move("x", 100, 300),
  goto("end"),
  label("goLeft"),
  move("x", -100, 300),
  label("end"),
]);

const { refs, nextStep, start } = useAnimationScenario({
  scenario,
  initialValues: { x: 0 },
  callbacks: {
    checkDirection: () => Math.random() > 0.5,
  },
});

---

🧪 Advanced Flow Example: set, goto, resume, and stop

This scenario demonstrates how to use the new set, goto, resume, and stop steps for conditional or non-linear animation flows.

import { useAnimationScenario,defineScenario, label, vibrate, move, goto, stop, set, resume } from "react-native-animation-scenario";

const scenario = defineScenario([
  label("start"),
  vibrate(),
  move("x", 100, 2000),
  goto("reverse"),                          // Jump to reverse path
  move("x", 200, 500, "after-resume"),      // Will resume here after `resume`
  stop(),                                   // Stops the flow here
  label("reverse"),
  set("x", 0),                              // Instantly reset position
  move("x", -100, 500),
  resume(),   
]);

const MyComponent = () => {
  const {refs,start,TimelineView,} = useAnimationScenario({
    scenario,
    initialValues: { x: 0, direction: 0 },
    callbacks: {
      checkDirection: () => {
        // Example: dynamically decide to reverse
        if (Math.random() > 0.5) return goto("reverse");
      },
    },
  });

  return (
    <Animated.View style={{ transform: [{ translateX: refs.x }] }} >
      <Button title="Start" onPress={start} />
      <TimelineView />
    </Animated.View>
  );
};

---

🧪 Timeline Debug

Add the TimelineView to display step progress:

<TimelineView /> <!-- Optional -->

Great for development or visual debugging of onboarding flows.

---

🛡 Safeguards

• 🚫 Throws error if an initialValue or callback is missing
• 🔒 All animations use Animated.Value and native drivers by default

---

🧩 Optional: Screen Lifecycle Hook

This helper hook requires @react-navigation/native and should be imported separately:

import { useScreenLifecycle } from 'react-native-animation-scenario/src/useScreenLifecycle';

It allows you to trigger logic when the screen gains or loses focus.

---

📄 License

MIT – Created by Cyril Adam

---

📦 CHANGELOG for v1.4.2 and v1.4.1

🔧 Fixes

• Fixed a bug where the stop() step didn't correctly interrupt scenario execution in all cases.
• Improved internal handling of the shouldStop flag to prevent race conditions and ensure proper reset behavior.
• reset() now explicitly clears holdResolver and callingStepIndexRef, making the scenario restart more predictable and clean.
• Minor log improvements under debug mode.

💡 Internal Improvements

• Factored out reusable logic into evalStepValue() and evalStepCondition() to unify async/sync step evaluation across set, ifThen, and callback steps.
• Jump logic now centralized via jumpTo() utility, ensuring consistent block traversal across ifThen, ifElse, and ifEnd.
• Internal state handling made more robust for future scalability and debugging ease.
• Scenario validation (compileScenario) now checks parallel content blocks.

📜 CHANGELOG for v1.4.0

✨ Added

• ifThen(condition), ifElse(), ifEnd() block structure: familiar conditional logic using nested blocks.
• nextStep(label): allows you to jump to a specific label manually, even after a hold() step.
• move(...) now supports relative values using inc(x) and dec(x).
• Extended support for callback() to accept parameters, including dynamic values.
• Scenario validation (compileScenario) now checks for properly closed ifThen/ifElse/ifEnd blocks.
• Modular refactoring for better extensibility.

🐞 Fixed

• Ensured ifJump() does not rely on refs directly from defineScenario().
• Improved safety and label resolution for nested conditional logic.
• Fixed corner cases in hold() + jump logic for nextStep().

🧪 Testing

• Jest tests added for malformed conditional structures (ifThen without ifEnd, duplicate ifElse, etc.)
• Unit tests extended to cover relative moves.

📜 CHANGELOG for v1.3.1

🐞 Fixed

• Move useScreenLifecycle to a separate export to avoid dependency issues on Snack

📜 CHANGELOG for v1.3.0

✨ Added

• set(target, value): set a ref value directly, from a function, or from an async callback
• stop(): terminates the current animation sequence cleanly
• resume(): continues execution from the step after the last goto() jump
• ifJump(condition, labelTrue, labelFalse?): conditional branching based on a sync or async function or a callback name
• Scenario validation now checks label existence for goto and ifJump
• Improved label jump tracking with callingStepIndexRef for `resume()

🐞 Fixed

• Ensured nextStep() respects the shouldStop flag
• Cleaned up validation logic (moved to compileScenario)
• Deduplicated validation errors for clearer debug output

🧪 Testing

• New unit test coverage for scenario compilation including nested `use() blocks and label resolution.
• Some validation moved from runtime to compile-time, simplifying runtime hook logic.

📜 CHANGELOG for v1.2.0

✨ Added

• goto("label") step to jump within the scenario
• label("name") step to declare jump targets
• Support for use("blockName") reusable block structure
• __sourceBlock annotation for debugging block origins
• Visual timeline label display (TimelineView)
• Full reset() support restores animated values
• stop() now halts looping scenarios safely
• useScreenLifecycle(onFocus, onBlur) hook

🐞 Fixed

• Scenario would continue running after screen unmount (fixed with shouldStop)
• reset() didn't clear active animation state properly
• Label detection and step validation improved

🧪 Testing

• Added Jest tests and modular compileScenario system
• Internal compilation now flattens nested use() blocks

---

🤝 Contributing

• PRs welcome! Especially for:
• TypeScript types
• New step types (e.g. spring)
• Helper tooling