Skip to main content

​
Overview

Tailwind Animations v1.0 represents a major architectural change with native support for Tailwind CSS v4. The plugin has been completely rewritten as a CSS-only implementation, eliminating the JavaScript-based plugin system used in v3.
Breaking Changes: Version 1.0+ is incompatible with Tailwind CSS v3. If you need v3 support, use @midudev/[email protected].

​
Key Changes

​
Package Rename

The package has been renamed from @midudev/tailwind-animations to tailwind-animations.

​
CSS-Only Implementation

The plugin is now pure CSS using Tailwind v4’s @theme and @utility directives. The JavaScript plugin system has been completely removed.

​
Configuration Method

Tailwind CSS v4 uses CSS imports instead of JavaScript configuration files.

​
Migration Steps

1

Update Tailwind CSS

First, upgrade your project to Tailwind CSS v4:
npm install tailwindcss@^4.0.0
2

Uninstall Old Package

Remove the old scoped package:
npm uninstall @midudev/tailwind-animations
3

Install New Package

Install the new unscoped package:
npm install tailwind-animations
4

Update Configuration

Before (Tailwind CSS v3):
tailwind.config.js
module.exports = {
  // ... other config
  plugins: [
    require('@midudev/tailwind-animations')
  ]
}
After (Tailwind CSS v4):
globals.css
@import 'tailwindcss';
@import 'tailwind-animations';
You can now delete your tailwind.config.js file if it only contained the animations plugin.
5

Remove JavaScript Plugin Logic

If you had any custom theme extensions for animations in your tailwind.config.js, you’ll need to migrate them to CSS custom properties using Tailwind v4’s @theme directive.
6

Verify Your Animations

All animation class names remain the same. Test your application to ensure animations work correctly:
<div class="animate-fade-in">
  Fade in box
</div>

<div class="animate-slide-in-bottom animate-delay-300 animate-duration-slow">
  Slow animation after 300ms
</div>

​
What Stays the Same

​
Class Names

All animation utility classes remain unchanged:
  • animate-fade-in, animate-fade-out
  • animate-slide-in-top, animate-slide-in-bottom
  • animate-zoom-in, animate-zoom-out
  • All other animation classes

​
Animation Modifiers

All modifier classes continue to work:
  • animate-delay-* - Animation delays
  • animate-duration-* - Animation durations
  • animate-iteration-count-* - Iteration counts
  • animate-fill-mode-* - Fill modes
  • animate-bezier-* - Timing functions

​
View Timelines

View timeline utilities remain functional: 
<div class="view-animate-[--subjectReveal] animate-zoom-in animate-range-[entry_10%_contain_25%]">
  Scroll-based animation
</div>

​
Benefits of v4

Faster Build Times

CSS-only implementation eliminates JavaScript processing overhead

Simpler Architecture

No plugin registration or JavaScript configuration needed

Better Tree-Shaking

Improved CSS optimization with Tailwind v4’s engine

Modern Standards

Built on Tailwind CSS v4’s native @theme and @utility directives

​
Troubleshooting

​
Animations not working after migration

  1. Verify you’ve imported tailwind-animations in your CSS file
  2. Ensure you’re using Tailwind CSS v4.0.0 or higher
  3. Check that your build process is processing the CSS imports correctly

​
Using both v3 and v4 in a monorepo

If you have a monorepo with projects on different Tailwind versions:
  • Projects on Tailwind v3: Use @midudev/[email protected]
  • Projects on Tailwind v4: Use tailwind-animations@latest

​
Need Help?

If you encounter issues during migration:

Build docs developers (and LLMs) love

Get started for freeTalk to us