npm package: @retronew/unocss-preset-animate
Description: UnoCSS's animate preset for Wind4
Author: retronew
Latest version: 0.2.1

# unocss-preset-animate [![npm version](https://img.shields.io/npm/v/@retronew/unocss-preset-animate?color=red&logo=npm)](https://www.npmjs.com/package/@retronew/unocss-preset-animate) [![npm downloads](https://img.shields.io/npm/dt/@retronew/unocss-preset-animate?color=red&logo=npm)](https://www.npmjs.com/package/@retronew/unocss-preset-animate) [![MIT license](https://img.shields.io/github/license/retronew/unocss-preset-animate)]() [![GitHub stars](https://img.shields.io/github/stars/retronew/unocss-preset-animate?color=blue)](https://github.com/retronew/unocss-preset-animate)

A collection of UnoCSS utilities for creating beautiful animations tailored for Tailwind CSS. This package includes ready-to-use animations and a set of utilities for creating custom animations.

---

This package serves as an animation preset for UnoCSS, leveraging a CSS-first approach to provide animation capabilities without relying on legacy JavaScript plugins.

## Table of Contents

- [Getting Started](#getting-started)
  - [Installation](#installation)
- [Usage](#usage)
  - [Enter/Exit Animations](#enterexit-animations)
    - [Base Classes](#base-classes)
    - [Parameter Classes](#parameter-classes)
    - [Transform Classes](#transform-classes)
  - [Ready-to-Use Animations](#ready-to-use-animations)
- [Examples](#examples)
- [Notes on Compatibility](#notes-on-compatibility)

## Getting Started

### Installation

1. Install the package with `pnpm`:

   ```sh
   pnpm install -D @retronew/unocss-preset-animate
   ```

2. Add the preset to your UnoCSS configuration file (typically `uno.config.ts` or similar):

   ```javascript
   import { defineConfig } from 'unocss';
   import { presetAnimate } from '@retronew/unocss-preset-animate';

   export default defineConfig({
     presets: [
       presetAnimate(),
       // other presets...
     ],
     // other configurations...
   });
   ```

3. Start using the animations in your HTML:

   ```html
   <!-- Add an animated fade and zoom entrance -->
   <div class="animate-in fade-in zoom-in">...</div>

   <!-- Add an animated slide to top-left exit -->
   <div class="animate-out slide-out-to-top slide-out-to-left">...</div>

   <!-- And so much more! -->
   ```

## Usage

### Enter/Exit Animations

To keep the README concise, I'll define a few variables:

* `<io>`: Specify the type of animation. This can be `in` for enter or `out` for exit animations.
* `<dir>`: Specify the direction of the slide. This can be `in-from-top`, `in-from-bottom`, `in-from-left`, `in-from-right`, `in-from-start`, `in-from-end`, `out-to-top`, `out-to-bottom`, `out-to-left`, `out-to-right`, `out-to-start`, or `out-to-end`.
* `*`: Specify a value to apply. See list of possible values.

#### Base Classes

| Class            | Description                                                                                                |
| ---------------- | ---------------------------------------------------------------------------------------------------------- |
| [`animate-<io>`] | Base class for enter/exit animations. This needs to be applied in order for enter/exit animations to work. |

> Tip: `animate-in` / `animate-out` defines the base enter/exit animation (name + parameters).
> Pair it with transform utilities such as `fade-in`, `slide-in-from-top-*`, `zoom-in-*`, etc.

#### Parameter Classes

Use these utilities to customize animation parameters (duration/ease/delay/repeat/direction/fill/play-state):

| Class                  | Description                                                                                                                             |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| [`animate-duration-*`] | Sets `animation-duration`.                                                                                                              |
| [`animate-delay-*`]    | Sets `animation-delay`. Possible values: any `<number>`, `initial`, or any other `[<value>]`.                                           |
| [`animate-ease-*`]     | Sets `animation-timing-function`.                                                                                                       |
| [`repeat-*`]           | Sets `animation-iteration-count`. Possible values: any `<number>`, `infinite`, `initial` or any other `[<value>]`.                      |
| [`direction-*`]        | Sets `animation-direction`. Possible values: `normal`, `reverse`, `alternate`, `alternate-reverse`, `initial` or any other `[<value>]`. |
| [`fill-mode-*`]        | Sets `animation-fill-mode`. Possible values: `none`, `forwards`, `backwards`, `both`, `initial` or any other `[<value>]`.               |
| [`running`]            | Sets `animation-play-state` to `running`.                                                                                               |
| [`paused`]             | Sets `animation-play-state` to `paused`.                                                                                                |
| [`play-state-*`]       | Sets `animation-play-state`. Possible values: `initial` or any other `[<value>]`.                                                       |

> Note: These parameter utilities are designed to work smoothly with `animate-in` / `animate-out`.
> If you already have a “Tailwind v4 preset rules” layer providing these (e.g. `animations` rules), keep using it — this preset focuses on enter/exit variables + transforms + keyframes + ready-to-use animations.

#### Transform Classes

| Class             | Description                                                                                                                  |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| [`blur-in-*`]     | Applies blur when entering. Values: `blur-in`, `blur-in-<number>`, `blur-in-(<custom-property>)`, or `blur-in-[<value>]`.    |
| [`blur-out-*`]    | Applies blur when exiting. Values: `blur-out`, `blur-out-<number>`, `blur-out-(<custom-property>)`, or `blur-out-[<value>]`. |
| [`fade-<io>`]     | Fades the element in from or out to `opacity: 0`.                                                                            |
| [`fade-<io>-*`]   | Fades the element in/out to a specific opacity. Values: any `<number>` (percentage) or any other `[<value>]`.                |
| [`zoom-<io>`]     | Zooms the element in/out (default `scale3D(0,0,0)`).                                                                         |
| [`zoom-<io>-*`]   | Zooms the element in/out to a specific scale. Values: any `<number>` (percentage) or any other `[<value>]`.                  |
| [`spin-<io>`]     | Spins the element in/out (default `rotate(30deg)`).                                                                          |
| [`spin-<io>-*`]   | Spins the element in/out to a specific rotate value. Values: any `<number>` (degrees) or any other `[<value>]`.              |
| [`slide-<dir>`]   | Slides the element in/out to the specified direction (`100%`).                                                               |
| [`slide-<dir>-*`] | Slides the element in/out by a specific value. Values: spacing integers, ratios, percentages, or any other `[<value>]`.      |

> RTL note: `slide-*-start` and `slide-*-end` are direction-aware — in RTL they automatically flip left/right semantics.

### Ready-to-Use Animations

| Class                | Description                                                                                                                              |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| [`accordion-down`]   | Accordion down animation. Requires content height to be set (e.g. `--radix-accordion-content-height` or other compatible variables).     |
| [`accordion-up`]     | Accordion up animation. Requires content height to be set (e.g. `--radix-accordion-content-height` or other compatible variables).       |
| [`collapsible-down`] | Collapsible down animation. Requires content height to be set (e.g. `--radix-collapsible-content-height` or other compatible variables). |
| [`collapsible-up`]   | Collapsible up animation. Requires content height to be set (e.g. `--radix-collapsible-content-height` or other compatible variables).   |
| [`caret-blink`]      | Blinking animation for caret/cursor.                                                                                                     |

By the way, if you don't use some of the above animations, they won't be included in the final CSS file due to UnoCSS's on-demand generation.

## Examples

**Basic usage:**

```html
<div class="animate-in fade-in slide-in-from-top-8 animate-duration-500">
  Fade in from 0% opacity,<br />
  slide from top by 8 spacing units (2rem),<br />
  with a 500ms duration.
</div>
```

**Advanced usage:**

```html
<div class="data-[state=show]:animate-in data-[state=hide]:animate-out fade-in slide-in-from-top-8 fade-out slide-out-to-top-8 animate-duration-500" data-state="show">
  <p>
    If the element has the <code>data-state="show"</code> attribute,<br />
    fade in from 0% opacity,<br />
    slide from top by 8 spacing units (2rem),<br />
    with a 500ms duration.
  </p>
  <p>
    If the element has the <code>data-state="hide"</code> attribute,<br />
    fade out to 0% opacity,<br />
    slide to top by 8 spacing units (2rem),<br />
    with a 500ms duration.
  </p>
</div>
```

**Blur + spin (enter/exit):**

```html
<div class="animate-in blur-in-8 spin-in-45 animate-duration-300">...</div>
<div class="animate-out blur-out-8 spin-out-45 animate-duration-300">...</div>
```

**Controlling delay / repeat / fill mode / direction:**

```html
<div class="animate-in fade-in animate-duration-300 delay-150 repeat-2 direction-alternate fill-mode-both">...</div>
```

**Accordion / Collapsible:**

```html
<div class="overflow-hidden data-[state=open]:accordion-down data-[state=closed]:accordion-up" data-state="open">
  ...
</div>

<div class="overflow-hidden data-[state=open]:collapsible-down data-[state=closed]:collapsible-up" data-state="open">
  ...
</div>
```

## Notes on Compatibility

> **NOTE:** This package follows a CSS-first approach and focuses on providing enter/exit transforms, keyframes, and ready-to-use animations.
> It may not be a 100% drop-in replacement for every existing animation library. If you notice any inconsistencies, feel free to contribute to this repository by opening a pull request.