A powerful and flexible animation library for React applications, built on animejs v4.2.2 with enhanced scroll detection, comprehensive TypeScript support, and expanded animation presets.
- Type-Safe: Built with TypeScript for reliable autocompletion and error checking with full animejs v4.2.2 type definitions.
- Native Scroll Detection: Uses animejs v4.2.2's built-in onScroll event for performant scroll-based animations.
- Expanded Animation Presets: Over 40 predefined animations including flip, zoom, elastic, and attention-seeking effects.
- Independent Child Animations: Child elements can have their own scroll triggers and configurations.
- Flexible Animation Control: Supports single, multiple, and sequential animations with advanced scroll options.
- Enhanced Scroll Configuration: Custom containers, thresholds, axis detection, and repeat options.
- Easy Integration: Simple to integrate into existing React projects.
The component now defaults to rendering a <div> element. When using the Animate component with the animation prop, any custom animation props are internally used but filtered out so that React warnings about unknown attributes are avoided.
<Animate animation="fadeIn" duration={500} delay={200}>
<h2>Hello World</h2>
<p>This content will fade in on load.</p>
</Animate>You can pass an array of animations to have multiple effects applied simultaneously.
<Animate animation={["fadeIn", "slideUp"]} duration={800}>
<p>This element fades in and slides up simultaneously.</p>
</Animate>The childAnimations prop allows you to define animations for nested elements.
Note: that the custom prop is filtered from the DOM while the hook uses it to control child elements. Make sure the IDs in your DOM match those provided in
childAnimations.
<Animate
animation="fadeIn"
childAnimations={[
{ id: "title", animation: "slideDown", delay: 300 },
{ id: "subtitle", animation: "fadeLeft", delay: 600 },
]}
>
<div>
<h2 id="title">Animated Title</h2>
<p id="subtitle">This subtitle animates separately</p>
<div>The parent container just fades in.</div>
</div>
</Animate>Set the animateOnScroll prop to trigger the animation once the element is scrolled into view. The scrollThreshold determines when the animation starts.
<Animate animation="fadeUp" animateOnScroll scrollThreshold={0.3}>
<h2>I appear when scrolled into view!</h2>
</Animate>Use the enhanced scroll configuration object for more control over scroll behavior:
<Animate
animation="slideUp"
animateOnScroll={{
enabled: true,
threshold: 0.5,
repeat: true,
}}
>
<div>Advanced scroll animation with custom container and repeat</div>
</Animate>Child animations can have their own scroll triggers, independent of the parent:
<Animate
animation="fadeIn"
animateOnScroll={{ enabled: true, threshold: 0.2 }}
childAnimations={[
{
id: "title",
animation: "slideDown",
animateOnScroll: { enabled: true, threshold: 0.4, repeat: true }
},
{
id: "subtitle",
animation: "fadeLeft",
animateOnScroll: { enabled: true, threshold: 0.6 }
},
]}
>
<div>
<h2 id="title">Title with independent scroll trigger</h2>
<p id="subtitle">Subtitle with different scroll settings</p>
<div>Parent container fades in first</div>
</div>
</Animate>The useAnimation hook allows you to control animations imperatively. Use it to update animation configurations or to trigger animations on user interaction.
function UsingHook() {
const { ref, play, updateConfig } = useAnimation({
animation: "bounce",
duration: 1000,
});
return (
<div>
<div ref={ref} onClick={() => play()}>
Click me to bounce!
</div>
<br />
<button onClick={() => updateConfig({ duration: 5000, animation: "rotateRight" })}>
Make animation slower and rotate right
</button>
</div>
);
}The library includes over 40 predefined animation presets organized by category:
fadeIn,fadeUp,fadeDown,fadeLeft,fadeRight
scaleX,scaleY
skewUp,skewDown
rotateLeft,rotateRight
slideLeft,slideRight,slideUp,slideDown
bounce,pulse,shake,swing,tada
flipX,flipY,flipInX,flipInY,flipOutX,flipOutY
zoomIn,zoomOut,zoomInUp,zoomInDown,zoomInLeft,zoomInRightzoomOutUp,zoomOutDown,zoomOutLeft,zoomOutRight
elastic,elasticIn,elasticOut
flash,headShake,heartBeat,jello,rubberBand,wobble
// Examples of new animation presets
<Animate animation="flipInX" duration={800}>
<div>Flips in along X-axis</div>
</Animate>
<Animate animation="zoomInUp" delay={200}>
<div>Zooms in from below</div>
</Animate>
<Animate animation="elasticOut" duration={1200}>
<div>Elastic bounce effect</div>
</Animate>
<Animate animation="heartBeat" loop={3}>
<div>Attention-seeking heartbeat</div>
</Animate>interface ScrollConfig {
enabled: boolean; // Enable/disable scroll animation
threshold?: number | string; // When to trigger (0-1 or pixel value)
repeat?: boolean; // Repeat animation on scroll
// can use other configs if required
}interface UseAnimationProps extends AnimationConfig {
childAnimations?: AnimationTarget[];
parentId?: string;
animateOnLoad?: boolean;
animateOnScroll?: boolean | ScrollConfig;
}interface AnimationTarget extends AnimationConfig {
id: string;
parentId?: string;
animateOnScroll?: boolean | ScrollConfig;
}// Horizontal scroll animation
<Animate
animation="slideLeft"
animateOnScroll={{
enabled: true,
threshold: 0.3,
}}
>
<div>Triggers on horizontal scroll</div>
</Animate>
// Multiple animations with different scroll triggers
<Animate
animation={["fadeIn", "scaleX"]}
animateOnScroll={{ enabled: true, threshold: 0.1 }}
childAnimations={[
{
id: "card-1",
animation: "zoomInLeft",
animateOnScroll: { enabled: true, threshold: 0.3, repeat: true }
},
{
id: "card-2",
animation: "flipInY",
animateOnScroll: { enabled: true, threshold: 0.5 }
}
]}
>
<div>
<div id="card-1">Card 1 - zooms from left with repeat</div>
<div id="card-2">Card 2 - flips in along Y-axis</div>
</div>
</Animate>The library now uses animejs v4.2.2's native ScrollObserver which provides:
- Better Performance: Native implementation optimized for animations
- More Accurate Triggering: Precise scroll position detection
- Enhanced Features: Support for custom containers, axis detection, and repeat options
- Memory Efficiency: Automatic cleanup and disposal of observers
- Use Specific Containers: When possible, specify scroll containers to limit observation scope
- Optimize Thresholds: Use appropriate threshold values to avoid excessive triggering
- Limit Repeat Animations: Use
repeat: truejudiciously for performance - Batch Child Animations: Group related child animations for better coordination
The library provides comprehensive TypeScript support with:
- Full animejs v4.2.2 type definitions
- Enhanced IDE autocompletion for all animation properties
- Type-safe animation configuration
- Proper typing for scroll configuration options
- Complete interface definitions for all props and return types
import { AnimationConfig, ScrollConfig, UseAnimationProps } from '@koadz/animate';
// Fully typed animation configuration
const config: AnimationConfig = {
animation: "fadeIn",
duration: 1000,
delay: 200
};
// Typed scroll configuration
const scrollConfig: ScrollConfig = {
enabled: true,
threshold: 0.3,
repeat: false
};