# tailwind-animations — how to use this package

You are helping a developer add CSS animations with the `tailwind-animations` npm package.
This file is the shortest complete usage guide. Do not invent class names that are not listed here.

Package: `tailwind-animations@1.0.2`
npm: https://www.npmjs.com/package/tailwind-animations
Site: https://tailwind-animations.com
Playground: https://tailwind-animations.com/playground/
Full reference: https://tailwind-animations.com/llms-full.md
Skill: `npx skills add midudev/tailwind-animations`

## What it is

A **CSS-only** plugin for **Tailwind CSS v4**. There is no JavaScript plugin to register.
Import the CSS next to Tailwind. Then use utility classes in HTML.

Peer dependency: `"tailwindcss": "4"` (any 4.x).
Tailwind v3: use deprecated `@midudev/tailwind-animations@0.2.0` instead.

## Install

```bash
npm install tailwind-animations
# pnpm add tailwind-animations
# yarn add tailwind-animations
```

```css
/* globals.css / app.css */
@import "tailwindcss";
@import "tailwind-animations";
```

That is the entire setup. Do not add a `plugins` entry in `tailwind.config`.

## How to pick a class

1. Choose an animation name from the catalog.
2. Prefix it with `animate-` → `animate-fade-in`.
3. Optionally add modifiers (`animate-duration-*`, `animate-delay-*`, …).
4. Preview composition at https://tailwind-animations.com/playground/

```html
<div class="animate-fade-in">Hello</div>

<div class="animate-slide-in-bottom animate-delay-300 animate-duration-slow">
  Delayed entrance
</div>

<div class="animate-slide-in-left animate-slide-distance-[6rem]">
  Custom travel distance
</div>
```

## Animation catalog (79)

Use as `animate-{name}`:

- blink
- blurred-fade-in
- bounce-fade-in
- bouncing
- contract-horizontally
- contract-vertically
- dancing
- expand-horizontally
- expand-vertically
- fade-in
- fade-in-down
- fade-in-left
- fade-in-right
- fade-in-up
- fade-out
- fade-out-down
- fade-out-left
- fade-out-right
- fade-out-up
- flash
- flip-horizontal
- flip-in-x
- flip-in-y
- flip-out-x
- flip-out-y
- flip-vertical
- flip-x
- flip-y
- float
- hang
- heartbeat
- horizontal-bounce
- horizontal-vibration
- impulse-rotation-left
- impulse-rotation-right
- jelly
- jiggle
- jump
- pop
- pulse
- pulse-fade-in
- pulsing
- roll-in
- roll-out
- rotate-180
- rotate-360
- rotate-90
- rotate-in
- rotate-out
- rotational-wave
- rubber-band
- scale
- shake
- sink
- skew
- skew-right
- slide-in-bottom
- slide-in-left
- slide-in-right
- slide-in-top
- slide-out-bottom
- slide-out-left
- slide-out-right
- slide-out-top
- slide-rotate-in
- slide-rotate-out
- slide-up-fade
- spin-clockwise
- spin-counter-clockwise
- squeeze
- sway
- swing
- swing-drop-in
- tada
- tilt
- vertical-bounce
- wobble
- zoom-in
- zoom-out

## Modifiers

Compose after the animation class. Arbitrary values work: `animate-duration-[1.2s]`.

| Goal | Classes |
|------|---------|
| Duration | `animate-duration-{0\|100\|150\|200\|250\|300\|400\|500\|700\|800\|900\|1000\|none\|slower\|slow\|normal\|fast\|faster}` or `animate-duration-[777ms]` |
| Delay | `animate-delay-{0\|100\|150\|200\|250\|300\|400\|500\|700\|800\|900\|1000\|none}` or `animate-delay-[250ms]` |
| Steps | `animate-steps-{none\|retro\|normal\|modern}` |
| Iteration | `animate-iteration-count-{none\|once\|twice\|thrice\|infinite}` |
| Fill mode | `animate-fill-mode-{none\|forwards\|backwards\|both}` |
| Easing | `animate-ease`, `animate-ease-in`, `animate-ease-out`, `animate-ease-in-out`, `animate-linear` |
| Bezier | `animate-bezier-{sine-in\|sine-out\|sine-in-out\|quad-in\|quad-out\|quad-in-out\|cubic-in\|cubic-out\|cubic-in-out\|quart-in\|quart-out\|quart-in-out\|quint-in\|quint-out\|quint-in-out\|expo-in\|expo-out\|expo-in-out\|circ-in\|circ-out\|circ-in-out\|back-in\|back-out\|back-in-out}` |
| Direction | `animate-direction-normal\|reverse\|alternate\|alternate-reverse` |
| Play state | `animate-play-running`, `animate-play-paused` |
| Slide distance | `animate-slide-distance-[50%]`, `animate-slide-distance-[6rem]` (default travel is `20px`) |

