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
  • Installation
• Usage
  • Enter/Exit Animations
    • Base Classes
    • Parameter Classes
    • Transform Classes
  • Ready-to-Use Animations
• Examples
• Notes on Compatibility

Getting Started

Installation

1. Install the package with pnpm:

   pnpm install -D @retronew/unocss-preset-animate

2. Add the preset to your UnoCSS configuration file (typically uno.config.ts or similar):

   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:

   <!-- 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:

<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:

<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):

<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:

<div class="animate-in fade-in animate-duration-300 delay-150 repeat-2 direction-alternate fill-mode-both">...</div>

Accordion / Collapsible:

<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.