Changelog - Motion Icon Docs

All notable changes to Motion Icons React are documented on this page. We follow Semantic Versioning.

[1.0.9] - November 2025

Critical Bug Fix: Entrance Animations

This release fixes a critical issue where entrance animations were not working properly in the npm package despite functioning correctly in the website playground.

Problem Identified

Entrance animations were either too fast, invisible, or not playing at all in applications using the npm package:

Animations appeared to skip or play too quickly
Icons were visible immediately instead of animating in
Animation timing didn’t match the specified duration
The same code worked perfectly in the website playground

Root Cause

Three separate issues were preventing entrance animations from working:

Timer Logic Error: The setHasEntered(true) was being called after only animationDelay instead of animationDuration + animationDelay, causing the animation class to be removed prematurely
Missing Initial Opacity: Elements weren’t starting with opacity: 0, making them visible before the animation began
Conditional Animation Duration: The animationDuration style was only applied conditionally, preventing proper override of CSS defaults

Changes Made

1. Fixed Timer Duration

Before:

useEffect(() => {
  if (entrance) {
    const timer = setTimeout(() => {
      setHasEntered(true);
    }, animationDelay);  // ❌ Only waits for delay!
    return () => clearTimeout(timer);
  }
}, [entrance, animationDelay]);

After:

useEffect(() => {
  if (entrance) {
    const timer = setTimeout(() => {
      setHasEntered(true);
    }, animationDuration + animationDelay);  // ✅ Waits for full animation
    return () => clearTimeout(timer);
  }
}, [entrance, animationDuration, animationDelay]);

Why this fixes it: The entrance animation class needs to remain applied for the entire duration of the animation. Previously, it was removed after just the delay, cutting off the animation mid-play.

2. Added Initial Opacity for Entrance Animations

Before:

style={{
  display: 'inline-flex',
  alignItems: 'center',
  justifyContent: 'center',
  color
}}

After:

style={{
  display: 'inline-flex',
  alignItems: 'center',
  justifyContent: 'center',
  animationDuration: `${animationDuration}ms`,
  animationDelay: `${animationDelay}ms`,
  ...(entrance && !hasEntered && { opacity: 0 }),  // ✅ Start invisible
  color
}}

Why this fixes it: Entrance animations need the element to start invisible (opacity: 0) before the animation begins. The CSS keyframes animate from opacity: 0 to opacity: 1, but without the initial opacity, the element appears immediately.

3. Always Apply Animation Duration

Before:

style={{
  ...(entrance && !hasEntered && { animationDuration: `${animationDuration}ms` }),
  ...(animationDelay > 0 && { animationDelay: `${animationDelay}ms` }),
}}

After:

style={{
  animationDuration: `${animationDuration}ms`,  // ✅ Always applied
  animationDelay: `${animationDelay}ms`,        // ✅ Always applied
  ...(entrance && !hasEntered && { opacity: 0 }),
}}

Why this fixes it: The entrance animation CSS classes have hardcoded durations (0.8s-1s). By always applying the inline style, we ensure the user’s custom animationDuration prop properly overrides these defaults.

Testing Results

Before v1.0.9:

❌ Entrance animations not visible or too fast
❌ Icons appear immediately instead of animating
❌ Custom timing not respected
✅ Works in website playground

After v1.0.9:

✅ Entrance animations work properly
✅ Icons start invisible and animate in
✅ Custom duration and delay respected
✅ Matches website playground behavior
✅ Works in React, Next.js, and Vite

Migration Guide

If you’re upgrading from v1.0.8 or earlier:

Update the package:
```
npm install motion-icons-react@latest
```
Clear build cache:
```
rm -rf node_modules/.cache
npm run dev
```
Hard refresh browser:
- Windows/Linux: Ctrl + Shift + R
- Mac: Cmd + Shift + R

No code changes are required in your application. All entrance animations will now work as expected.

Example

<MotionIcon
  name="Heart"
  entrance="fadeInUp"        // Now works correctly!
  animationDuration={1000}   // Duration is respected
  animationDelay={200}       // Delay works properly
/>

Files Changed

npm-motion-icons/src/components/MotionIcon.tsx - Fixed entrance animation logic

[1.0.3] - October 2025

Critical Bug Fix: Next.js Animation Support

This release fixes a critical issue where animations were not working in Next.js applications despite working perfectly in regular React apps.

Problem Identified

Animations appeared static in Next.js applications even though:

CSS was loaded correctly
Classes were applied to elements
DevTools showed animation: running
No console errors were present

Root Cause

Tailwind CSS utility classes were conflicting with CSS animation transforms. The component was using Tailwind classes like inline-flex items-center justify-center which set CSS properties that interfered with the animation’s transform property.

Changes Made

