tailwind-motion

A powerful Tailwind CSS animation library with React hooks, scroll-triggered animations, hover animations, stagger effects, and full TypeScript support.

Installation

npm install tailwind-motion
# or
yarn add tailwind-motion
# or
pnpm add tailwind-motion

Setup

1. Add the Tailwind plugin

In your tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  plugins: [
    require('tailwind-motion/plugin'),
  ],
};

This registers all keyframes and animate-* utility classes.

2. Import in your app

import { Motion, MotionGroup, useScrollAnimation, useHoverAnimation } from 'tailwind-motion';

<Motion> Component

The all-in-one animation component. Works with mount, scroll, hover, and click triggers.

Mount animation (default)

import { Motion } from 'tailwind-motion';

export default function Hero() {
  return (
    <Motion preset="fade-in-up" duration="normal" easing="spring">
      <h1>Welcome</h1>
    </Motion>
  );
}

Scroll-triggered animation

<Motion
  trigger="scroll"
  scroll={{
    preset: 'fade-in-left',
    threshold: 0.2,
    once: true,
  }}
>
  <p>Appears as you scroll</p>
</Motion>

Hover animation

<Motion
  trigger="hover"
  hover={{
    preset: 'rubber-band',
    duration: 'fast',
  }}
>
  <button className="px-4 py-2 bg-blue-500 text-white rounded">Hover me</button>
</Motion>

Stagger with delay

<Motion preset="fade-in-up" delay={200} duration="slow" easing="spring">
  <Card />
</Motion>

Looping attention animation

<Motion preset="heartbeat" repeat={-1}>
  <span>❤️</span>
</Motion>

<Motion> Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | preset | AnimationPreset | — | Animation name | | trigger | 'mount' \| 'scroll' \| 'hover' \| 'click' | 'mount' | When to trigger | | duration | 'fastest' \| 'fast' \| 'normal' \| 'slow' \| 'slowest' \| number | 'normal' | Animation speed | | delay | number | 0 | Delay in ms | | easing | AnimationEasing | 'ease-out' | CSS easing or named preset | | repeat | number | 1 | Times to repeat (-1 = infinite) | | reverse | boolean | false | Play in reverse | | fillMode | 'none' \| 'forwards' \| 'backwards' \| 'both' | 'both' | CSS fill mode | | scroll | ScrollAnimationConfig | — | Scroll trigger config | | hover | HoverAnimationConfig | — | Hover trigger config | | as | keyof JSX.IntrinsicElements | 'div' | Rendered HTML tag | | className | string | — | Extra CSS classes |

<MotionGroup> Component

Stagger-animate a list of children automatically.

import { MotionGroup } from 'tailwind-motion';

export default function FeatureList() {
  return (
    <MotionGroup
      preset="fade-in-up"
      staggerDelay={100}
      duration="normal"
      easing="spring"
      trigger="scroll"
    >
      <div className="p-4 bg-white rounded shadow">Feature One</div>
      <div className="p-4 bg-white rounded shadow">Feature Two</div>
      <div className="p-4 bg-white rounded shadow">Feature Three</div>
    </MotionGroup>
  );
}

<MotionGroup> Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | preset | AnimationPreset | — | Animation for each child | | staggerDelay | number | 80 | Delay between children (ms) | | direction | 'normal' \| 'reverse' \| 'center' \| 'edges' | 'normal' | Stagger direction | | trigger | 'mount' \| 'scroll' | 'mount' | When to start | | duration | AnimationDuration | 'normal' | Child animation speed | | delay | number | 0 | Base delay before stagger starts | | scroll | ScrollAnimationConfig | — | Scroll config when trigger="scroll" | | as | keyof JSX.IntrinsicElements | 'div' | Wrapper tag |

Hooks

useScrollAnimation

Full control over scroll-triggered animations.

import { useScrollAnimation } from 'tailwind-motion';

export default function Card() {
  const { ref, isVisible, style } = useScrollAnimation({
    preset: 'fade-in-up',
    duration: 'normal',
    threshold: 0.2,
    once: true,
  });

  return (
    <div ref={ref} style={style} className="p-6 bg-white rounded-xl shadow">
      I animate in when scrolled into view
    </div>
  );
}

useHoverAnimation

Animate on mouse enter / leave.

import { useHoverAnimation } from 'tailwind-motion';

export default function HoverCard() {
  const { ref, style, handlers } = useHoverAnimation({
    preset: 'scale-in',
    duration: 'fastest',
    easing: 'spring',
    leaveAnimation: 'scale-out',
  });

  return (
    <div ref={ref} style={style} {...handlers} className="p-4 bg-indigo-500 text-white rounded-lg cursor-pointer">
      Hover me!
    </div>
  );
}

