useAnimationSequence
Relevant source files
The following files were used as context for generating this wiki page:
The useAnimationSequence hook is a specialized utility within the @pcstyle/motion library designed to orchestrate complex, multi-step animations using the Framer Motion useAnimate API. It allows developers to define a series of animation steps that execute sequentially, providing fine-grained control over timing, delays, and staggering for various DOM targets within a scoped environment.
This hook is part of a broader animation suite that includes specialized keyframes, variants (such as cyberpunk styles), and accessibility utilities like reduced motion support. It serves as a programmatic alternative to declarative variants for scenarios requiring precise temporal coordination between multiple elements.
Sources: src/hooks/useAnimationSequence.ts:1-40, package.json:1-10, src/hooks/index.ts:1-5
Core Hook Functionality
The module exports two primary hooks for handling imperative animations: useAnimationSequence for sequential multi-step logic and useAnimateTrigger for single-shot animation triggers.
useAnimationSequence
This hook returns a scope ref (to be attached to a parent element) and a runSequence function. The runSequence function iterates through an array of AnimationStep objects, awaiting each animation's completion before proceeding to the next.
The diagram shows the internal logic of the runSequence function as it processes animation steps.
Sources: src/hooks/useAnimationSequence.ts:18-40
useAnimateTrigger
A simplified version of the sequence hook, useAnimateTrigger provides a trigger function that executes a single animation against a target with a specified duration.
Sources: src/hooks/useAnimationSequence.ts:50-65
Data Structures and API
The hooks rely on specific TypeScript interfaces to define the structure of animation sequences and their timing options.
AnimationStep Interface
| Property | Type | Description |
|---|---|---|
target | string | A CSS selector string targeting elements within the scope. |
animation | DOMKeyframesDefinition | The keyframes to apply (e.g., x, y, opacity). |
options | Object | Optional configuration for duration, delay, or stagger. |
Sources: src/hooks/useAnimationSequence.ts:8-16
Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
duration | number | 0.3 | The length of the animation in seconds. |
delay | number | - | A fixed start delay for the step. |
stagger | number | - | Creates a staggered effect for multiple target elements. |
Sources: src/hooks/useAnimationSequence.ts:24-34
Integration with Keyframes and Variants
While useAnimationSequence is imperative, it is designed to work seamlessly with the library's predefined keyframes and variants. For instance, a sequence could use definitions from the cyberpunk keyframe set.
| Keyframe Set | Properties Influenced | Purpose |
|---|---|---|
glitchKeyframes | x, y | Erratic movement for digital "glitch" effects. |
pulseKeyframes | opacity, scale | Periodic breathing/glow effect. |
matrixKeyframes | y, opacity | Falling rain visual. |
hologramKeyframes | filter, opacity | Shimmering color-shifting effect. |
Sources: src/keyframes/index.ts:1-55, src/variants/cyber.ts:1-85
Sequence Execution Flow
When runSequence is invoked, it manages the lifecycle of the animation steps through an asynchronous loop.
This sequence diagram illustrates the asynchronous nature of the hook, where each step waits for the previous animate promise to resolve.
Sources: src/hooks/useAnimationSequence.ts:22-38
Accessibility Considerations
The library includes useReducedMotion and useAccessibleMotion hooks. While useAnimationSequence performs direct DOM animations, developers are encouraged to check the prefers-reduced-motion state before triggering complex sequences to ensure accessibility compliance.
const prefersReduced = useReducedMotion();
// Only run intense sequences if user hasn't requested reduced motion
if (!prefersReduced) {
runSequence(complexSteps);
}
Sources: src/hooks/useReducedMotion.ts:9-25
Summary
The useAnimationSequence hook provides a robust programmatic interface for managing timed animation flows within the @pcstyle/motion ecosystem. By abstracting the complexities of the useAnimate API and providing a structured AnimationStep format, it enables the creation of sophisticated, multi-element visual narratives while maintaining integration with the project's cyberpunk keyframes and accessibility standards.