tailwind-animations

tailwind-animations（使用者技能）

帮助用户在自己的应用中使用 tailwind-animations 包。此技能不适用于为插件 monorepo 做贡献。

**包：**适用于 Tailwind CSS v4 的纯 CSS 工具类（peer：任意 tailwindcss@4）。
网站 / 演示： https://tailwind-animations.com
Playground（组合并分享 URL）： https://tailwind-animations.com/playground/
Agent 文档（优先使用 Markdown）： https://tailwind-animations.com/llms-full.md

适用场景

• 使用 Tailwind 类添加入场、离场和强调动画
• npm install 后配置 tailwind-animations
• 为原生 <dialog> 设置打开 / 关闭动画
• 由滚动或视图驱动的 CSS 动画
• 为溢出 / 滚动容器的边缘添加淡出效果（scroll-mask-*）
• 自定义滑动距离、时长、延迟、步数、迭代次数和填充模式

在使用该包的项目中安装

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

/* globals.css / app.css — Tailwind v4 */
@import "tailwindcss";
@import "tailwind-animations";

要求： Tailwind CSS v4。
旧版 Tailwind v3： @midudev/[email protected]（已弃用；API 不同）。

不要注册 JS 插件。此包是纯 CSS。

核心用法

动画名称前加上 animate-：

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

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

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

组合修饰符

目标	类
时长	animate-duration-faster|fast|normal|slow|slower 或 animate-duration-100…1000 或 animate-duration-[777ms]
延迟	animate-delay-0…1000、none 或任意值
步数（复古效果）	animate-steps-none|retro|normal|modern
迭代次数	animate-iteration-count-once|twice|thrice|infinite|none
填充模式	animate-fill-mode-none|forwards|backwards|both
缓动	animate-ease、animate-ease-in、animate-ease-out、animate-ease-in-out、animate-linear
贝塞尔预设	animate-bezier-sine-in、animate-bezier-quad-out、animate-bezier-back-in-out、…
方向	animate-direction-normal|reverse|alternate|alternate-reverse
播放状态	animate-play-running、animate-play-paused
滑动距离	animate-slide-distance-[50%]、animate-slide-distance-[6rem]（默认移动距离为 20px）

对话框（原生 <dialog>）

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

另有：animate-dialog-fade、animate-dialog-zoom、animate-dialog-from-bottom|left|right、animate-dialog-duration-*。

滚动 / 视图时间线

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

滚动遮罩（溢出边缘淡出）

由 animation-timeline: scroll() 驱动的纯 CSS 边缘淡出效果。应用于滚动容器（需要设置溢出）。

<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-x-from-90% overflow-x-auto">…</div>
<div class="scroll-mask-r-from-[calc(100%-2rem)] overflow-x-auto">…</div>

目标	类
全部四条边	scroll-mask、scroll-mask-from-*
垂直轴	scroll-mask-y、scroll-mask-y-from-*
水平轴	scroll-mask-x、scroll-mask-x-from-*
单条边	scroll-mask-t|b|l|r、scroll-mask-t-from-*（等等）

默认淡出终点为 80%（到 80% 为止保持不透明，然后在边缘变为透明）。需要浏览器支持 animation-timeline: scroll()。

动画目录（79）

用作 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

Playground（用于探索）

https://tailwind-animations.com/playground/

可分享的查询参数：a（动画）、d（时长）、delay、s（步数）、i（迭代次数）、f（填充）、p（预设：box|button|card|text）。

示例：
https://tailwind-animations.com/playground/?a=jelly&d=700&delay=100&i=infinite&p=card

Agent 阅读文档站点

优先使用 Markdown，而不是抓取 HTML：

• https://tailwind-animations.com/llm.txt
• https://tailwind-animations.com/index.md
• https://tailwind-animations.com/playground.md
• https://tailwind-animations.com/llms-full.md
• https://tailwind-animations.com/llms.txt

最佳实践

1. 优先使用 transform + opacity 动画（目录中的大多数动画）。
2. 注意 blurred-fade-in（filter: blur）在移动设备上的开销较大。
3. 无限循环（pulse、horizontal-vibration、rotational-wave 等）会持续播放动画，请谨慎使用；在宿主应用中遵循 prefers-reduced-motion。
4. 当存在 transform 工具类时，不要为布局属性（width、height、top）添加动画。
5. Tailwind 支持任意值：animate-duration-[1.2s]、animate-slide-distance-[10rem]。

反模式

• 为此包安装 JS Tailwind 插件（v1 中不存在此插件）。
• 在 Tailwind v3 中使用最新版本的包（请改用 @midudev/[email protected]）。
• 未查阅文档或 Playground 就臆造目录中不存在的类名。
• 将此技能与 monorepo 贡献者工作流混为一谈（不在讨论范围内）。

快速示例

列表项依次进入

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

单次强调

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

模态框

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

带边缘渐隐效果的可滚动面板

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