useAnimation (manual control)

Play, pause, and reset an animation programmatically.

import { useAnimation } from 'tailwind-motion';

export default function ClickAnimate() {
  const { style, play, reset, isPlaying } = useAnimation({
    preset: 'bounce-in',
    duration: 'normal',
    easing: 'spring',
  });

  return (
    <div>
      <div style={style} className="w-16 h-16 bg-green-400 rounded-full" />
      <button onClick={play} disabled={isPlaying}>Play</button>
      <button onClick={reset}>Reset</button>
    </div>
  );
}

useStaggerAnimation

Generate staggered styles for N items manually.

import { useStaggerAnimation } from 'tailwind-motion';

export default function List({ items }: { items: string[] }) {
  const stagger = useStaggerAnimation({
    count: items.length,
    preset: 'fade-in-up',
    staggerDelay: 80,
    direction: 'normal',
    visible: true,
  });

  return (
    <ul>
      {items.map((item, i) => (
        <li key={item} style={stagger[i].style}>{item}</li>
      ))}
    </ul>
  );
}

Preset Builders

Import ready-made config objects for common use cases:

import {
  fadeInUp, bounceIn, scrollFadeInUp,
  hoverScale, hoverRubberBand, pulse,
} from 'tailwind-motion/animations';

// Use with <Motion>
<Motion {...fadeInUp({ duration: 'fast' })}>...</Motion>
<Motion trigger="scroll" scroll={scrollFadeInUp({ threshold: 0.3 })}>...</Motion>
<Motion trigger="hover" hover={hoverRubberBand()}>...</Motion>

Available preset builders

| Builder | Category | |---------|----------| | fadeIn, fadeOut, fadeInUp, fadeInDown, fadeInLeft, fadeInRight | Fade | | slideInUp, slideInDown, slideInLeft, slideInRight | Slide | | scaleIn, scaleOut, bounceIn | Scale | | rotateIn, spinOnce | Rotate | | pulse, shake, wobble, rubberBand, heartbeat, jello, flash | Attention | | scrollFadeInUp, scrollSlideInLeft, scrollSlideInRight, scrollScaleIn | Scroll | | hoverScale, hoverShake, hoverRubberBand, hoverWobble, hoverHeartbeat | Hover |

Tailwind Utility Classes

When the plugin is registered, you can use classes directly without JavaScript:

<!-- Fade animations -->
<div class="animate-fade-in">...</div>
<div class="animate-fade-in-up">...</div>
<div class="animate-fade-in-left">...</div>

<!-- Slide animations -->
<div class="animate-slide-in-up">...</div>
<div class="animate-slide-in-right">...</div>

<!-- Scale / bounce -->
<div class="animate-scale-in">...</div>
<div class="animate-bounce-in">...</div>

<!-- Attention -->
<div class="animate-shake">...</div>
<div class="animate-wobble">...</div>
<div class="animate-rubber-band">...</div>
<div class="animate-heartbeat">...</div>
<div class="animate-jello">...</div>
<div class="animate-flash">...</div>

<!-- Duration modifiers -->
<div class="animate-fade-in animate-duration-fast">...</div>
<div class="animate-bounce-in animate-duration-slowest">...</div>

<!-- Easing modifiers -->
<div class="animate-scale-in animate-ease-spring">...</div>
<div class="animate-fade-in-up animate-ease-bounce">...</div>

All Animation Presets

| Name | Category | |------|----------| | fade-in | Fade | | fade-out | Fade | | fade-in-up | Fade | | fade-in-down | Fade | | fade-in-left | Fade | | fade-in-right | Fade | | slide-in-up | Slide | | slide-in-down | Slide | | slide-in-left | Slide | | slide-in-right | Slide | | slide-out-up | Slide | | slide-out-down | Slide | | scale-in | Scale | | scale-out | Scale | | scale-in-center | Scale | | bounce-in | Scale | | bounce-out | Scale | | rotate-in | Rotate | | rotate-in-cw | Rotate | | rotate-in-ccw | Rotate | | spin-once | Rotate | | pulse | Attention | | shake | Attention | | bounce | Attention | | flash | Attention | | wobble | Attention | | rubber-band | Attention | | jello | Attention | | heartbeat | Attention |

Easing Presets

| Name | Value | |------|-------| | linear | linear | | ease | ease | | ease-in | ease-in | | ease-out | ease-out | | ease-in-out | ease-in-out | | spring | cubic-bezier(0.34, 1.56, 0.64, 1) | | bounce | cubic-bezier(0.68, -0.55, 0.265, 1.55) |

License

MIT