1. Removed Conflicting Tailwind Classes

Before:

className={cn(
  'inline-flex items-center justify-center',  // Conflicting classes
  interactive && 'cursor-pointer transition-transform duration-200',
  shouldAnimate && animationClass,
  className
)}

After:

className={cn(
  shouldAnimate && animationClass,  // Animation class first
  interactive && 'cursor-pointer',  // Removed transition-transform
  className
)}
style={{
  display: 'inline-flex',           // Moved to inline styles
  alignItems: 'center',
  justifyContent: 'center',
}}

Why this fixes it: Tailwind’s utility classes can override CSS animation properties. Moving layout properties to inline styles prevents conflicts and ensures animation classes have proper specificity.

2. Fixed SSR Hydration Issue

Before:

const [isAnimating, setIsAnimating] = useState(trigger === 'always');

After:

const [isAnimating, setIsAnimating] = useState(false);

useEffect(() => {
  if (trigger === 'always') {
    setIsAnimating(true);
  }
}, [trigger]);

Why this fixes it: Prevents hydration mismatch between server and client, ensures animations start after component mounts, and provides better Next.js SSR compatibility.

3. Improved Trigger Logic

Before:

const shouldAnimate = isAnimating && animation !== 'none';

After:

const shouldAnimate = (trigger === 'always' || isAnimating) && animation !== 'none';

Why this fixes it: The trigger="always" now applies animation immediately without waiting for state update, making continuous animations more reliable.

4. Removed Inline Animation Duration Override

Before:

style={{
  animationDuration: `${animationDuration}ms`,  // Always applied
  animationDelay: `${animationDelay}ms`,
}}

After:

style={{
  ...(entrance && !hasEntered && { animationDuration: `${animationDuration}ms` }),
  ...(animationDelay > 0 && { animationDelay: `${animationDelay}ms` }),
}}

Why this fixes it: Inline styles have higher specificity than CSS classes. The CSS defines animations as infinite, but inline style was overriding this. Now only applies duration for entrance animations where needed.

Testing Results

Before v1.0.3:

Works in React
Static in Next.js
Static in Next.js + Tailwind

After v1.0.3:

Works in React
Works in Next.js
Works in Next.js + Tailwind
Works with Turbopack
Works with SSR

Migration Guide

If you’re upgrading from v1.0.2:

Update the package:
```
npm install motion-icons-react@latest
```
Clear Next.js cache (recommended):
```
rm -rf .next
npm run dev
```
Hard refresh browser:
- Windows/Linux: Ctrl + Shift + R
- Mac: Cmd + Shift + R

No code changes are required in your application.

Technical Details

The problem was a CSS specificity conflict where Tailwind utility classes interfered with animation transforms. By moving non-animation styles to inline styles (which have highest specificity), we ensure:

Layout styles don’t interfere with animations
Animation classes work consistently
No conflicts with Tailwind or other CSS frameworks

Files Changed

src/components/MotionIcon.tsx - Main component fix
src/animations/animations.css - Enhanced animation keyframes
package.json - Version bump to 1.0.3

[1.0.2] - October 2025

Bug Fixes

Minor performance improvements
Documentation updates
TypeScript type refinements

[1.0.0] - October 2025

Initial Stable Release

The first production-ready release of Motion Icons React. This release brings smooth, accessible animations to Lucide React icons with zero configuration.

New Features

Core Animations

11 Built-in Animations: Complete animation library including:
- pulse - Gentle pulsing scale effect
- spin - Continuous 360° rotation
- bounce - Vertical bouncing with elastic easing
- ping - Radar-like expanding effect
- wiggle - Side-to-side shaking
- flip - 3D flip animation
- heartbeat - Double-pulse effect
- shake - Horizontal shaking motion
- swing - Pendulum-like rotation
- tada - Attention-grabbing celebration
- rubber - Rubber band elastic effect

Entrance Animations

10 Entrance Effects: Make icons appear with style
- fadeIn, fadeInUp, fadeInDown, fadeInLeft, fadeInRight
- scaleIn, slideInUp, slideInDown
- rotateIn, zoomIn

Animation Control

4 Trigger Types: Control when animations play
- always - Continuous animation (default)
- hover - Animate on mouse hover
- click - Animate on click
- focus - Animate on keyboard focus
Customizable Timing: Full control over duration and delay
Interactive Mode: Built-in hover effects for clickable icons

Developer Experience

TypeScript First: Complete type definitions with IntelliSense
Zero Configuration: Works immediately after installation
Framework Agnostic: Compatible with Next.js, Vite, CRA, and more
Tree Shakeable: Only bundle what you use

Accessibility

Motion Preferences: Automatic respect for prefers-reduced-motion
Keyboard Navigation: Full keyboard accessibility support
Screen Reader Friendly: Proper ARIA attributes
Focus Management: Visible focus indicators