## Native `<dialog>`

```html
<button type="button" commandfor="demo" command="show-modal">Open</button>

<dialog
  id="demo"
  class="animate-dialog animate-dialog-from-top animate-dialog-duration-fast m-auto max-w-lg rounded-2xl p-6"
>
  <p>Content</p>
  <button type="button" commandfor="demo" command="request-close">Close</button>
</dialog>
```

Also: `animate-dialog-fade`, `animate-dialog-zoom`, `animate-dialog-from-bottom|left|right`, `animate-dialog-duration-*`.

## Scroll / view timelines

```html
<div class="timeline-scroll animate-rotate-360">Rotates while scrolling</div>
<div class="animate-zoom-in timeline-view animate-range-entry">Plays as it enters the viewport</div>
```

- Timeline keys (`timeline-{key}`): none, auto, single, scroll, scroll-x, scroll-y, scroll-block, scroll-inline, view, view-x, view-y, view-block, view-inline
- Range keys (`animate-range-{key}`): normal, cover, contain, entry, exit, gradual, moderate, brisk, rapid

Needs browser support for CSS scroll/view timelines.

## Scroll mask (fade overflow edges)

Apply on the **scroll container** (needs overflow). Pure CSS via `animation-timeline: scroll()`.

```html
<ul class="scroll-mask-y max-h-64 overflow-y-auto">…</ul>
<div class="scroll-mask-x flex overflow-x-auto">…</div>
<div class="scroll-mask-b-from-80% overflow-y-auto">…</div>
<div class="scroll-mask-r-from-[calc(100%-2rem)] overflow-x-auto">…</div>
```

- All edges: `scroll-mask`, `scroll-mask-from-*`
- Axis: `scroll-mask-y`, `scroll-mask-x` (+ `-from-*`)
- One edge: `scroll-mask-t|b|l|r` (+ `-from-*`)
- Default opaque stop: `80%`

## Recipes

Staggered list:

```html
<li class="animate-fade-in-up animate-delay-100">…</li>
<li class="animate-fade-in-up animate-delay-200">…</li>
<li class="animate-fade-in-up animate-delay-300">…</li>
```

Attention once:

```html
<span class="animate-tada animate-iteration-count-once">Saved!</span>
```

Modal:

```html
<dialog class="animate-dialog animate-dialog-zoom animate-dialog-duration-normal">…</dialog>
```

Scrollable panel with edge fade:

```html
<div class="scroll-mask-y max-h-80 overflow-y-auto rounded-xl border p-4">…</div>
```

## Do / Don't

Do:
- Use names from the catalog above.
- Prefer transform + opacity animations (most of the list).
- Respect `prefers-reduced-motion` in the host app.
- Use the playground when unsure: https://tailwind-animations.com/playground/?a=jelly&d=700&p=card

Don't:
- Register a JS Tailwind plugin (none exists in v1).
- Use this package with Tailwind v3 (use `@midudev/tailwind-animations@0.2.0`).
- Invent `animate-*` names that are not in the catalog.
- Animate `width`, `height`, or `top` when a transform utility exists.
- Ship infinite loops (`pulse`, `horizontal-vibration`, …) without reduced-motion care.
- Use `blurred-fade-in` heavily on mobile (`filter: blur`).

## More docs (prefer these over HTML)

- This guide: https://tailwind-animations.com/llm.txt
- Short index: https://tailwind-animations.com/llms.txt
- Home (Markdown): https://tailwind-animations.com/index.md
- Playground (Markdown): https://tailwind-animations.com/playground.md
- Full catalog: https://tailwind-animations.com/llms-full.md
- Source of truth: https://github.com/midudev/tailwind-animations/blob/main/src/index.css

---
Generated from `tailwind-animations@1.0.2` · https://tailwind-animations.com