Package Details

Package Name: motion-icons-react
Peer Dependencies: lucide-react (for icon shapes)
Bundle Size: ~15KB gzipped (core) + ~8KB (CSS)
Browser Support: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+

Documentation

Comprehensive Guides: Step-by-step setup for Next.js and Vite
API Reference: Complete props documentation with examples
Real-World Examples: 20+ practical use cases
Accessibility Guide: Best practices for inclusive design
Interactive Demos: Live examples for all animations

Customization Options

<MotionIcon
  name="Heart"              // Icon name (required)
  animation="heartbeat"     // Animation type
  entrance="zoomIn"         // Entrance effect
  trigger="hover"           // When to animate
  size={32}                 // Icon size
  color="red"               // Icon color
  weight="bold"             // Stroke weight
  interactive               // Enable hover effects
  animationDuration={1000}  // Duration in ms
  animationDelay={200}      // Delay in ms
  className="custom-class"  // Additional CSS
  onClick={handleClick}     // Event handlers
/>

Roadmap

Planned for v1.1.0

Custom Animations: Define your own keyframe animations
Animation Sequences: Chain multiple animations together
More Entrance Effects: 5+ additional entrance animations
Animation Presets: Pre-configured combinations for common patterns
Performance Mode: Reduced animation complexity for low-end devices

Future Considerations

Animation Builder: Visual tool for creating custom animations
React Native Support: Bring animations to mobile apps
Animation Timeline: Control animation playback programmatically
Gesture Support: Touch and swipe gesture triggers
Sound Effects: Optional audio feedback for animations

Migration Guides

From Beta to v1.0.0

No breaking changes! The API is fully backward compatible. Recommended updates:

// Old (still works)
<MotionIcon name="Heart" animation="pulse" />

// New (with entrance effect)
<MotionIcon 
  name="Heart" 
  animation="pulse" 
  entrance="fadeIn" 
/>

Contributing

We welcome contributions from the community!

How to Contribute

Report Bugs: Open an issue
Request Features: Start a discussion
Submit PRs: Contribution guidelines
Improve Docs: Help us make documentation better

Contributors

Thank you to everyone who contributed to this release! 🎉

Support

Documentation: motion-icons.dev
GitHub Issues: Report bugs
Discussions: Ask questions
Email: garvitjoshi543@gmail.com

License

Motion Icons React is MIT licensed.

Getting Started

Essentials

Resources

​[1.0.9] - November 2025

​Critical Bug Fix: Entrance Animations

​Problem Identified

​Root Cause

​Changes Made

​1. Fixed Timer Duration

​2. Added Initial Opacity for Entrance Animations

​3. Always Apply Animation Duration

​Testing Results

​Migration Guide

​Example

​Files Changed

​[1.0.3] - October 2025

​Critical Bug Fix: Next.js Animation Support

​Problem Identified

​Root Cause

​Changes Made

​1. Removed Conflicting Tailwind Classes

​2. Fixed SSR Hydration Issue

​3. Improved Trigger Logic

​4. Removed Inline Animation Duration Override

​Testing Results

​Migration Guide

​Technical Details

​Files Changed

​[1.0.2] - October 2025

​Bug Fixes

​[1.0.0] - October 2025

​Initial Stable Release

​New Features

​Core Animations

​Entrance Animations

​Animation Control

​Developer Experience

​Accessibility

​Package Details

​Documentation

​Customization Options

​Roadmap

​Planned for v1.1.0

​Future Considerations

​Migration Guides

​From Beta to v1.0.0

​Contributing

​How to Contribute

​Contributors

​Support

​License

[1.0.9] - November 2025

Critical Bug Fix: Entrance Animations

Problem Identified

Root Cause

Changes Made

1. Fixed Timer Duration

2. Added Initial Opacity for Entrance Animations

3. Always Apply Animation Duration

Testing Results

Migration Guide

Example

Files Changed

[1.0.3] - October 2025

Critical Bug Fix: Next.js Animation Support

Problem Identified

Root Cause

Changes Made

1. Removed Conflicting Tailwind Classes

2. Fixed SSR Hydration Issue

3. Improved Trigger Logic

4. Removed Inline Animation Duration Override

Testing Results

Migration Guide

Technical Details

Files Changed

[1.0.2] - October 2025

Bug Fixes

[1.0.0] - October 2025

Initial Stable Release

New Features

Core Animations

Entrance Animations

Animation Control

Developer Experience

Accessibility

Package Details

Documentation

Customization Options

Roadmap

Planned for v1.1.0

Future Considerations

Migration Guides

From Beta to v1.0.0

Contributing

How to Contribute

Contributors

Support

License