# Technical Documentation: unovue/inspira-ui

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/unovue/inspira-ui)

### Overview (`README.md`)

<p align="center">
  <a href="https://github.com/unovue/inspira-ui">
    <img src="./logo.png" alt="Logo" width="150" />
  </a>
</p>
<h1 align="center">
  Inspira UI
</h1>
<p align="center">
  <b>Build beautiful websites using Vue & Nuxt.</b><br>
  A curated collection of beautifully designed, reusable components for Vue & Nuxt.
</p>

<p align="center">
  <a href="https://github.com/unovue/inspira-ui/stargazers">
    <img alt="GitHub stars" src="https://img.shields.io/github/stars/unovue/inspira-ui?style=social">
  </a>
  <a href="https://github.com/unovue/inspira-ui/blob/main/LICENSE.md">
    <img alt="License" src="https://img.shields.io/badge/License-MIT-yellow.svg">
  </a>  
</p>

<p align="center">🌐 Available Languages</h2>

<p align="center">
  <a href="README.md">🇺🇸 English</a> |
  <a href="README_CN.md">🇨🇳 Chinese</a> |
  <a href="README_IT.md">🇮🇹 Italian</a>
</p>

---

Welcome to [**Inspira UI**](https://inspira-ui.com), a community-driven project that brings the beauty and functionality of both [Aceternity UI](https://ui.aceternity.com) and [Magic UI](https://magicui.design) to the [Vue](https://vuejs.org) & [Nuxt](https://nuxt.com) ecosystem! While this project draws inspiration from these sources, it also includes unique custom components contributed by the community and created by us.
For **Chinese version** visit [here](README_CN.md).

## ✨ About Inspira UI

Inspira UI is a collection of elegant, ready-to-use Vue components designed to be flexible and easy to integrate. Rather than being a traditional component library, it allows you to pick, customize, and adapt components as needed, giving you the freedom to shape them to fit your unique project requirements.

## 🚀 Why Inspira UI?

Inspira UI was created to fill a gap in the Vue community by providing a set of components with the aesthetics and functionality of both Aceternity UI and Magic UI. Our goal is to empower developers to build beautiful applications more efficiently while adding our own custom and community-driven designs.

## 🎯 Key Features

- **Free and Open Source**: Completely [open source](https://github.com/unovue/inspira-ui) under the MIT license.
- **Highly Configurable**: Tailor components to your specific design needs. Check out our [configuration guide](/api/configuration).
- **Diverse Component Range**: A broad selection of [components](/components), inspired by Aceternity UI, Magic UI, and custom contributions, to help you build anything you imagine.
- **Mobile Optimized**: Designed to look great on all devices.
- **Nuxt Compatibility**: Fully compatible with [Nuxt](https://nuxt.com).

## 📚 Documentation

For full documentation and usage examples, visit [**Inspira UI Documentation**](https://inspira-ui.com).

## 🙏 Acknowledgments

A special thanks to:

- [Aceternity UI](https://ui.aceternity.com) for providing the inspiration and permission to adapt the original designs.
- [Magic UI](https://magicui.design) for its beautiful design inspiration.
- [shadcn-vue](https://www.shadcn-vue.com) for the Vue port of shadcn-ui and contributions to some components.
- [shadcn-docs-nuxt](https://github.com/ZTL-UwU/shadcn-docs-nuxt) for the beautifully crafted Nuxt documentation site.

## 👤 Author

Hi, I'm [Rahul Vashishtha](https://rahulv.dev). I started Inspira UI to bring a similar experience to the Vue ecosystem, inspired by Aceternity UI, Magic UI, and community contributions. I'm continuously working on it to make it better. Feel free to check out my work on [GitHub](https://github.com/rahul-vashishtha) and join me on this journey [here](https://github.com/unovue/inspira-ui)!

## 🌟 Contribute

We welcome contributions! If you want to suggest features, report bugs, or help improve the project, feel free to open an issue or submit a pull request on [GitHub](https://github.com/unovue/inspira-ui).

You can also follow this [Contribution Guide](https://inspira-ui.com/getting-started/contribution).

## Sponsorship

You can also support the development of the project by sponsoring the developer.

Support and sponsor the maintainer here: [Support Inspira UI](https://github.com/sponsors/rahul-vashishtha)

## Repo Stats



## Thanks to all the contributors 🙏

[](https://github.com/unovue/inspira-ui/graphs/contributors)

---

### Cn Index (`content/cn/index.md`)

---
seo:
  title: 适用于 Vue 和 Nuxt 的动画组件。
  description: 为 Vue 和 Nuxt 提供可直接复制的动画组件，包含实时预览、属性、API 文档和源码。
---

---

### En Index (`content/en/index.md`)

---
seo:
  title: Animated components for Vue and Nuxt.
  description: Copy ready animated components for Vue and Nuxt with live previews,
    props, API docs, and source code.
---

---

### Fr Index (`content/fr/index.md`)

---
seo:
  title: Composants animés pour Vue et Nuxt.
  description: Des composants animés prêts à copier pour Vue et Nuxt, avec aperçus,
    props, API et code source.
---

---

### Cn 1.Getting Started 1.Index (`content/cn/1.getting-started/1.index.md`)

---
title: 入门指南
description: 使用 shadcn-vue、motion-v 和 TailwindCSS 构建的可复用组件
icon: "lucide:info"
---

欢迎来到 [**Inspira UI**](https://inspira-ui.com)，一个为 [Vue](https://vuejs.org) 开发的社区驱动项目！

这个集合提供了精美设计的可复用组件，灵感来自 [Aceternity UI](https://ui.aceternity.com) 和 [Magic UI](https://magicui.design) 所做的令人惊艳的工作。虽然我们与这些项目没有官方联系，但我们已获得 Aceternity UI 创建者的许可来为 Vue 生态系统调整那些很棒的设计。此外，Inspira UI 还包括我们开发的自定义组件和社区贡献的组件。

### 关于 Inspira UI

Inspira UI **不是** 传统的组件库。相反，它是一个经过精心策划的优雅组件集合，您可以轻松集成到您的应用程序中。只需选择您需要的内容，复制代码，并根据您的项目进行自定义。代码是您可以随意使用和修改的！

### 为什么选择 Inspira UI？

这个项目起源于填补 Vue 社区中缺少的类似组件集合的空缺。Inspira UI 将 Aceternity UI、Magic UI 和自定义贡献的美感和功能带给 Vue，使开发人员更容易构建令人惊艳的应用程序。

### 主要特性

- 完全 [免费和开源](https://github.com/unovue/inspira-ui)
- 高度 [可配置](/cn/components) 以满足您的设计需求
- 范围广泛的 [组件](/cn/components) 可供选择
- 为移动使用优化
- 与 Nuxt 完全兼容

### 致谢

特别感谢：

- [Aceternity UI](https://ui.aceternity.com) 启发了这个 Vue 适配。
- [Magic UI](https://magicui.design) 提供了设计灵感。
- [shadcn-vue](https://www.shadcn-vue.com/) 提供了 shadcn-ui 的 Vue 端口并为文档贡献了一些组件。
- [shadcn-docs-nuxt](https://github.com/ZTL-UwU/shadcn-docs-nuxt) 精心打造的 Nuxt 文档网站。

### 关于我

嗨，我是 [Rahul Vashishtha](https://rahulv.dev)。我创建了 Inspira UI 以将类似的体验带给 Vue 生态系统，灵感来自 Aceternity UI、Magic UI 和社区贡献。我一直在努力改进它。欢迎查看我在 [GitHub](https://github.com/rahul-vashishtha) 上的工作，并在 [这里](https://github.com/unovue/inspira-ui) 加入我的旅程！

请随意探索并享受使用 Inspira UI 进行构建的乐趣！

---

### Cn 2.Components Index (`content/cn/2.components/index.md`)

---
title: 所有组件
description: Inspira UI 提供的所有组件的列表。
navigation: false
---

::ComponentsList
::

---

### Cn 3.Changelogs Index (`content/cn/3.changelogs/index.md`)

---
title: 更新日志
description: Inspira UI 的主要组件新增、修复和版本里程碑。
navigation: false
---

::InspiraChangelog
::

---

### En 1.Getting Started 1.Index (`content/en/1.getting-started/1.index.md`)

---
title: Getting Started
description: Reusable components built with shadcn-vue, motion-v, and TailwindCSS
icon: "lucide:info"
---

Welcome to [**Inspira UI**](https://inspira-ui.com), a community-driven project for [Vue](https://vuejs.org)!

This collection offers beautifully designed, reusable components, taking inspiration from the amazing work done on both [Aceternity UI](https://ui.aceternity.com) and [Magic UI](https://magicui.design). While we're not officially affiliated with these projects, we have received permission from Aceternity UI's creator to adapt those fantastic designs for the Vue ecosystem. Additionally, Inspira UI includes custom components developed by us and contributed by the community.

### About Inspira UI

Inspira UI is **not** a traditional component library. Instead, it's a curated collection of elegant components you can easily integrate into your applications. Simply pick what you need, copy the code, and customize it to fit your project. The code is yours to use and modify as you like!

### Why Inspira UI?

This project began to fill a gap in the Vue community for a similar set of components. Inspira UI brings the beauty and functionality of Aceternity UI, Magic UI, and custom contributions to Vue, making it easier for developers to build stunning applications.

### Key Features

- Completely [free and open source](https://github.com/unovue/inspira-ui)
- Highly [configurable](/components) to meet your design needs
- A wide range of [components](/components) to choose from
- Optimized for mobile use
- Fully compatible with Nuxt

### Acknowledgments

Special thanks to:

- [Aceternity UI](https://ui.aceternity.com) for inspiring this Vue adaptation.
- [Magic UI](https://magicui.design) for their design inspiration.
- [shadcn-vue](https://www.shadcn-vue.com/) for the Vue port of shadcn-ui and contributing some components for docs.
- [shadcn-docs-nuxt](https://github.com/ZTL-UwU/shadcn-docs-nuxt) for the beautifully crafted Nuxt documentation site.

### About Me

Hi, I'm [Rahul Vashishtha](https://rahulv.dev). I started Inspira UI to bring a similar experience to the Vue ecosystem, inspired by Aceternity UI, Magic UI, and community contributions. I'm continuously working on it to make it better. Feel free to check out my work on [GitHub](https://github.com/rahul-vashishtha) and join me on this journey [here](https://github.com/unovue/inspira-ui)!

Feel free to explore and enjoy building with Inspira UI!

---

### En 2.Components Index (`content/en/2.components/index.md`)

---
title: All Components
description: List of all the components provided by Inspira UI.
navigation: false
---

::ComponentsList
::

---

### En 3.Changelogs Index (`content/en/3.changelogs/index.md`)

---
title: Changelog
description: Major component additions, fixes, and release milestones for Inspira UI.
navigation: false
---

::InspiraChangelog
::

---

### Fr 1.Getting Started 1.Index (`content/fr/1.getting-started/1.index.md`)

---
title: Commencer
description: Composants réutilisables construits avec shadcn-vue, motion-v et TailwindCSS
icon: "lucide:info"
---

Bienvenue à [**Inspira UI**](https://inspira-ui.com), un projet communautaire pour [Vue](https://vuejs.org) !

Cette collection propose des composants magnifiquement conçus et réutilisables, s'inspirant du travail fantastique réalisé à la fois sur [Aceternity UI](https://ui.aceternity.com) et [Magic UI](https://magicui.design). Bien que nous ne soyons pas officiellement affiliés à ces projets, nous avons reçu la permission du créateur d'Aceternity UI d'adapter ces designs fantastiques pour l'écosystème Vue. De plus, Inspira UI inclut des composants personnalisés développés par nous et contribués par la communauté.

### À propos d'Inspira UI

Inspira UI n'est **pas** une bibliothèque de composants traditionnelle. Au lieu de cela, c'est une collection curée de composants élégants que vous pouvez facilement intégrer à vos applications. Choisissez simplement ce dont vous avez besoin, copiez le code et personnalisez-le selon votre projet. Le code est vôtre à utiliser et modifier comme bon vous semble !

### Pourquoi Inspira UI ?

Ce projet a commencé pour combler une lacune dans la communauté Vue pour un ensemble similaire de composants. Inspira UI apporte la beauté et la fonctionnalité d'Aceternity UI, Magic UI et des contributions personnalisées à Vue, facilitant aux développeurs la création d'applications magnifiques.

### Caractéristiques clés

- Complètement [gratuit et open source](https://github.com/unovue/inspira-ui)
- Hautement [configurable](/fr/components) pour répondre à vos besoins de conception
- Une large gamme de [composants](/fr/components) parmi lesquels choisir
- Optimisé pour l'utilisation mobile
- Entièrement compatible avec Nuxt

### Remerciements

Merci spécial à :

- [Aceternity UI](https://ui.aceternity.com) pour avoir inspiré cette adaptation Vue.
- [Magic UI](https://magicui.design) pour leur inspiration de conception.
- [shadcn-vue](https://www.shadcn-vue.com/) pour le port Vue de shadcn-ui et pour avoir contribué certains composants pour la documentation.
- [shadcn-docs-nuxt](https://github.com/ZTL-UwU/shadcn-docs-nuxt) pour le site de documentation Nuxt magnifiquement conçu.

### À mon sujet

Bonjour, je suis [Rahul Vashishtha](https://rahulv.dev). J'ai créé Inspira UI pour apporter une expérience similaire à l'écosystème Vue, inspiré par Aceternity UI, Magic UI et les contributions de la communauté. Je travaille continuellement dessus pour l'améliorer. N'hésitez pas à consulter mon travail sur [GitHub](https://github.com/rahul-vashishtha) et rejoignez-moi dans ce voyage [ici](https://github.com/unovue/inspira-ui) !

N'hésitez pas à explorer et profitez de la création avec Inspira UI !

---

### Fr 2.Components Index (`content/fr/2.components/index.md`)

---
title: Tous les composants
description: Liste de tous les composants fournis par Inspira UI.
navigation: false
---

::ComponentsList
::

---

### Fr 3.Changelogs Index (`content/fr/3.changelogs/index.md`)

---
title: Journal des modifications
description: Principaux ajouts de composants, correctifs et jalons de version d'Inspira UI.
navigation: false
---

::InspiraChangelog
::

---

### Cn 1.Getting Started .Navigation.Yml (`content/cn/1.getting-started/.navigation.yml`)

title: 入门指南
icon: lucide:rocket
navigation.redirect: /cn/getting-started/introduction

---

### Cn 1.Getting Started 2.Installation (`content/cn/1.getting-started/2.installation.md`)

---
title: 安装
description: 如何在你的应用中安装 Inspira UI。
icon: "lucide:play"
---

本指南将帮助你在 Vue 或 Nuxt 应用中安装并配置 Inspira UI 组件。

::warning
如果你正在使用 Tailwind CSS v3，**[请在这里查看 Inspira UI v1](https://v1.inspira-ui.com)。**
::

## 开始使用 Inspira UI

::steps

### 配置 `tailwindcss`

首先，请按照 [此指南](https://tailwindcss.com/docs/installation) 安装 `tailwindcss`。

### 添加依赖

安装以下所需的辅助库。

::code-group

```bash [npm]
npm install @vueuse/core motion-v tw-animate-css @inspira-ui/plugins
```

```bash [pnpm]
pnpm install @vueuse/core motion-v tw-animate-css @inspira-ui/plugins
```

```bash [bun]
bun add @vueuse/core motion-v tw-animate-css @inspira-ui/plugins
```

```bash [yarn]
yarn add @vueuse/core motion-v tw-animate-css @inspira-ui/plugins
```

::

请参考此指南，在 [Vue 或 Nuxt](https://motion.dev/docs/vue) 中配置 `motion-v`。

### 更新你的 `main.css` 文件

::tip
如果你正在使用 `shadcn-vue` 或 ，可以跳过此步骤
::

将以下代码添加到你的 `main.css` 文件中，用于配置组件所需的变量：

::tabs{.w-full}
:::tabs-item{icon="simple-icons:nuxt" label="Nuxt UI"}

:::::code-collapse

```
/* Detailed source-code truncated for AI context efficiency. */
```

:::::

:::
:::tabs-item{icon="simple-icons:tailwindcss" label="Other TailwindCSS Kit"}

:::::code-collapse

```
/* Detailed source-code truncated for AI context efficiency. */
```

:::::

:::
::

::

::tip{class="mt-12" icon="tabler:check"}
太棒了！你的项目现在已经配置完成，可以使用 Inspira UI 了。
::

### 可选：添加图标支持

许多 Inspira UI 组件和示例会使用 `<Icon>` 组件和 Iconify 图标。虽然这是可选的，但我们强烈推荐安装，以获得更好的使用体验。

要在你的 Vue.js 或 Nuxt.js 项目中添加图标支持，请参考 [Iconify Vue 指南](https://iconify.design/docs/icon-components/vue/)。

### 开始使用 Inspira UI 🚀

现在，你可以在项目中开始使用 Inspira UI 组件了。选择你需要的组件，复制代码，并将其集成到你的应用中。

---

### Cn 1.Getting Started 3.Contribution (`content/cn/1.getting-started/3.contribution.md`)

---
title: 如何贡献
description: 遵循以下指南以确保顺利协作
icon: "lucide:scroll-text"
---

感谢您有兴趣为 **Inspira UI** 项目做出贡献！您的贡献帮助使这个项目对每个人都更好。请花一点时间阅读这些指南，以确保顺畅的协作。

## 目录

1. [入门](#入门)
2. [行为准则](#行为准则)
3. [如何贡献](#如何贡献)
   - [报告 Bug](#报告-bug)
   - [建议改进](#建议改进)
   - [添加新组件](#添加新组件)
4. [项目结构](#项目结构)
5. [风格指南](#风格指南)
   - [编码标准](#编码标准)
   - [组件格式](#组件格式)
   - [提交消息](#提交消息)
6. [文档指南](#文档指南)
   - [单文件组件](#单文件组件)
   - [多文件组件](#多文件组件)
7. [测试](#测试)
8. [许可证](#许可证)

---

## 入门

- **Fork 仓库**：在 GitHub 上创建项目的个人副本。
- **克隆 Fork**：将您的 fork 仓库克隆到本地机器。
- **创建分支**：为您的贡献创建新分支 (`git checkout -b feature/YourFeatureName`)。
- **安装依赖**：运行 `pnpm install` 以安装所有必要的依赖。

## 行为准则

通过参与此项目，您同意遵守 [行为准则](./4.code-of-conduct.md)，该准则旨在营造开放和欢迎的环境。

## 如何贡献

### 报告 Bug

如果您发现 bug，请打开一个 [issue](https://github.com/unovue/inspira-ui/issues){:target="\_blank"} 并包括：

- 清晰而描述性的标题。
- 重现问题的步骤。
- 预期和实际结果。
- 截图或代码片段（如适用）。

### 建议改进

我们欢迎新功能或改进的建议。请打开一个 [issue](https://github.com/unovue/inspira-ui/issues){:target="\_blank"} 并包括：

- 清晰而描述性的标题。
- 改进的详细说明。
- 任何相关的示例或模型。

### 添加新组件

我们感谢为库添加新组件的贡献。请确保：

- 该组件通常有用，并与项目目标一致。
- 该组件与 **Nuxt** 和 **Vue** 兼容。
- 您遵循下面列出的编码和文档指南。
- 您为您的组件包括单元测试。

#### 组件指南

1. **创建或更新 `index.ts`**  
   `components/content/inspira/ui/<component-folder-name>/` 下的每个文件夹都应该有一个 `index.ts`，导出所有 Vue 文件。例如：

   ```ts
   // index.ts
   export { default as Book } from "./Book.vue";
   export { default as BookDescription } from "./BookDescription.vue";
   export { default as BookHeader } from "./BookHeader.vue";
   export { default as BookTitle } from "./BookTitle.vue";
   ```

2. **注册表依赖项：**
   如果您的新组件依赖（或使用）其他 Inspira UI 组件，您必须更新 `~/scripts/crawl-content.ts` 中的 `COMPONENT_DEPENDENCIES` 映射以反映这些关系。这帮助库理解当用户通过 CLI 添加组件时应该一起安装哪些组件。

3. **仅限 Nuxt 的功能：**
   如果您的新组件或其示例使用仅限 Nuxt 的功能（如 `<ClientOnly>`），请在文档中提及。这确保用户知道在 Nuxt 外部使用该组件时可能存在限制或额外步骤。

   这确保用户可以通过 CLI 安装该组件，并且所有依赖项都正确声明。

4. **避免外部组件：**
   创建组件时，避免使用不属于核心 Vue.js 生态系统的外部 UI 组件（如 `<UiButton>` 或类似）。

5. **显式导入：**
   即使您在开发过程中使用 Nuxt 的自动导入功能，也始终在组件代码中包含显式导入。这确保与没有自动导入的 Vue.js 用户的兼容性。例如：

   ```vue
   <script setup lang="ts">
   import { useWindowSize } from "@vueuse/core";
   import { onMounted, ref } from "vue";
   // 包含所有导入明确
   ```

---

### Cn 1.Getting Started 4.Code Of Conduct (`content/cn/1.getting-started/4.code-of-conduct.md`)

---
title: 行为准则
description: 行为准则阐述了我们对参与者行为的期望以及不可接受行为的后果。
icon: "lucide:award"
---

## 简介

我们致力于为所有涉及 **Inspira UI** 项目的人员提供友好、安全和欢迎的环境。本行为准则阐述了我们对参与者行为的期望以及不可接受行为的后果。

## 我们的承诺

为了促进开放和包容的社区，我们承诺使参与我们的项目和社区对每个人来说都是无骚扰的体验，无论：

- 年龄
- 体型
- 残疾
- 种族
- 性别认同和表达
- 经验水平
- 国籍
- 个人外观
- 种族
- 宗教
- 性取向和认同

## 预期行为

我们社区中的所有参与者都应该：

- **尊重他人**：对他人表现出同情和善良。
- **体谅他人**：记住您的行为和言语会影响他人。
- **善于合作**：共同努力以实现共同目标。
- **有效沟通**：使用清晰和建设性的语言。
- **展现专业精神**：专业行动并为您的行为承担责任。

## 不可接受行为

以下行为在我们社区中被认为是不可接受的：

- **骚扰和歧视**：包括贬低性评论、辱骂或不受欢迎的性关注。
- **滥用和威胁**：任何形式的言语或书面滥用、恐吓或威胁。
- **网络骚扰和侮辱**：旨在扰乱对话的煽动性或侮辱性言论。
- **不尊重的沟通**：包括过度谩骂、大声喊叫（全大写）或打断他人。
- **人身攻击**：以骚扰或贬低他人为意图针对个人的行为。

## 报告指南

如果您经历或目睹不可接受的行为，或有其他问题，请尽快通过联系我们的 **Discord 频道** 上的项目维护者来报告：

[Inspira UI Discord 频道](https://discord.gg/Xbh5DwJRc9)

在报告事件时，请包括：

- **您的联系信息**：您的 Discord 用户名或任何首选的联系方式。
- **涉及人员的名称**：涉及个人的真实姓名或用户名。
- **事件描述**：对发生情况的清晰简洁的说明。
- **支持证据**：任何相关消息、截图或有助于我们理解情况的上下文。

所有报告将被保密处理。

## 实施

项目维护者负责确保遵守本行为准则，并将采取适当措施应对被认为不可接受的任何行为。措施可能包括：

- 向违规者发出私下警告。
- 临时或永久禁止参与项目和 Discord 频道。
- 删除违反行为准则的贡献。

## 范围

本行为准则适用于所有项目空间，包括但不限于：

- GitHub 仓库
- 问题跟踪器
- Pull Request
- 项目相关论坛和聊天频道
- 与项目相关的社交媒体互动
- 官方 **Inspira UI Discord 频道**

当个人在公共空间代表项目或其社区时也适用。

## 上诉流程

任何因违反纪律而受到处罚的个人有权通过在行动后一周内通过 **Discord 频道** 联系项目维护者来对决定提出上诉。将审查上诉并告知最终决定。

## 隐私

所有不可接受行为的报告将谨慎处理。我们将尊重举报者和被告的隐私。

## 致谢

我们感谢所有贡献者和社区成员帮助创造积极的环境。本行为准则改编自开源社区中使用的最佳实践和指南。

## 联系信息

如果您对本行为准则有任何问题或疑虑，请通过我们的 **Discord 频道** 联系项目维护者：

[Inspira UI Discord 频道](https://discord.gg/Xbh5DwJRc9)

---

### En 1.Getting Started .Navigation.Yml (`content/en/1.getting-started/.navigation.yml`)

title: Getting started
icon: lucide:rocket
navigation.redirect: /getting-started/introduction

---

### En 1.Getting Started 2.Installation (`content/en/1.getting-started/2.installation.md`)

---
title: Installation
description: How to install Inspira UI in your app.
icon: "lucide:play"
---

This guide will help you install and set up Inspira UI components in your Vue or Nuxt application.

::warning
If you are using Tailwind CSS v3, **[Checkout Inspira UI v1 here](https://v1.inspira-ui.com).**
::

## Getting Started with Inspira UI

::steps

### Set up `tailwindcss`

To begin, install `tailwindcss` using this [Vite install guide for Vue](https://tailwindcss.com/docs/installation) or using this [framework-specific guide for Nuxt](https://tailwindcss.com/docs/installation/framework-guides/nuxt).

### Add dependencies

Install following supporting libraries.

::code-group

```bash [npm]
npm install @vueuse/core motion-v tw-animate-css @inspira-ui/plugins
```

```bash [pnpm]
pnpm install @vueuse/core motion-v tw-animate-css @inspira-ui/plugins
```

```bash [bun]
bun add @vueuse/core motion-v tw-animate-css @inspira-ui/plugins
```

```bash [yarn]
yarn add @vueuse/core motion-v tw-animate-css @inspira-ui/plugins
```

::

Follow this guide to setup `motion-v` on [Vue or Nuxt](https://motion.dev/docs/vue).

### Update your `main.css` file

::tip
Skip this step if you are using `shadcn-vue`.
::

Add the following code to your `main.css` file, this setup the variable required for the components:

::tabs{.w-full}
:::tabs-item{icon="simple-icons:nuxt" label="Nuxt UI"}

:::::code-collapse

```
/* Detailed source-code truncated for AI context efficiency. */
```

:::::

:::
:::tabs-item{icon="simple-icons:tailwindcss" label="Other TailwindCSS Kit"}

:::::code-collapse

```
/* Detailed source-code truncated for AI context efficiency. */
```

:::::

:::
::

::

::tip{class="mt-12" icon="tabler:check"}
Great job! Your project is now configured to use Inspira UI.
::

### Optional: Add Icon Support

A variety of Inspira UI components and demos utilize the `<Icon>` component with Iconify icons. Although optional, we recommend installing it for an optimal experience.

To add icon support to your Vue.js or Nuxt.js project, please follow the [Iconify Vue guide](https://iconify.design/docs/icon-components/vue/).

### Start Using Inspira UI 🚀

Now, you can start using Inspira UI components in your project. Choose the components you need, copy the code, and integrate them into your application.

---

### En 1.Getting Started 3.Contribution (`content/en/1.getting-started/3.contribution.md`)

---
title: How To Contribute
description: Follow the following guidelines to ensure the smooth collaboration
icon: "lucide:scroll-text"
---

Thank you for your interest in contributing to the **Inspira UI** project! Your contributions help make this project better for everyone. Please take a moment to read through these guidelines to ensure a smooth collaboration.

## Table of Contents

1. [Getting Started](#getting-started)
2. [Code of Conduct](#code-of-conduct)
3. [How to Contribute](#how-to-contribute)
   - [Reporting Bugs](#reporting-bugs)
   - [Suggesting Enhancements](#suggesting-enhancements)
   - [Adding New Components](#adding-new-components)
4. [Project Structure](#project-structure)
5. [Style Guidelines](#style-guidelines)
   - [Coding Standards](#coding-standards)
   - [Component Format](#component-format)
   - [Commit Messages](#commit-messages)
6. [Documentation Guidelines](#documentation-guidelines)
   - [Single-File Components](#single-file-components)
   - [Multi-File Components](#multi-file-components)
7. [Testing](#testing)
8. [License](#license)

---

## Getting Started

- **Fork the Repository**: Create a personal fork of the project on GitHub.
- **Clone Your Fork**: Clone your forked repository to your local machine.
- **Create a Branch**: Create a new branch for your contribution (`git checkout -b feature/YourFeatureName`).
- **Install Dependencies**: Run `pnpm install` to install all necessary dependencies.

## Code of Conduct

By participating in this project, you agree to abide by the [Code of Conduct](./4.code-of-conduct.md), which aims to foster an open and welcoming environment.

## How to Contribute

### Reporting Bugs

If you find a bug, please open an [issue](https://github.com/unovue/inspira-ui/issues){:target="\_blank"} and include:

- A clear and descriptive title.
- Steps to reproduce the issue.
- Expected and actual results.
- Screenshots or code snippets, if applicable.

### Suggesting Enhancements

We welcome suggestions for new features or improvements. Please open an [issue](https://github.com/unovue/inspira-ui/issues){:target="\_blank"} and include:

- A clear and descriptive title.
- A detailed description of the enhancement.
- Any relevant examples or mockups.

### Adding New Components

We appreciate contributions that add new components to the library. Please ensure that:

- The component is generally useful and aligns with the project's goals.
- The component is compatible with both **Nuxt** and **Vue**.
- You follow the coding and documentation guidelines outlined below.
- You include unit tests for your component.

#### Components guidelines

1. **Create or Update `index.ts`**  
   Each folder under `components/content/inspira/ui/<component-folder-name>/` should have an `index.ts` that exports all Vue files. For example:

   ```ts
   // index.ts
   export { default as Book } from "./Book.vue";
   export { default as BookDescription } from "./BookDescription.vue";
   export { default as BookHeader } from "./BookHeader.vue";
   export { default as BookTitle } from "./BookTitle.vue";
   ```

2. **Registry Dependencies:**
   If your new component depends on (or uses) other Inspira UI components, you must update the `COMPONENT_DEPENDENCIES` map in `~/scripts/crawl-content.ts` to reflect those relationships. This helps the library understand which components should be installed together when a user adds them via the CLI.

3. **Nuxt-Only Features:**
   If your new component or its example uses Nuxt-only features such as `<ClientOnly>`, please mention this in the documentation. This ensures users know there may be limitations or additional steps when using the component outside of Nuxt.

   This ensures that users can install the component through the CLI and that all dependencies are properly declared.

4. **Avoid External Components:**
   When creating components, avoid using external UI components (like `<UiButton>` or similar) that are not part of the core Vue.js ecosystem.

5. **Explicit Imports:**
   Even if you're using Nuxt's auto-imports feature during development, always include explicit imports in your component code. This ensures compatibility with Vue.js users who don't have auto-imports. For example:

   ```vue
   <script setup lang="ts">
   import { useWindowSize } from "@vueuse/core";
   import { onMounted, ref } from "vue";
   // Include all imports explicitly
   </script>
   ```

6. **Icon Usage:**
   If you need icons in your demos or components, use the built-in `<Icon>` component rather than pasting raw SVGs into your templates.

## Project Structure

Understanding the project structure is crucial for effective contribution:

- **Components Directory**:
  - Main components should be placed in `components/content/inspira/ui/<component-folder-name>/`.
    - Include an `index.ts` file to export each component within that folder.
  - Example components should be placed in `components/content/inspira/examples/<component-folder-name>/`.
- **Documentation**:
  - Documentation files are located in the `content/2.components/<category>/` directory.
  - After adding a component, write its documentation in this directory.

## Style Guidelines

### Coding Standards

- **Language**: All components should be written in **Vue.js** with TypeScript support.
- **Styling**: Use **Tailwind CSS** classes for styling whenever possible.
- **Naming Conventions**: Use `PascalCase` for component names and filenames.

### Component Format

Your Vue components should adhere to the following structure:

```vue

<script lang="ts" setup>
// Your script code goes here
</script>


<template>
  
</template>


<style scoped>
/* Your styles go here */
</style>
```

**Props typing and code style**

Refer to this Vue.js documentation page -> [https://vuejs.org/api/sfc-script-setup#type-only-props-emit-declarations](https://vuejs.org/api/sfc-script-setup#type-only-props-emit-declarations)

```vue
<script lang="ts" setup>
const { msg = "hello", labels = ["one", "two"] } = defineProps<Props>();

// DON'T ⛔️
const props = defineProps({
  whatever: { type: String, required: true },
  optional: { type: String, default: "default" },
});

const props = withDefaults(defineProps<Props>(), { optional: "default" });

// DO ✅
interface Props {
  whatever: string;
  optional?: string;
}

// Or DO ✅ Props destructure (v3.5+)
interface Props {
  msg?: string;
  labels?: string[];
}
</script>
```

**Constants, interfaces, types and variants**

For reusability purposes, you can also add an `index.ts` file at the root of the component folder to export interfaces, constants, and other useful code elements. Keep in mind that developers will copy and paste the component code into their projects, so it should be very easy to customize according to their standards.

Constants have to be `CAPS_CAMEL_CASE` in order to identify them clearly inside the code. And `prefix` them.
Please never use Enums; use `{} as const` instead. 😘

```typescript
// DON'T ⛔️
const Direction = { Top: 'top'} as const
const ComponentNameDirection = { Top: 'top'} as const

// DON'T ⛔️
enum COMPONENT_NAME_DIRECTION_WRONG = { Top = 'top'};

// DO ✅
import type { ObjectValues } from "@/lib/utils";
export const COMPONENT_NAME_DIRECTION = { Top: 'top', Bottom: 'bottom'} as const

//Types and Interfaces should use CamelCase to differentiate them from constants and variables.
export type ComponentNameDirection = ObjectValues<typeof COMPONENT_NAME_DIRECTION>;

interface {
   direction: ComponentNameDirection; //Enforce correct value : 'top' or 'bottom'
}
```

You can check the `PatternBackground` component files `components/content/inspira/ui/pattern-background` for a complete example.

**Notes:**

- Use `<script lang="ts" setup>` for TypeScript and the Composition API.
- Keep styles scoped to prevent conflicts.
- Ensure compatibility with both **Nuxt** and **Vue**.

### Commit Messages

- Use the [Conventional Commits](https://www.conventionalcommits.org/) format.
- Begin with a type (`feat`, `fix`, `docs`, etc.) followed by a short description.
- Example: `feat: add TextHoverEffect component`

## Documentation Guidelines

Proper documentation is crucial for users to understand and effectively use the components. Follow these guidelines when adding documentation for new components.

### Steps to Add a New Component

1. **Create the Component**
   - Place the main component in `components/content/inspira/ui/<component-folder-name>/`.
   - Follow the [Component Format](#component-format) specified above.
   - If the component requires examples or demos, add demo components to `components/content/inspira/examples/<component-folder-name>/`.

2. **Write Documentation**
   - Add a new Markdown file in `content/2.components/<category>/` for your component's documentation.
   - Use the appropriate template based on whether your component is single-file or multi-file (see below).
   - Add utility classes section if applicable to your component.
   - Mention the **Credits** and source if the component is ported from any other UI library or taken inspiration from any other source.

3. **Ensure Compatibility**
   - Test your component in both **Nuxt** and **Vue** environments.

### Single-File Components

For components that are contained within a single `.vue` file, use the following template:

1. **Front Matter**

   Begin with YAML front matter that includes the `title` and `description`:

   ```yaml
   ---
   title: Your Component Title
   description: A brief description of what your component does.
   ---
   ```

2. **Preview Section**

   Use the `ComponentLoader` to display a live preview of the component. The `id` should be set to the folder name of your component in `components/content/inspira/examples/`. In case, there is no folder, then `id` is not required.

   ```markdown
   ::ComponentLoader{label="Preview" componentName="YourComponentDemo" type="examples" id="your-component-folder-name"}
   ::
   ```

3. **Alerts**

   If your component has special requirements or dependencies, add an alert section before the installation instructions:

   ```markdown
   ::alert{type="info"}
   **Note:** This component requires `package-name` as a dependency.
   ::

   ::alert{type="warning"}
   **Note:** This component uses the `nuxt-only` syntax with the `<ClientOnly>`. If you are not using Nuxt, you can simply remove it.
   ::
   ```

4. **Installation**

   Include both CLI and manual installation instructions. If additional setup is required (e.g., dependencies, Tailwind config updates), use a stepper to list all needed steps.

   ```markdown
   ## Install using CLI

   ::InstallationCli{componentId="your-component-folder-name"}
   ::

   ## Install Manually

   Copy and paste the following code

   ::CodeViewer{filename="YourComponent.vue" language="vue" componentName="YourComponent" type="ui" id="your-component-folder-name"}
   ::
   ```

5. **API Documentation**

   Provide a table listing all props:

   ```markdown
   ## API

   | Prop Name | Type      | Default | Description                    |
   | --------- | --------- | ------- | ------------------------------ |
   | `prop1`   | `string`  | `''`    | Description of prop1.          |
   | `prop2`   | `number`  | `0`     | Description of prop2.          |
   | `prop2`   | `?number` | `0`     | Description of prop2 optional. |
   ```

**Example:**

```markdown
---
title: Text Hover Effect
description: A text hover effect that animates and outlines gradient on hover, as seen on x.ai
---

::ComponentLoader{label="Preview" componentName="TextHoverEffectDemo" type="examples"}
::

::alert{type="warning"}
This component uses the `nuxt-only` syntax with the `<ClientOnly>`. If you are not using Nuxt, you can simply remove it.
::

## Install using CLI

::InstallationCli{componentId="text-hover-effect"}
::

## Install Manually

Copy and paste the following code

::CodeViewer{filename="TextHoverEffect.vue" language="vue" componentName="TextHoverEffect" type="ui" id="text-hover-effect"}
::

## API

| Prop Name     | Type     | Default  | Description                                               |
| ------------- | -------- | -------- | --------------------------------------------------------- |
| `text`        | `string` | Required | The text to be displayed with the hover effect.           |
| `duration`    | `number` | `200`    | The duration of the mask transition animation in seconds. |
| `strokeWidth` | `number` | `0.75`   | The width of the text stroke.                             |
| `opacity`     | `number` | `null`   | The opacity of the text.                                  |
```

In this example, the `id` used in both `ComponentLoader`, `CodeViewer` and `InstallationCli` is `text-hover-effect`, which matches the folder name where the component and its demo are stored.

### Multi-File Components

For components that consist of multiple files, such as a main component and several sub-components or variants, use the following template:

1. **Front Matter**

   Begin with YAML front matter:

   ```yaml
   ---
   title: Your Components Group Title
   description: A brief description of what this group of components does.
   ---
   ```

2. **Preview Sections**

   Include multiple `ComponentLoader` sections for each example or variant. The `id` should be set to the folder name of your component in `components/content/inspira/examples/`.

   ```markdown
   ::ComponentLoader{label="Preview" componentName="ComponentVariantDemo" type="examples" id="your-component-folder-name"}
   ::
   ```

3. **Alerts**

   If your component has special requirements or dependencies, add an alert section before the installation instructions:

   ```markdown
   ::alert{type="info"}
   **Note:** This component requires `package-name` as a dependency.
   ::

   ::alert{type="warning"}
   **Note:** This component uses the `nuxt-only` syntax with the `<ClientOnly>`. If you are not using Nuxt, you can simply remove it.
   ::
   ```

4. **Installation**

   Include both CLI and manual installation instructions. If additional setup is required (e.g., dependencies, Tailwind config updates), use a stepper to list all needed steps.

   ```markdown
   ## Install using CLI

   ::InstallationCli{componentId="your-component-folder-name"}
   ::

   ## Install Manually

   Copy and paste the following code in the same folder

   ::code-group

   :CodeViewerTab{label="YourComponent.vue" language="vue" componentName="YourComponent" type="ui" id="your-component-folder-name"}
   :CodeViewerTab{filename="YourComponent2.vue" language="vue" componentName="YourComponent2" type="ui" id="your-component-folder-name"}

   ::
   ```

5. **API Documentation**

   Provide comprehensive API documentation covering all components:

   ```markdown
   ## API

   | Prop Name | Type     | Default | Description                             |
   | --------- | -------- | ------- | --------------------------------------- |
   | `prop1`   | `string` | `''`    | Description applicable to all variants. |
   ```

**Example:**

```
/* Detailed source-code truncated for AI context efficiency. */
```

## Testing

- **Unit Tests**: Write unit tests for your component if applicable.
- **Cross-Environment Testing**: Ensure that your component works correctly in both **Nuxt** and **Vue** environments.
- **Visual Testing**: Check the component visually to ensure it renders correctly.
- **CLI Installation Testing**: After updating the registry with `pnpm build:registry`, test the component installation in a separate project by referencing the local registry URL. For example:
  ```sh
  npx shadcn-vue@latest add "https://localhost:3000/r/<component-name>"
  ```

## Additional Notes

- **Component Names**: Use `PascalCase` for component filenames and names.
- **IDs**: In `CodeViewer`, `CodeViewerTab`, and `ComponentLoader`, the `id` parameter should be set to the **folder name** where the component is stored in `components/content/inspira/ui/<component-folder-name>/` and `components/content/inspira/examples/<component-folder-name>/`. This helps in correctly linking the code and examples in the documentation.
- **Demo Components**: For each component, create a corresponding `Demo` component used in the `ComponentLoader` for previews, and place it in `components/content/inspira/examples/<component-folder-name>/`.
- **Localization**: If your component supports multiple languages, include details in the documentation.

## License

By contributing, you agree that your contributions will be licensed under the [MIT License](https://github.com/unovue/inspira-ui/blob/main/LICENSE){:target="\_blank"}.

---

### En 1.Getting Started 4.Code Of Conduct (`content/en/1.getting-started/4.code-of-conduct.md`)

---
title: Code of Conduct
description: Code of Conduct outlines our expectation for participant behavior as well as consequences for unacceptable conduct.
icon: "lucide:award"
---

## Introduction

We are committed to providing a friendly, safe, and welcoming environment for everyone involved in the **Inspira UI** project. This Code of Conduct outlines our expectations for participant behavior as well as the consequences for unacceptable conduct.

## Our Pledge

In the interest of fostering an open and inclusive community, we pledge to make participation in our project and community a harassment-free experience for everyone, regardless of:

- Age
- Body size
- Disability
- Ethnicity
- Gender identity and expression
- Level of experience
- Nationality
- Personal appearance
- Race
- Religion
- Sexual identity and orientation

## Expected Behavior

All participants in our community are expected to:

- **Be Respectful**: Show empathy and kindness towards others.
- **Be Considerate**: Remember that your actions and words affect others.
- **Be Collaborative**: Work together to achieve common goals.
- **Communicate Effectively**: Use clear and constructive language.
- **Demonstrate Professionalism**: Act professionally and take responsibility for your actions.

## Unacceptable Behavior

The following behaviors are considered unacceptable within our community:

- **Harassment and Discrimination**: Including derogatory comments, slurs, or unwanted sexual attention.
- **Abuse and Threats**: Any form of verbal or written abuse, intimidation, or threats.
- **Trolling and Insults**: Provocative or insulting remarks intended to disrupt conversations.
- **Disrespectful Communication**: Including excessive profanity, shouting (using all caps), or interrupting others.
- **Personal Attacks**: Targeting an individual with the intent to harass or belittle.

## Reporting Guidelines

If you experience or witness unacceptable behavior, or have any other concerns, please report it as soon as possible by contacting the project maintainers on our **Discord channel**:

[Inspira UI Discord Channel](https://discord.gg/Xbh5DwJRc9)

When reporting an incident, please include:

- **Your Contact Information**: Your Discord username or any preferred method of contact.
- **Names of Those Involved**: Real names or usernames of the individuals involved.
- **Description of the Incident**: A clear and concise account of what happened.
- **Supporting Evidence**: Any relevant messages, screenshots, or context that can help us understand the situation.

All reports will be handled confidentially.

## Enforcement

Project maintainers are responsible for ensuring compliance with this Code of Conduct and will take appropriate action in response to any behavior that is deemed unacceptable. Actions may include:

- A private warning to the offender.
- Temporary or permanent ban from participation in the project and Discord channel.
- Removal of contributions that violate the Code of Conduct.

## Scope

This Code of Conduct applies to all project spaces, including but not limited to:

- GitHub repositories
- Issue trackers
- Pull requests
- Project-related forums and chat channels
- Social media interactions pertaining to the project
- The official **Inspira UI Discord channel**

It also applies when an individual is representing the project or its community in public spaces.

## Appeal Process

Any individual who is subjected to disciplinary action has the right to appeal the decision by contacting the project maintainers through the **Discord channel** within one week of the action. The appeal will be reviewed, and a final decision will be communicated.

## Privacy

All reports of unacceptable behavior will be handled with discretion. We will respect the privacy of the reporter and the accused.

## Acknowledgments

We thank all contributors and community members for helping to create a positive environment. This Code of Conduct is adapted from best practices and guidelines used in open-source communities.

## Contact Information

For questions or concerns about this Code of Conduct, please contact the project maintainers on our **Discord channel**:

[Inspira UI Discord Channel](https://discord.gg/Xbh5DwJRc9)

---

### Fr 1.Getting Started .Navigation.Yml (`content/fr/1.getting-started/.navigation.yml`)

title: Commencer
icon: lucide:rocket
navigation.redirect: /fr/getting-started/introduction

---

### Fr 1.Getting Started 2.Installation (`content/fr/1.getting-started/2.installation.md`)

---
title: Installation
description: Comment installer Inspira UI dans votre application.
icon: "lucide:play"
---

Ce guide vous aidera à installer et configurer les composants Inspira UI dans votre application Vue ou Nuxt.

::warning
Si vous utilisez Tailwind CSS v3, **[consultez Inspira UI v1 ici](https://v1.inspira-ui.com).**
::

## Commencer avec Inspira UI

::steps

### Configurez `tailwindcss`

Pour commencer, installez `tailwindcss` en utilisant [ce guide](https://tailwindcss.com/docs/installation).

### Ajoutez les dépendances

Installez les bibliothèques de support suivantes.

::code-group

```bash [npm]
npm install @vueuse/core motion-v tw-animate-css @inspira-ui/plugins
```

```bash [pnpm]
pnpm install @vueuse/core motion-v tw-animate-css @inspira-ui/plugins
```

```bash [bun]
bun add @vueuse/core motion-v tw-animate-css @inspira-ui/plugins
```

```bash [yarn]
yarn add @vueuse/core motion-v tw-animate-css @inspira-ui/plugins
```

::

Suivez ce guide pour configurer `motion-v` sur [Vue ou Nuxt](https://motion.dev/docs/vue).

### Mettez à jour votre fichier `main.css`

::tip
Ignorez cette étape si vous utilisez `shadcn-vue`.
::

Ajoutez le code suivant à votre fichier `main.css` pour configurer les variables requises pour les composants :

::tabs{.w-full}
:::tabs-item{icon="simple-icons:nuxt" label="Nuxt UI"}

:::::code-collapse

```
/* Detailed source-code truncated for AI context efficiency. */
```

:::::

:::
:::tabs-item{icon="simple-icons:tailwindcss" label="Other TailwindCSS Kit"}

:::::code-collapse

```
/* Detailed source-code truncated for AI context efficiency. */
```

:::::

:::
::

::

::tip{class="mt-12" icon="tabler:check"}
Bravo ! Votre projet est maintenant configuré pour utiliser Inspira UI.
::

### Optionnel : Ajoutez le support des icônes

Une variété de composants et de démos d'Inspira UI utilisent le composant `<Icon>` avec les icônes Iconify. Bien que facultatif, nous vous recommandons de l'installer pour une expérience optimale.

Pour ajouter le support des icônes à votre projet Vue.js ou Nuxt.js, veuillez suivre le [guide Iconify Vue](https://iconify.design/docs/icon-components/vue/).

### Commencez à utiliser Inspira UI 🚀

Maintenant, vous pouvez commencer à utiliser les composants d'Inspira UI dans votre projet. Choisissez les composants dont vous avez besoin, copiez le code et intégrez-les à votre application.

---

### Fr 1.Getting Started 3.Contribution (`content/fr/1.getting-started/3.contribution.md`)

---
title: Comment contribuer
description: Suivez les directives suivantes pour assurer une collaboration harmonieuse
icon: "lucide:scroll-text"
---

Merci de votre intérêt à contribuer au projet **Inspira UI** ! Vos contributions aident à rendre ce projet meilleur pour tout le monde. Veuillez prendre un moment pour lire ces directives afin d'assurer une collaboration harmonieuse.

## Table des matières

1. [Commencer](#commencer)
2. [Code de conduite](#code-de-conduite)
3. [Comment contribuer](#comment-contribuer)
   - [Signaler des bogues](#signaler-des-bogues)
   - [Suggérer des améliorations](#suggérer-des-améliorations)
   - [Ajouter de nouveaux composants](#ajouter-de-nouveaux-composants)
4. [Structure du projet](#structure-du-projet)
5. [Directives de style](#directives-de-style)
   - [Normes de codage](#normes-de-codage)
   - [Format des composants](#format-des-composants)
   - [Messages de commit](#messages-de-commit)
6. [Directives de documentation](#directives-de-documentation)
   - [Composants à fichier unique](#composants-à-fichier-unique)
   - [Composants multi-fichiers](#composants-multi-fichiers)
7. [Tests](#tests)
8. [Licence](#licence)

---

## Commencer

- **Forkez le dépôt** : Créez un fork personnel du projet sur GitHub.
- **Clonez votre fork** : Clonez votre dépôt forké sur votre machine locale.
- **Créez une branche** : Créez une nouvelle branche pour votre contribution (`git checkout -b feature/YourFeatureName`).
- **Installez les dépendances** : Exécutez `pnpm install` pour installer toutes les dépendances nécessaires.

## Code de conduite

En participant à ce projet, vous acceptez de respecter le [Code de conduite](./4.code-of-conduct.md), qui vise à créer un environnement ouvert et accueillant.

## Comment contribuer

### Signaler des bogues

Si vous trouvez un bogue, veuillez ouvrir une [issue](https://github.com/unovue/inspira-ui/issues){:target="\_blank"} et inclure :

- Un titre clair et descriptif.
- Les étapes pour reproduire le problème.
- Les résultats attendus et réels.
- Des captures d'écran ou des extraits de code, si applicable.

### Suggérer des améliorations

Nous accueillons les suggestions de nouvelles fonctionnalités ou améliorations. Veuillez ouvrir une [issue](https://github.com/unovue/inspira-ui/issues){:target="\_blank"} et inclure :

- Un titre clair et descriptif.
- Une description détaillée de l'amélioration.
- Tous les exemples ou maquettes pertinents.

### Ajouter de nouveaux composants

Nous apprécions les contributions qui ajoutent de nouveaux composants à la bibliothèque. Veuillez vous assurer que :

- Le composant est généralement utile et s'aligne avec les objectifs du projet.
- Le composant est compatible avec **Nuxt** et **Vue**.
- Vous suivez les directives de codage et de documentation décrites ci-dessous.
- Vous incluez des tests unitaires pour votre composant.

#### Directives des composants

1. **Créer ou mettre à jour `index.ts`**  
   Chaque dossier sous `components/content/inspira/ui/<component-folder-name>/` doit avoir un `index.ts` qui exporte tous les fichiers Vue. Par exemple :

   ```ts
   // index.ts
   export { default as Book } from "./Book.vue";
   export { default as BookDescription } from "./BookDescription.vue";
   export { default as BookHeader } from "./BookHeader.vue";
   export { default as BookTitle } from "./BookTitle.vue";
   ```

2. **Dépendances du registre :**
   Si votre nouveau composant dépend (ou utilise) d'autres composants Inspira UI, vous devez mettre à jour la carte `COMPONENT_DEPENDENCIES` dans `~/scripts/crawl-content.ts` pour refléter ces relations. Cela aide la bibliothèque à comprendre quels composants devraient être installés ensemble lorsqu'un utilisateur les ajoute via la CLI.

3. **Fonctionnalités spécifiques à Nuxt :**
   Si votre nouveau composant ou son exemple utilise des fonctionnalités spécifiques à Nuxt telles que `<ClientOnly>`, veuillez le mentionner dans la documentation. Cela garantit que les utilisateurs savent qu'il peut y avoir des limitations ou des étapes supplémentaires lors de l'utilisation du composant en dehors de Nuxt.

   Cela garantit que les utilisateurs peuvent installer le composant via la CLI et que toutes les dépendances sont correctement déclarées.

4. **Évitez les composants externes :**
   Lors de la création de composants, évitez d'utiliser des composants d'interface utilisateur externes (comme `<UiButton>` ou similaires) qui ne font pas partie de l'écosystème principal de Vue.js.

5. **Importations explicites :**
   Même si vous utilisez la fonction d'auto-importation de Nuxt pendant le développement, incluez toujours les importations explicites dans le code de votre composant. Cela garantit la compatibilité avec les utilisateurs de Vue.js qui n'ont pas d'auto-importations. Par exemple :

   ```vue
   <script setup lang="ts">
   import { useWindowSize } from "@vueuse/core";
   import { onMounted, ref } from "vue";
   // Incluez tous les imports explicitement
   ```

---

### Fr 1.Getting Started 4.Code Of Conduct (`content/fr/1.getting-started/4.code-of-conduct.md`)

---
title: Code de conduite
description: Le code de conduite décrit nos attentes en matière de comportement des participants ainsi que les conséquences d'une conduite inacceptable.
icon: "lucide:award"
---

## Introduction

Nous nous engageons à fournir un environnement amical, sûr et accueillant pour tous ceux impliqués dans le projet **Inspira UI**. Ce code de conduite décrit nos attentes en matière de comportement des participants ainsi que les conséquences d'une conduite inacceptable.

## Notre engagement

Dans l'intérêt de favoriser une communauté ouverte et inclusive, nous nous engageons à rendre la participation à notre projet et à notre communauté une expérience sans harcèlement pour tous, indépendamment de :

- L'âge
- La taille du corps
- Le handicap
- L'ethnicité
- L'identité et l'expression de genre
- Le niveau d'expérience
- La nationalité
- L'apparence personnelle
- La race
- La religion
- L'identité et l'orientation sexuelles

## Comportement attendu

Tous les participants de notre communauté sont attendus de :

- **Être respectueux** : Montrez de l'empathie et de la gentillesse envers les autres.
- **Être attentif** : Rappelez-vous que vos actions et vos paroles affectent les autres.
- **Être collaboratif** : Travaillez ensemble pour atteindre des objectifs communs.
- **Communiquer efficacement** : Utilisez un langage clair et constructif.
- **Faire preuve de professionnalisme** : Agissez profesionnellement et assumez la responsabilité de vos actions.

## Comportement inacceptable

Les comportements suivants sont considérés comme inacceptables dans notre communauté :

- **Harcèlement et discrimination** : Y compris les commentaires péjoratifs, les insultes ou l'attention sexuelle non désirée.
- **Abus et menaces** : Toute forme d'abus verbal ou écrit, d'intimidation ou de menaces.
- **Trolling et insultes** : Les remarques provocatrices ou insultantes destinées à perturber les conversations.
- **Communication irrespectueuse** : Y compris les jurons excessifs, les cris (en majuscules) ou l'interruption des autres.
- **Attaques personnelles** : Cibler une personne avec l'intention de la harceler ou de l'humilier.

## Directives de signalement

Si vous expérimentez ou témoin un comportement inacceptable, ou si vous avez d'autres préoccupations, veuillez le signaler dès que possible en contactant les mainteneurs du projet sur notre **canal Discord** :

[Canal Discord Inspira UI](https://discord.gg/Xbh5DwJRc9)

Lors du signalement d'un incident, veuillez inclure :

- **Vos informations de contact** : Votre nom d'utilisateur Discord ou tout autre moyen de contact préféré.
- **Noms des personnes impliquées** : Noms réels ou noms d'utilisateur des individus impliqués.
- **Description de l'incident** : Un récit clair et concis de ce qui s'est passé.
- **Preuves de soutien** : Tous les messages pertinents, captures d'écran ou contexte qui peuvent nous aider à comprendre la situation.

Tous les rapports seront traités de manière confidentielle.

## Application

Les mainteneurs du projet sont responsables du respect de ce code de conduite et prendront les mesures appropriées en réponse à tout comportement jugé inacceptable. Les actions peuvent inclure :

- Un avertissement privé au contrevenant.
- Une interdiction temporaire ou permanente de participation au projet et au canal Discord.
- La suppression des contributions qui violent le code de conduite.

## Champ d'application

Ce code de conduite s'applique à tous les espaces du projet, notamment mais sans limitation :

- Dépôts GitHub
- Suivi des problèmes
- Demandes de fusion
- Forums de projet et canaux de chat
- Interactions sur les réseaux sociaux concernant le projet
- Le **canal Discord officiel d'Inspira UI**

Il s'applique également lorsqu'une personne représente le projet ou sa communauté dans les espaces publics.

## Processus d'appel

Toute personne faisant l'objet d'une action disciplinaire a le droit de contester la décision en contactant les mainteneurs du projet via le **canal Discord** dans un délai d'une semaine à compter de l'action. L'appel sera examiné et une décision finale sera communiquée.

## Confidentialité

Tous les rapports de comportement inacceptable seront traités avec discrétion. Nous respecterons la confidentialité du signataire et de l'accusé.

## Remerciements

Nous remercions tous les contributeurs et les membres de la communauté de nous aider à créer un environnement positif. Ce code de conduite s'inspire des meilleures pratiques et directives utilisées dans les communautés open source.

## Coordonnées

Pour des questions ou des préoccupations concernant ce code de conduite, veuillez contacter les mainteneurs du projet sur notre **canal Discord** :

[Canal Discord Inspira UI](https://discord.gg/Xbh5DwJRc9)

---

### Fr 3.Changelogs .Navigation.Yml (`content/fr/3.changelogs/.navigation.yml`)

title: Journaux des modifications
icon: carbon:update-now

---

### Cn 2.Components Backgrounds Aurora Background (`content/cn/2.components/backgrounds/aurora-background.md`)

---
title: 极光背景
description: 细腻的极光（南北极光）背景效果。
category: Background
tags: [css, tailwind, background, aceternity-ui]
---

::ComponentViewer{demoFile="AuroraBackgroundDemo.vue" config="AuroraBackgroundConfig" componentId="aurora-background" :componentFiles='["AuroraBackground.vue"]'}

#instructions

在 `main.css` 的 inline theme 中添加以下内容：

```css
@theme inline {
  --animate-aurora: aurora 60s linear infinite;
  @keyframes aurora {
    from {
      background-position:
        50% 50%,
        50% 50%;
    }
    to {
      background-position:
        350% 50%,
        350% 50%;
    }
  }
}
```

#api

## API

| 属性名           | 类型      | 默认值 | 描述                         |
| ---------------- | --------- | ------ | ---------------------------- |
| `class`          | `string`  | `-`    | 应用于组件的额外 CSS 类。    |
| `radialGradient` | `boolean` | `true` | 是否为背景应用径向渐变效果。 |

#credits

- 感谢 [Aceternity UI](https://ui.aceternity.com/components/aurora-background)。
- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi) 移植该组件。

::

---

### Cn 2.Components Backgrounds Black Hole Background (`content/cn/2.components/backgrounds/black-hole-background.md`)

---
title: 黑洞背景
description: 令人沉浸的画布背景效果，模拟扭曲的“黑洞”隧道，包含动画圆盘、放射线与粒子。
category: Background
tags: [css, tailwind, background, motion-v, canvas]
---

::ComponentViewer{demoFile="BlackHoleBackgroundDemo.vue" config="BlackHoleBackgroundConfig" componentId="bg-black-hole" :componentFiles='["BlackHoleBackground.vue"]'}

#api

## API

| 属性名             | 类型                       | 默认值          | 描述                       |
| ------------------ | -------------------------- | --------------- | -------------------------- |
| `strokeColor`      | `string`                   | `"#737373"`     | 同心圆与放射线的描边颜色。 |
| `numberOfLines`    | `number`                   | `50`            | 从中心发出的放射线数量。   |
| `numberOfDiscs`    | `number`                   | `50`            | 组成隧道的同心椭圆数量。   |
| `particleRGBColor` | `[number, number, number]` | `[255,255,255]` | 流向黑洞的微粒 RGB 颜色。  |
| `class`            | `string`                   | `""`            | 合并到根容器的额外工具类。 |

#credits

- 自定义生成艺术逻辑，灵感来自隧道/折跃动画。
- 使用 **Motion-V** 实现渐变漂移，并结合 Vue 3 组合式 API 控制生命周期。
- 考虑无障碍：画布通过 `aria-hidden` 仅作装饰。

::

---

### Cn 2.Components Backgrounds Bubbles Bg (`content/cn/2.components/backgrounds/bubbles-bg.md`)

---
title: 气泡背景
description: 具有漂浮气泡的动画背景。
category: Background
tags: [css, tailwind, background, threejs]
---

::ComponentViewer{demoFile="BubblesBgDemo.vue" config="BubblesBgConfig" componentId="bg-bubbles" :componentFiles='["BubblesBg.vue"]' dependencies="three" devDependencies="@types/three"}

#api

## API

| 属性名 | 类型     | 默认值 | 描述                         |
| ------ | -------- | ------ | ---------------------------- |
| `blur` | `number` | `0`    | 应用于背景的模糊量（像素）。 |

#credits

- 使用 [Three.js](https://threejs.org/) 库实现 3D 渲染与动画。
- 灵感来自 [Tresjs Experiment](https://lab.tresjs.org/experiments/overlay)。

::

---

### Cn 2.Components Backgrounds Cosmic Portal (`content/cn/2.components/backgrounds/cosmic-portal.md`)

---
title: 宇宙传送门
description: 使用 Three.js 构建的震撼 3D 传送门，包含发光环、漂浮水晶、空间扭曲和次元流体。
category: Background
tags: [css, tailwind, background, threejs, postprocessing]
---

::ComponentViewer{demoFile="CosmicPortalDemo.vue" config="CosmicPortalConfig" componentId="cosmic-portal" :componentFiles='["CosmicPortal.vue"]' dependencies="three postprocessing" devDependencies="@types/three"}

#api

## API

| 属性名             | 类型     | 默认值    | 描述                           |
| ------------------ | -------- | --------- | ------------------------------ |
| `portalComplexity` | `number` | `4`       | 控制传送门特效与几何的复杂度。 |
| `crystalCount`     | `number` | `12`      | 场景中漂浮水晶的数量。         |
| `primaryColor`     | `string` | `#9b59b6` | 传送门与背景辉光的主色。       |
| `secondaryColor`   | `string` | `#3498db` | 混合与辉光的辅色。             |
| `accentColor`      | `string` | `#e74c3c` | 用于能量与高光的强调色。       |
| `vortexColor`      | `string` | `#2ecc71` | 用于旋转漩涡与维度流的颜色。   |
| `rotationSpeed`    | `number` | `0.3`     | 物体旋转速度。                 |
| `bloomStrength`    | `number` | `1.2`     | 泛光后期处理强度。             |
| `bloomRadius`      | `number` | `0.7`     | 泛光半径。                     |
| `bloomThreshold`   | `number` | `0.2`     | 泛光可见性的阈值。             |
| `dimensionShift`   | `number` | `4`       | 着色器动画的次元扭曲程度。     |

#credits

- 灵感并移植自 [Techartist 的 Dimensional Portal](https://x.com/techartist_)。

::

---

### Cn 2.Components Backgrounds Falling Stars (`content/cn/2.components/backgrounds/falling-stars.md`)

---
title: 流星背景
description: 华丽的星空动画背景，带有发光和锐利拖尾效果。
category: Background
tags: [css, tailwind, background, canvas]
---

::ComponentViewer{demoFile="FallingStarsBgDemo.vue" config="FallingStarsBgConfig" componentId="bg-falling-stars" :componentFiles='["FallingStarsBg.vue"]'}

#api

## API

| 属性名  | 类型     | 默认值   | 描述                   |
| ------- | -------- | -------- | ---------------------- |
| `color` | `string` | `"#FFF"` | 星空中星星的颜色。     |
| `count` | `number` | `200`    | 动画中显示的星星数量。 |

#credits

- 灵感来自现代 Canvas 动画中的 3D 星空与拖尾效果。
- 感谢 [Prodromos Pantos](https://github.com/prpanto) 将原组件移植到 Vue & Nuxt。

::

---

### Cn 2.Components Backgrounds Flickering Grid (`content/cn/2.components/backgrounds/flickering-grid.md`)

---
title: 闪烁网格
description: 使用 Canvas 制作的闪烁网格背景，可通过 Tailwind CSS 完全自定义。
category: Background
tags: [css, tailwind, background, canvas, magic-ui]
---

::ComponentViewer{demoFile="FlickeringGridDemo.vue" config="FlickeringGridConfig" componentId="flickering-grid" :componentFiles='["FlickeringGrid.vue"]'}

#api

## API

| 属性名          | 类型     | 默认值         | 描述                   |
| --------------- | -------- | -------------- | ---------------------- |
| `squareSize`    | `number` | `4`            | 网格中每个方块的尺寸。 |
| `gridGap`       | `number` | `6`            | 方块之间的间距。       |
| `flickerChance` | `number` | `0.3`          | 方块闪烁的概率。       |
| `color`         | `string` | `rgb(0, 0, 0)` | 方块颜色。             |
| `width`         | `number` | `-`            | 画布宽度。             |
| `height`        | `number` | `-`            | 画布高度。             |
| `class`         | `string` | `-`            | 画布的额外 CSS 类。    |
| `maxOpacity`    | `number` | `0.2`          | 方块的最大不透明度。   |

#credits

- 感谢 [magicui flickering-grid](https://magicui.design/docs/components/flickering-grid) 组件。

::

---

### Cn 2.Components Backgrounds Interactive Grid Pattern (`content/cn/2.components/backgrounds/interactive-grid-pattern.md`)

---
title: 交互网格图案
description: 采用 SVG 制作的交互式网格背景，完全可自定义。
category: Background
tags: [css, tailwind, background, svg, magic-ui]
---

::ComponentViewer{demoFile="InteractiveGridPatternDemo.vue" config="InteractiveGridPatternConfig" componentId="interactive-grid-pattern" :componentFiles='["InteractiveGridPattern.vue"]' }

#api

## API

| 属性名             | 类型               | 默认值     | 描述                 |
| ------------------ | ------------------ | ---------- | -------------------- |
| `className`        | `string`           | -          | 组件样式的额外类名。 |
| `squaresClassName` | `string`           | -          | 方块样式的额外类名。 |
| `width`            | `number`           | `40`       | 方块宽度（像素）。   |
| `height`           | `number`           | `40`       | 方块高度（像素）。   |
| `squares`          | `[number, number]` | `[24, 24]` | 网格中方块的数量。   |

#credits

- 灵感来自 [MagicUI](https://magicui.design/docs/components/interactive-grid-pattern)。
- 感谢 [kalix127](https://github.com/kalix127) 移植该组件。

::

---

### Cn 2.Components Backgrounds Lamp Effect (`content/cn/2.components/backgrounds/lamp-effect.md`)

---
title: 灯光效果
description: 引人注目的灯光效果，包含圆锥渐变、聚光与发光线，带来沉浸式视觉体验。
category: Background
tags: [css, tailwind, background, aceternity-ui]
---

::ComponentViewer{demoFile="LampEffectDemo.vue" config="LampEffectConfig" componentId="lamp-effect" :componentFiles='["LampEffect.vue"]'}

#api

## API

| 属性名     | 类型     | 默认值 | 描述                          |
| ---------- | -------- | ------ | ----------------------------- |
| `delay`    | `number` | `0.5`  | 动画开始前的延迟（秒）。      |
| `duration` | `number` | `0.8`  | 动画持续时间（秒）。          |
| `class`    | `string` | `""`   | 用于自定义样式的额外 CSS 类。 |

#credits

- 移植自 [Aceternity UI](https://ui.aceternity.com/components/lamp-effect)

::

---

### Cn 2.Components Backgrounds Liquid Background (`content/cn/2.components/backgrounds/liquid-background.md`)

---
title: 液态背景
description: 使用 OGL 实现的响应式动态背景效果，基于 WebGL。
category: Background
tags: [css, tailwind, background, ogl, webgl]
---

::ComponentViewer{demoFile="LiquidBackgroundDemo.vue" config="LiquidBackgroundConfig" componentId="liquid-background" :componentFiles='["LiquidBackground.vue"]' dependencies="ogl"}

#api

## API

该组件无需外部 props，即可在挂载时动态渲染液态背景效果。

#credits

- 基于 [OGL](https://github.com/oframe/ogl) 库实现 3D 渲染。
- 灵感来自生成艺术图案。
- 使用 Vue 组合式 API 管理生命周期与状态。

::

---

### Cn 2.Components Backgrounds Neural Background (`content/cn/2.components/backgrounds/neural-background.md`)

---
title: 神经网络背景
description: 使用 OGL 与 GLSL 的动态着色器背景，呈现流动的神经质视觉效果。
category: Background
tags: [css, tailwind, background, ogl, webgl, cursify]
---

::ComponentViewer{demoFile="NeuralBgDemo.vue" config="NeuralBgConfig" componentId="bg-neural" :componentFiles='["NeuralBg.vue"]'}

#api

## API

| 属性名       | 类型     | 默认值 | 描述                               |
| ------------ | -------- | ------ | ---------------------------------- |
| `hue`        | `number` | `200`  | 背景颜色的基础色相（度数 0–360）。 |
| `saturation` | `number` | `0.8`  | 背景颜色的饱和度（0–1）。          |
| `chroma`     | `number` | `0.6`  | HSL 颜色的色度/亮度系数（0–1）。   |
| `class`      | `string` | `—`    | 可选，应用于画布的额外 CSS 类。    |

> 💡 组件默认使用全屏固定背景并设置 `pointer-events-none`。如需修改，可通过 `class` 属性覆写样式。

#credits

- 基于轻量级 WebGL 框架 [OGL](https://github.com/oframe/ogl) 构建。
- 数学与图案逻辑源自递归三角函数叠加。
- 移植自 [Cursify 的 Neural Glow Cursor](https://cursify.vercel.app/components/neural-glow)。

::

---

### Cn 2.Components Backgrounds Particle Whirlpool Bg (`content/cn/2.components/backgrounds/particle-whirlpool-bg.md`)

---
title: 粒子漩涡
description: 带有旋转粒子的动画背景。
category: Background
tags: [css, tailwind, background, threejs, postprocessing]
---

::ComponentViewer{demoFile="ParticleWhirlpoolBgDemo.vue" config="ParticleWhirlpoolBgConfig" componentId="bg-particle-whirlpool" :componentFiles='["ParticleWhirlpoolBg.vue"]' dependencies="three postprocessing" devDependencies="@types/three"}

#api

## API

| 属性名          | 类型     | 默认值 | 描述                          |
| --------------- | -------- | ------ | ----------------------------- |
| `class`         | `string` | `""`   | 用于自定义样式的额外 CSS 类。 |
| `blur`          | `number` | `0`    | 应用于背景的模糊量（像素）。  |
| `particleCount` | `number` | `2000` | 漩涡动画中的粒子数量。        |

#credits

- 使用 [Three.js](https://threejs.org/) 库实现 3D 渲染与动画。
- 灵感来自 [TroisJs](https://troisjs.github.io/examples/demos/3.html)。

::

---

### Cn 2.Components Backgrounds Particles Bg (`content/cn/2.components/backgrounds/particles-bg.md`)

---
title: 粒子背景
description: 粒子能为页面增加动态与沉浸感，营造深度、运动和交互的视觉效果。
category: Background
tags: [css, tailwind, background, magic-ui, canvas]
---

::ComponentViewer{demoFile="ParticlesBgDemo.vue" config="ParticlesBgConfig" componentId="particles-bg" :componentFiles='["ParticlesBg.vue"]'}

#api

## API

| 属性名      | 类型     | 默认值 | 描述                                       |
| ----------- | -------- | ------ | ------------------------------------------ |
| `color`     | `string` | `#FFF` | 粒子的十六进制颜色，支持 3 位或 6 位代码。 |
| `quantity`  | `number` | `100`  | 在画布上生成并显示的粒子数量。             |
| `staticity` | `number` | `50`   | 粒子随鼠标距离移动的程度，值越大移动越小。 |
| `ease`      | `number` | `50`   | 粒子运动的缓动程度，值越小越紧跟鼠标。     |

#credits

- 感谢 [Magic UI](https://magicui.design/docs/components/particles) 提供该组件。
- 感谢 [Prodromos Pantos](https://github.com/prpanto) 将原组件移植到 Vue & Nuxt。

::

---

### Cn 2.Components Backgrounds Pattern Background (`content/cn/2.components/backgrounds/pattern-background.md`)

---
title: 图案背景
description: 简单的动画图案背景，让版块更突出。
category: Background
tags: [css, tailwind, background, magic-ui]
---

::ComponentViewer{demoFile="PatternBackgroundDemo.vue" config="PatternBackgroundConfig" componentId="pattern-background" :componentFiles='["PatternBackground.vue", "index.ts"]' dependencies="class-variance-authority"}

#api

## API

| 属性名      | 类型                                                                                                   | 默认值    | 描述                                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------------------ | --------- | ----------------------------------------------------------------------------------------------------- |
| `animate`   | `boolean`                                                                                              | `false`   | 若设为 `true`，背景将有动画。                                                                         |
| `direction` | `top` \| `bottom` \| `left` \| `right` \| `top-left` \| `top-right` \| `bottom-left` \| `bottom-right` | `top`     | 动画移动方向。可使用常量 `PATTERN_BACKGROUND_DIRECTION`。                                             |
| `direction` | `grid` \| `dot`                                                                                        | `grid`    | 图案类型。可使用常量 `PATTERN_BACKGROUND_VARIANT`。                                                   |
| `size`      | `xs` \| `sm` \| `md` \| `lg`                                                                           | `md`      | 背景图案的大小。                                                                                      |
| `mask`      | `ellipse` \| `ellipse-top`                                                                             | `ellipse` | 在背景图案上添加遮罩。可使用常量 `PATTERN_BACKGROUND_MASK`。                                          |
| `speed`     | `number`                                                                                               | `10000`   | 动画时长（毫秒），数值越大动画越慢（`20000` 比 `5000` 更慢）。可使用常量 `PATTERN_BACKGROUND_SPEED`。 |

#credits

- 灵感来自 [Magic UI 的 Dot Pattern](https://magicui.design/docs/components/dot-pattern)。
- 灵感来自 [Magic UI 的 Grid Pattern](https://magicui.design/docs/components/grid-pattern)。
- 灵感来自 [Magic UI 的 Animated Grid Pattern](https://magicui.design/docs/components/animated-grid-pattern)。
- 感谢 [Nathan De Pachtere](https://nathandepachtere.com/) 移植该组件。

::

---

### Cn 2.Components Backgrounds Ribbon Background (`content/cn/2.components/backgrounds/ribbon-background.md`)

---
title: 丝带背景
description: 可配置颜色、旋转角度和透明度的分层动态丝带背景。
category: Background
tags: [css, tailwind, background, shader-toy, ogl, webgl]
badge: New
---

::ComponentViewer{demoFile="RibbonBackgroundDemo.vue" config="RibbonBackgroundConfig" componentId="ribbon-background" :componentFiles='["RibbonBackground.vue"]'}

#api

## API

| 属性名            | 类型       | 默认值                                                    | 描述                                  |
| ----------------- | ---------- | --------------------------------------------------------- | ------------------------------------- |
| `colors`          | `string[]` | `['#355070', '#6d597a', '#b56576', '#e56b6f', '#eaac8b']` | 分层丝带使用的五个 CSS 十六进制颜色。 |
| `backgroundColor` | `string`   | `'#282828'`                                               | 丝带后方渲染的 CSS 十六进制背景色。   |
| `transparent`     | `boolean`  | `false`                                                   | 将空白背景像素的 alpha 值设为 `0`。   |
| `enableShadows`   | `boolean`  | `true`                                                    | 启用重叠丝带层之间的阴影。            |
| `angle`           | `number`   | `0`                                                       | 以度为单位旋转整个丝带区域。          |
| `offsetX`         | `number`   | `0`                                                       | 以视口单位水平移动丝带区域。          |
| `offsetY`         | `number`   | `0`                                                       | 以视口单位垂直移动丝带区域。          |
| `speed`           | `number`   | `1`                                                       | 动画速度倍数。                        |
| `class`           | `string`   | `—`                                                       | 应用于全尺寸外层元素的附加类。        |

组件会填满最近的已定位父元素。请为父元素设置明确高度和 `position: relative`。

#credits

- 使用 Inspira UI Shader Toy Viewer 和 [OGL](https://github.com/oframe/ogl) 渲染。

::

---

### Cn 2.Components Backgrounds Ripple (`content/cn/2.components/backgrounds/ripple.md`)

---
title: 涟漪
description: 用于突出元素的动画涟漪效果。
category: Background
tags: [css, tailwind, background, magic-ui]
---

::ComponentViewer{demoFile="RippleDemo.vue" config="RippleConfig" componentId="ripple" :componentFiles='["Ripple.vue", "RippleCircle.vue", "RippleContainer.vue"]'}

#api

## API

| 属性名                        | 类型     | 默认值      | 描述                               |
| ----------------------------- | -------- | ----------- | ---------------------------------- |
| `baseCircleSize`              | `number` | `210`       | 主圆的尺寸（像素）。               |
| `baseCircleOpacity`           | `number` | `0.24`      | 主圆的不透明度。                   |
| `spaceBetweenCircle`          | `number` | `70`        | 每个涟漪圆之间的间距（像素）。     |
| `circleOpacityDowngradeRatio` | `number` | `0.03`      | 每个后续涟漪圆的不透明度递减比例。 |
| `circleClass`                 | `string` | `undefined` | 用于额外样式的圆形 CSS 类。        |
| `waveSpeed`                   | `number` | `80`        | 波纹动画速度（毫秒）。             |
| `numberOfCircles`             | `number` | `7`         | 渲染的涟漪圆数量。                 |

#credits

- 感谢 [Magic UI](https://magicui.design/docs/components/ripple)。
- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi) 移植该组件。
- 感谢 [Nathan De Pachtere](https://nathandepachtere.com/) 更新该组件。

::

---

### Cn 2.Components Backgrounds Silk Background (`content/cn/2.components/backgrounds/silk-background.md`)

---
title: 丝绸背景
description: 柔和流动的着色器背景，灵感来自丝绸纹理与运动，基于 ShaderToy。
category: Background
tags: [css, tailwind, background, shader-toy, ogl, webgl]
---

::ComponentViewer{demoFile="SilkBackgroundDemo.vue" config="SilkBackgroundConfig" componentId="bg-silk" :componentFiles='["SilkBackground.vue"]'}

#api

## API

| 属性名       | 类型     | 默认值 | 描述                                                  |
| ------------ | -------- | ------ | ----------------------------------------------------- |
| `hue`        | `number` | `300`  | 丝绸纹理的基础色相（度数 0–360）。                    |
| `saturation` | `number` | `0.5`  | 颜色饱和度（0–1）。                                   |
| `brightness` | `number` | `1`    | 输出颜色的亮度倍数（建议 0–2）。                      |
| `speed`      | `number` | `1`    | 动画速度倍数（例如 `2` 表示两倍速度）。               |
| `class`      | `string` | `—`    | 可选，应用于容器 div 的额外 CSS 类（如 z-index 等）。 |

> 💡 组件默认使用全屏绝对定位容器，可通过 `class` 覆写定位与层级。

#credits

- 改编自 Giorgi Azmaipharashvili 在 [ShaderToy](https://www.shadertoy.com/view/X3yXRd) 的着色器（MIT License）。
- 灵感来自丝绸纹理与自然流动的运动模式。

::

---

### Cn 2.Components Backgrounds Singularity Background (`content/cn/2.components/backgrounds/singularity-background.md`)

---
title: 奇点背景
description: 一个基于着色器的背景。
category: Background
tags: [css, tailwind, background, shader-toy, webgl, ogl]
---

::ComponentViewer{demoFile="SingularityBackgroundDemo.vue" config="SingularityBackgroundConfig" componentId="bg-singularity" :componentFiles='["SingularityBackground.vue"]'}

#api

## API

| 属性名             | 类型     | 默认值 | 描述                                        |
| ------------------ | -------- | ------ | ------------------------------------------- |
| `hue`              | `number` | `0`    | 分形纹理的基础色相（0–360 度）。            |
| `saturation`       | `number` | `1`    | 颜色的饱和度（0–1）。                       |
| `brightness`       | `number` | `1`    | 输出颜色的亮度倍增（推荐 0–2）。            |
| `speed`            | `number` | `1`    | 动画的速度倍增。                            |
| `mouseSensitivity` | `number` | `0.5`  | 控制对鼠标移动的响应程度（0–5）。           |
| `damping`          | `number` | `1`    | 阻尼系数，用于平滑纹理的扭曲（0–1）。       |
| `class`            | `string` | `-`    | 容器 div 的额外 CSS 类（例如 z-index 等）。 |

> 💡 该组件适用于全屏或大段落的背景。针对现代 GPU 优化，但在低端设备上可能较耗资源。

#credits

- 改编自 [这个 ShaderToy 着色器](https://www.shadertoy.com/view/3csSWB)。

::

---

### Cn 2.Components Backgrounds Snowfall Bg (`content/cn/2.components/backgrounds/snowfall-bg.md`)

---
title: 雪花背景
description: 优雅的雪花飘落动画背景。
category: Background
tags: [css, tailwind, background, canvas]
---

::ComponentViewer{demoFile="SnowfallBgDemo.vue" config="SnowfallBgConfig" componentId="snowfall-bg" :componentFiles='["SnowfallBg.vue"]'}

#api

## API

| 属性名      | 类型     | 默认值 | 描述                      |
| ----------- | -------- | ------ | ------------------------- |
| `color`     | `string` | `#FFF` | 雪花的十六进制颜色。      |
| `quantity`  | `number` | `100`  | 显示的雪花数量。          |
| `speed`     | `number` | `1`    | 雪花下落速度。            |
| `maxRadius` | `number` | `3`    | 雪花的最大半径。          |
| `minRadius` | `number` | `1`    | 雪花的最小半径。          |
| `class`     | `string` | `null` | 应用于容器的额外 CSS 类。 |

#credits

- 灵感来自自然的降雪效果。

::

---

### Cn 2.Components Backgrounds Sparkles (`content/cn/2.components/backgrounds/sparkles.md`)

---
title: 闪光
description: 可配置的闪光组件，可作为背景或独立使用。
category: Background
tags: [css, tailwind, background, canvas]
---

::ComponentViewer{demoFile="SparklesDemo.vue" config="SparklesConfig" componentId="sparkles" :componentFiles='["Sparkles.vue"]'}

#api

## API

| 属性名            | 类型     | 默认值      | 描述                                          |
| ----------------- | -------- | ----------- | --------------------------------------------- |
| `background`      | `string` | `'#0d47a1'` | 容器背景色。使用 `transparent` 可透视父元素。 |
| `particleColor`   | `string` | `'#ffffff'` | 粒子颜色，接受任何合法 CSS 颜色值。           |
| `minSize`         | `number` | `1`         | 粒子最小尺寸（像素）。                        |
| `maxSize`         | `number` | `3`         | 粒子最大尺寸（像素）。                        |
| `speed`           | `number` | `4`         | 移动速度倍数，值越大移动越快。                |
| `particleDensity` | `number` | `120`       | 渲染的粒子数量，值越大粒子越密集。            |

#credits

- 感谢 [M Atif](https://github.com/atif0075) 移植该组件。
- 移植自 [Aceternity UI 的 Sparkles](https://ui.aceternity.com/components/sparkles)。

::

---

### Cn 2.Components Backgrounds Stars Background (`content/cn/2.components/backgrounds/stars-background.md`)

---
title: 星空背景
description: 使用分层运动与随机星位的视差星空动画背景。
category: Background
tags: [css, tailwind, background, animate-ui, motion-v]
---

::ComponentViewer{demoFile="StarsBackgroundDemo.vue" config="StarsBackgroundConfig" componentId="bg-stars" :componentFiles='["StarsBackground.vue"]'}

#api

## API

| 属性名       | 类型            | 默认值                           | 描述                                       |
| ------------ | --------------- | -------------------------------- | ------------------------------------------ |
| `factor`     | `number`        | `0.05`                           | 鼠标视差移动的倍数。                       |
| `speed`      | `number`        | `50`                             | 星层垂直循环动画的基础速度（秒）。         |
| `transition` | `SpringOptions` | `{ stiffness: 50, damping: 20 }` | 视差响应的弹簧物理配置。                   |
| `starColor`  | `string`        | `"#fff"`                         | 星星颜色，接受任何合法 CSS 颜色。          |
| `class`      | `string`        | `—`                              | 可选，容器 div 的额外类（如 z-index 等）。 |

> 💡 组件包裹了一个插槽，可在背景上放置其他 UI 元素。

#credits

- 移植自 [Animate UI](https://animate-ui.com/docs/backgrounds/stars)

::

---

### Cn 2.Components Backgrounds Stractium Background (`content/cn/2.components/backgrounds/stractium-background.md`)

---
title: Stractium 背景
description: 基于着色器的背景，灵感来自复杂分形与有机纹理，使用光线步进与 GLSL 创建不断演化的视觉效果。
category: Background
tags: [css, tailwind, background, shader-toy, webgl, ogl]
---

::ComponentViewer{demoFile="StractiumBackgroundDemo.vue" config="StractiumBackgroundConfig" componentId="bg-stractium" :componentFiles='["StractiumBackground.vue"]'}

#api

## API

| 属性名             | 类型     | 默认值 | 描述                                                  |
| ------------------ | -------- | ------ | ----------------------------------------------------- |
| `hue`              | `number` | `0`    | 分形纹理的基础色相（0–360°）。                        |
| `saturation`       | `number` | `1`    | 颜色饱和度（0–1）。                                   |
| `brightness`       | `number` | `1`    | 输出颜色的亮度倍数（建议 0–2）。                      |
| `speed`            | `number` | `1`    | 纹理动画的速度倍数。                                  |
| `mouseSensitivity` | `number` | `0.5`  | 控制纹理对鼠标移动的响应度（0–1）。                   |
| `damping`          | `number` | `1`    | 控制纹理变形平滑度的阻尼系数（0–1）。                 |
| `class`            | `string` | `—`    | 可选，应用于容器 div 的额外 CSS 类（如 z-index 等）。 |

> 💡 该组件适合用于全屏或大区块背景，对现代 GPU 做了优化，但在低端设备上可能较吃性能。

#credits

- 基于原作者的 ShaderToy 片段着色器（MIT License）。
- 封装为 Vue 组件并适配动态输入。
- 灵感来自分形纹理、自然纹理与高级光线步进技术。

::

---

### Cn 2.Components Backgrounds Tetris (`content/cn/2.components/backgrounds/tetris.md`)

---
title: 俄罗斯方块
description: 俄罗斯方块背景组件，甚至可以点击方块来消除。
category: Background
tags: [css, tailwind, background]
---

::ComponentViewer{demoFile="TetrisDemo.vue" config="TetrisConfig" componentId="tetris" :componentFiles='["Tetris.vue"]' dependencies="theme-colors"}

#api

## API

| 属性名         | 类型     | 默认值 | 描述                 |
| -------------- | -------- | ------ | -------------------- |
| `class`        | `string` | `""`   | 用于样式的额外类名。 |
| `base`         | `number` | `10`   | 每行包含的方块数量。 |
| `square-color` | `string` | `""`   | 方块颜色。           |

#credits

- 感谢 [Whbbit1999](https://github.com/Whbbit1999) 提供该组件。
- 灵感并移植自 [Nuxt UI Home](https://ui2.nuxt.com/)。

::

---

### Cn 2.Components Backgrounds Thunderstorm Background (`content/cn/2.components/backgrounds/thunderstorm-background.md`)

---
title: 雷暴背景
description: 受云层雷暴启发的基于着色器的背景。
category: Background
tags: [css, tailwind, background, shader-toy, webgl, ogl]
---

::ComponentViewer{demoFile="ThunderstormBackgroundDemo.vue" config="ThunderstormBackgroundConfig" componentId="bg-thunderstorm" :componentFiles='["ThunderstormBackground.vue"]'}

#api

## API

| 属性名             | 类型     | 默认值 | 描述                                        |
| ------------------ | -------- | ------ | ------------------------------------------- |
| `hue`              | `number` | `0`    | 分形纹理的基础色相（0–360 度）。            |
| `saturation`       | `number` | `1`    | 颜色的饱和度（0–1）。                       |
| `brightness`       | `number` | `1`    | 输出颜色的亮度倍增（推荐 0–2）。            |
| `speed`            | `number` | `1`    | 动画的速度倍增。                            |
| `mouseSensitivity` | `number` | `0.5`  | 控制对鼠标移动的响应程度（0–5）。           |
| `damping`          | `number` | `1`    | 阻尼系数，用于平滑纹理的扭曲（0–1）。       |
| `class`            | `string` | `-`    | 容器 div 的额外 CSS 类（例如 z-index 等）。 |

> 💡 该组件适用于全屏或大段落的背景。针对现代 GPU 优化，但在低端设备上可能较耗资源。

#credits

- 改编自 [这个 ShaderToy 着色器](https://www.shadertoy.com/view/W3d3z7)。

::

---

### Cn 2.Components Backgrounds Video Text (`content/cn/2.components/backgrounds/video-text.md`)

---
title: 视频文字
description: 带有视频背景的文字组件。
category: Background
tags: [css, tailwind, background, magic-ui]
---

::ComponentViewer{demoFile="VideoTextDemo.vue" config="VideoTextConfig" componentId="video-text" :componentFiles='["VideoText.vue"]'}

#api

## API

| 属性名             | 类型                             | 默认值         | 描述                 |
| ------------------ | -------------------------------- | -------------- | -------------------- |
| `src`              | `string`                         | `Required`     | 视频源地址。         |
| `class`            | `string`                         | `""`           | 容器的额外类名。     |
| `autoPlay`         | `boolean`                        | `true`         | 是否自动播放视频。   |
| `muted`            | `boolean`                        | `true`         | 是否静音播放。       |
| `loop`             | `boolean`                        | `true`         | 是否循环播放。       |
| `preload`          | `"auto" \| "metadata" \| "none"` | `"auto"`       | 是否预加载视频。     |
| `fontSize`         | `string \| number`               | `"120"`        | 文字蒙版的字体大小。 |
| `fontWeight`       | `string \| number`               | `"bold"`       | 文字蒙版的字重。     |
| `textAnchor`       | `string`                         | `"middle"`     | 文字蒙版的锚点。     |
| `dominantBaseline` | `string`                         | `"middle"`     | 文字蒙版的基线对齐。 |
| `fontFamily`       | `string`                         | `"sans-serif"` | 文字蒙版的字体族。   |

#credits

- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi) 提供该组件。
- 移植自 [Magic UI 的 Video Text](https://magicui.design/docs/components/video-text)。

::

---

### Cn 2.Components Backgrounds Vortex (`content/cn/2.components/backgrounds/vortex.md`)

---
title: 漩涡背景
description: 波动、旋转的漩涡背景，适用于 CTA 与背景展示。
category: Background
tags: [css, tailwind, background, aceternity-ui, motion-v, simplex-noise]
---

::ComponentViewer{demoFile="VortexDemo.vue" config="VortexConfig" componentId="vortex" :componentFiles='["Vortex.vue"]' dependencies="simplex-noise"}

#api

## API

| 属性名            | 类型     | 默认值      | 描述                         |
| ----------------- | -------- | ----------- | ---------------------------- |
| `class`           | `string` |             | 用于子元素包装器的可选类名。 |
| `containerClass`  | `string` |             | 容器的可选类名。             |
| `particleCount`   | `number` | `700`       | 生成的粒子数量。             |
| `rangeY`          | `number` | `100`       | 粒子垂直运动范围。           |
| `baseHue`         | `number` | `220`       | 粒子颜色的基础色相。         |
| `baseSpeed`       | `number` | `0.0`       | 粒子运动的基础速度。         |
| `rangeSpeed`      | `number` | `1.5`       | 粒子速度变化范围。           |
| `baseRadius`      | `number` | `1`         | 粒子的基础半径。             |
| `rangeRadius`     | `number` | `2`         | 粒子半径变化范围。           |
| `backgroundColor` | `string` | `"#000000"` | 画布背景色。                 |

#credits

- 感谢 [Aceternity UI](https://ui.aceternity.com/components/vortex)。
- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi) 移植该组件。

::

---

### Cn 2.Components Backgrounds Warp Background (`content/cn/2.components/backgrounds/warp-background.md`)

---
title: 扭曲背景
description: 为子元素添加扭曲动画效果的容器组件。
category: Background
tags: [css, tailwind, background, magic-ui]
---

::ComponentViewer{demoFile="WarpBackgroundDemo.vue" config="WarpBackgroundConfig" componentId="warp-background" :componentFiles='["WarpBackground.vue", "Beam.vue"]'}

#api

## API

| 属性名         | 类型     | 默认值                 | 描述                   |
| -------------- | -------- | ---------------------- | ---------------------- |
| `perspective`  | `number` | `100`                  | 扭曲动画的透视值。     |
| `beamsPerSide` | `number` | `3`                    | 每侧的光束数量。       |
| `beamSize`     | `number` | `5`                    | 光束大小。             |
| `beamDelayMax` | `number` | `3`                    | 光束的最大延迟（秒）。 |
| `beamDelayMin` | `number` | `0`                    | 光束的最小延迟（秒）。 |
| `beamDuration` | `number` | `3`                    | 光束的持续时间。       |
| `gridColor`    | `string` | `"hsl(var(--border))"` | 网格线颜色。           |

#credits

- 感谢 [Whbbit1999](https://github.com/Whbbit1999) 提供该组件。
- 灵感并移植自 [Magic UI WarpBackground](https://magicui.design/docs/components/warp-background)。

::

---

### Cn 2.Components Backgrounds Wavy Background (`content/cn/2.components/backgrounds/wavy-background.md`)

---
title: 波浪背景
description: 流动的波浪背景效果。
category: Background
tags: [css, tailwind, background, simplex-noise, aceternity-ui]
---

::ComponentViewer{demoFile="WavyBackgroundDemo.vue" config="WavyBackgroundConfig" componentId="wavy-background" :componentFiles='["WavyBackground.vue"]' dependencies="simplex-noise"}

#api

## API

| 属性名           | 类型               | 默认值                                                    | 描述                       |
| ---------------- | ------------------ | --------------------------------------------------------- | -------------------------- |
| `class`          | `string`           | `-`                                                       | 显示在波浪背景之上的内容。 |
| `containerClass` | `string`           | `-`                                                       | 应用于内容容器的 CSS 类。  |
| `colors`         | `string[]`         | `["#38bdf8", "#818cf8", "#c084fc", "#e879f9", "#22d3ee"]` | 波浪的颜色。               |
| `waveWidth`      | `number`           | `50`                                                      | 波浪的宽度。               |
| `backgroundFill` | `string`           | `"black"`                                                 | 背景颜色。                 |
| `blur`           | `number`           | `10`                                                      | 应用于波浪的模糊效果。     |
| `speed`          | `"slow" \| "fast"` | `"fast"`                                                  | 粒子速度范围。             |
| `waveOpacity`    | `number`           | `0.5`                                                     | 波浪的不透明度。           |
| `[key: string]`  | `any`              | `-`                                                       | 粒子半径变化范围。         |

#credits

- 感谢 [Aceternity UI](https://ui.aceternity.com/components/wavy-background)。
- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi) 移植该组件。

::

---

### Cn 2.Components Buttons Gradient Button (`content/cn/2.components/buttons/gradient-button.md`)

---
title: 渐变按钮
description: 一款带有旋转圆锥渐变边框的时尚动效按钮，提供可自定义的属性，呈现活力效果。
category: Button
tags: [css, tailwind, button]
---

::ComponentViewer{demoFile="GradientButtonDemo.vue" config="GradientButtonConfig" componentId="gradient-button" :componentFiles='["GradientButton.vue"]'}

#api

## API

| 属性名         | 类型       | 默认值     | 描述                             |
| -------------- | ---------- | ---------- | -------------------------------- |
| `borderWidth`  | `number`   | `2`        | 渐变边框的像素宽度。             |
| `colors`       | `string[]` | 彩虹色数组 | 用于圆锥渐变边框的颜色数组。     |
| `duration`     | `number`   | `2500`     | 渐变旋转动画的持续时间（毫秒）。 |
| `borderRadius` | `number`   | `8`        | 圆角半径（像素）。               |
| `blur`         | `number`   | `4`        | 渐变边框的模糊强度（像素）。     |
| `class`        | `string`   | `""`       | 用于自定义样式的额外 CSS 类。    |
| `bgColor`      | `string`   | `"#000"`   | 按钮内容的背景色。               |

::

---

### Cn 2.Components Buttons Interactive Hover Button (`content/cn/2.components/buttons/interactive-hover-button.md`)

---
title: 交互悬停按钮
description: 一款视觉效果出色的按钮组件，悬停时呈现动态过渡，能在明暗模式下平滑适配，提升交互体验。
category: Button
tags: [css, tailwind, button, magic-ui]
---

::ComponentViewer{demoFile="InteractiveHoverButtonDemo.vue" config="InteractiveHoverButtonConfig" componentId="interactive-hover-button" :componentFiles='["InteractiveHoverButton.vue"]'}

#api

## API

| 属性名  | 类型     | 默认值   | 描述                 |
| ------- | -------- | -------- | -------------------- |
| `text`  | `string` | `Button` | 按钮内部显示的文字。 |
| `class` | `string` | `""`     | 用于样式的额外类名。 |

#credits

- 感谢 [Whbbit1999](https://github.com/Whbbit1999) 提供该组件。
- 灵感并移植自 [Magic UI Interactive Hover Button](https://magicui.design/docs/components/interactive-hover-button)。

::

---

### Cn 2.Components Buttons Rainbow Button (`content/cn/2.components/buttons/rainbow-button.md`)

---
title: 彩虹按钮
description: 在按钮上呈现彩虹效果。
category: Button
tags: [css, tailwind, button, magic-ui]
---

::ComponentViewer{demoFile="RainbowButtonDemo.vue" config="RainbowButtonConfig" componentId="rainbow-button" :componentFiles='["RainbowButton.vue"]'}

#api

## API

| 属性名  | 类型     | 默认值     | 描述                         |
| ------- | -------- | ---------- | ---------------------------- |
| `class` | `string` | `""`       | 应用于按钮的额外 CSS 类。    |
| `is`    | `string` | `"button"` | 渲染组件时使用的 HTML 标签。 |
| `speed` | `number` | `2`        | 动画持续时间（秒）。         |

#credits

- 感谢 [Grzegorz Krol](https://github.com/Grzechu335) 移植该组件。
- 致敬 [Magic UI](https://magicui.design/docs/components/rainbow-button)。

::

---

### Cn 2.Components Buttons Ripple Button (`content/cn/2.components/buttons/ripple-button.md`)

---
title: 波纹按钮
description: 一款带有可自定义颜色和动画时长的时尚波纹按钮组件。
category: Button
tags: [css, tailwind, button, magic-ui]
---

::ComponentViewer{demoFile="RippleButtonDemo.vue" config="RippleButtonConfig" componentId="ripple-button" :componentFiles='["RippleButton.vue"]'}

#api

## API

| 属性名        | 类型     | 默认值      | 描述                          |
| ------------- | -------- | ----------- | ----------------------------- |
| `class`       | `string` | -           | 用于自定义样式的额外 CSS 类。 |
| `rippleColor` | `string` | `"#ADD8E6"` | 波纹效果的颜色。              |
| `duration`    | `number` | `600`       | 波纹动画的持续时间（毫秒）。  |

## Emits

| 事件名  | 类型    | 描述     |
| ------- | ------- | -------- |
| `click` | `event` | 点击事件 |

#credits

- 灵感来自 [Magic UI 的 Ripple Button](https://magicui.design/docs/components/ripple-button) 组件。
- 感谢 [kalix127](https://github.com/kalix127) 对该组件的移植。

::

---

### Cn 2.Components Buttons Shimmer Button (`content/cn/2.components/buttons/shimmer-button.md`)

---
title: 闪光按钮
description: 一款带有闪烁动画效果的按钮。
category: Button
tags: [css, tailwind, button, magic-ui]
---

::ComponentViewer{demoFile="ShimmerButtonDemo.vue" config="ShimmerButtonConfig" componentId="shimmer-button" :componentFiles='["ShimmerButton.vue"]'}

#api

## API

| 属性名            | 类型     | 默认值               | 描述                                  |
| ----------------- | -------- | -------------------- | ------------------------------------- |
| `class`           | `string` | `""`                 | 应用于按钮的额外 CSS 类。             |
| `shimmerColor`    | `string` | `"#ffffff"`          | 闪光效果的颜色。                      |
| `shimmerSize`     | `string` | `"0.05em"`           | 闪光效果的尺寸。                      |
| `borderRadius`    | `string` | `"100px"`            | 按钮的圆角半径。                      |
| `shimmerDuration` | `string` | `"3s"`               | 闪光动画的持续时间。                  |
| `background`      | `string` | `"rgba(0, 0, 0, 1)"` | 按钮的背景色，可使用 rgb 或十六进制。 |

#credits

- 移植自 [Magic UI Shimmer Button](https://magicui.design/docs/components/shimmer-button)。

::

---

### Cn 2.Components Cards 3d Card (`content/cn/2.components/cards/3d-card.md`)

---
title: 3D 卡片效果
description: 具有透视效果的卡片，悬停时可让卡片元素提升。
category: Card
tags: [css, tailwind, card, aceternity-ui]
---

::ComponentViewer{demoFile="CardDemo.vue" config="Card3dConfig" componentId="card-3d" :componentFiles='["CardContainer.vue", "CardBody.vue", "CardItem.vue", "useMouseState.ts"]'}

#api

## API

### `CardContainer`

`CardContainer` 组件是 3D 卡片效果的外层容器，处理鼠标事件以创建 3D 透视。

#### Props

| 属性名           | 类型   | 默认值 | 描述                       |
| ---------------- | ------ | ------ | -------------------------- |
| `class`          | string | `null` | 用于内层容器的额外样式类。 |
| `containerClass` | string | `null` | 用于外层容器的额外样式类。 |

---

### `CardBody`

`CardBody` 是一个保留 3D 样式的灵活容器，需在 `CardContainer` 内使用，以承载带有 3D 变换效果的内容。

#### Props

| 属性名  | 类型   | 默认值 | 描述                     |
| ------- | ------ | ------ | ------------------------ |
| `class` | string | `null` | 用于自定义样式的额外类。 |

---

### `CardItem`

`CardItem` 表示 3D 卡片中的单个元素，支持平移与旋转等变换，以构建动态的 3D 效果。

#### Props

| 属性名       | 类型   | 默认值  | 描述                                 |
| ------------ | ------ | ------- | ------------------------------------ |
| `as`         | string | `"div"` | 渲染该元素使用的 HTML 标签或组件。   |
| `class`      | string | `null`  | 应用于元素的额外类名。               |
| `translateX` | string | `0`     | X 轴平移（像素）。                   |
| `translateY` | string | `0`     | Y 轴平移（像素）。                   |
| `translateZ` | string | `0`     | Z 轴平移（像素），用于控制纵深效果。 |
| `rotateX`    | string | `0`     | 绕 X 轴旋转角度（度）。              |
| `rotateY`    | string | `0`     | 绕 Y 轴旋转角度（度）。              |
| `rotateZ`    | string | `0`     | 绕 Z 轴旋转角度（度）。              |

---

> 💡 **重要提示：**
>
> 如果在 `div` 内使用 `CardItem`，请在该 div 上添加 `style="transform-style: preserve-3d;"`，以确保 `translate-z` 属性生效。

#credits

- 移植自 Aceternity UI 的 3D Card 组件。

::

---

### Cn 2.Components Cards Apple Card Carousel (`content/cn/2.components/cards/apple-card-carousel.md`)

---
title: Apple 卡片轮播
description: 一款流畅的 Apple 风格卡片轮播，支持模糊加载图片、模态展开和平滑滚动控制。
category: Card
tags: [css, tailwind, card, aceternity-ui]
---

::ComponentViewer{demoFile="AppleCardCarouselDemo.vue" config="AppleCardCarouselConfig" componentId="apple-card-carousel" :componentFiles='["AppleCardCarousel.vue", "AppleCarouselItem.vue", "AppleCard.vue", "AppleBlurImage.vue", "AppleCarouselContext.ts"]'}

#api

**Apple Carousel** 由四个相互关联的组件组成：

| 组件                | 用途                                        |
| ------------------- | ------------------------------------------- |
| `AppleCardCarousel` | 带有左右控制的水平滚动容器。                |
| `AppleCarouselItem` | 为每个卡片添加进入动画和间距的包装组件。    |
| `AppleCard`         | 可点击的精美卡片，可展开为全屏模态。        |
| `AppleBlurImage`    | 一个 `<img>` 的替代品，图片加载前保持模糊。 |

它们组合在一起，重现 “App Store / Apple TV” 的浏览体验。

---

## `AppleCardCarousel`

| 属性            | 类型     | 默认值 | 描述                               |
| --------------- | -------- | ------ | ---------------------------------- |
| `initialScroll` | `number` | `0`    | 挂载时应用的水平滚动偏移量（px）。 |

### Slots

默认插槽中应包含一个或多个 **`AppleCarouselItem`** 组件。

### Emits

无自定义事件。

---

## `AppleCarouselItem`

| 属性    | 类型     | 必填 | 描述                                     |
| ------- | -------- | ---- | ---------------------------------------- |
| `index` | `number` | 是   | 从零开始的索引，用于控制入场动画的交错。 |

### Slots

默认插槽——在此放置 **`AppleCard`**。

---

## `AppleCard`

| 属性     | 类型                                               | 必填 | 默认值  | 描述                       |
| -------- | -------------------------------------------------- | ---- | ------- | -------------------------- |
| `card`   | `{ src: string; title: string; category: string }` | 是   | —       | 卡片数据对象。             |
| `index`  | `number`                                           | 是   | —       | 卡片在轮播中的位置。       |
| `layout` | `boolean`                                          | 否   | `false` | 启用共享布局的 FLIP 动画。 |

### Slots

当卡片 **展开**（模态打开）时，默认插槽会渲染在模态主体中，你可以插入更多内容，如文本、图片或视频。

### Emits

无自定义事件（依赖注入的 `CarouselKey` 上下文）。

---

## `AppleBlurImage`

| 属性     | 类型               | 默认值                           | 描述                                                    |
| -------- | ------------------ | -------------------------------- | ------------------------------------------------------- |
| `src`    | `string`           | **—**                            | 图片源地址。_必填。_                                    |
| `alt`    | `string`           | "Background of a beautiful view" | 图片的替代文本。                                        |
| `width`  | `number \| string` | 图片自然尺寸                     | 宽度属性；使用 `fill` 时会省略。                        |
| `height` | `number \| string` | 图片自然尺寸                     | 高度属性；使用 `fill` 时会省略。                        |
| `fill`   | `boolean`          | `false`                          | 若为 `true`，通过工具类设置 `width:100%; height:100%`。 |
| `class`  | `string`           | `""`                             | 通过 `cn()` 合并的额外类名。                            |

当图片触发原生 `load` 事件时，会从 `blur-sm` 平滑过渡为无模糊。

---

#credits

- 移植自 [Aceternity UI Apple Card Carousel](https://ui.aceternity.com/components/apple-cards-carousel)。

::

---

### Cn 2.Components Cards Card Spotlight (`content/cn/2.components/cards/card-spotlight.md`)

---
title: 卡片聚光效果
description: 一款带有动态聚光灯效果的卡片组件，光标移动时跟随，增强视觉互动。
category: Card
tags: [css, tailwind, card, magic-ui]
---

::ComponentViewer{demoFile="CardSpotlightDemo.vue" config="CardSpotlightConfig" componentId="card-spotlight" :componentFiles='["CardSpotlight.vue"]'}

#api

## API

| 属性名            | 类型     | 默认值      | 描述                           |
| ----------------- | -------- | ----------- | ------------------------------ |
| `gradientSize`    | `number` | `200`       | 聚光效果的半径（像素）。       |
| `gradientColor`   | `string` | `'#262626'` | 聚光渐变的颜色。               |
| `gradientOpacity` | `number` | `0.8`       | 聚光渐变效果的不透明度。       |
| `slotClass`       | `string` | `undefined` | 应用于包含插槽的父容器的类名。 |

#credits

- 灵感来自 [Magic UI](https://magicui.design/docs/components/magic-card) 的 Magic Card 组件。

::

---

### Cn 2.Components Cards Card Stack (`content/cn/2.components/cards/card-stack.md`)

---
title: 卡片堆叠
description: 随着用户滚动，让卡片缩放并叠放成聚焦的卡片堆。
category: 卡片
tags: [css, tailwind, motion-v, scroll]
badge: New
---

::ComponentViewer{demoFile="CardStackDemo.vue" config="CardStackConfig" componentId="card-stack" :componentFiles='["CardStack.vue", "CardStackItem.vue", "CardStackContext.ts", "index.ts"]'}

#api

## API

### CardStack

| 属性名            | 类型               | 默认值                                   | 说明                              |
| ----------------- | ------------------ | ---------------------------------------- | --------------------------------- |
| `totalCards`      | `number`           | —                                        | 用于计算堆叠缩放效果的卡片总数。  |
| `scaleMultiplier` | `number`           | `0.03`                                   | 卡片在滚动范围内缩放的幅度。      |
| `scrollOptions`   | `UseScrollOptions` | `{ offset: ["start start", "end end"] }` | Motion 滚动选项，可传入滚动容器。 |
| `class`           | `string`           | `-`                                      | 应用到堆叠容器的额外类名。        |

### CardStackItem

| 属性名        | 类型     | 默认值           | 说明                               |
| ------------- | -------- | ---------------- | ---------------------------------- |
| `index`       | `number` | —                | 用于计算缩放的从零开始的卡片索引。 |
| `topPosition` | `string` | `5 + index * 3%` | 卡片的 sticky 顶部偏移。           |
| `class`       | `string` | `-`              | 应用到卡片包装器的额外类名。       |

## 用法

使用 `CardStack` 作为父组件，并在每张卡片外包裹一个 `CardStackItem`。为每个项目设置高度，让 sticky 滚动范围可以正常推进。

```vue
<CardStack :total-cards="cards.length">
  <CardStackItem
    v-for="(card, index) in cards"
    :key="card"
    :index="index"
    class="h-dvh"
  >
    <div class="h-[80%]">{{ card }}</div>
  </CardStackItem>
</CardStack>
```

#credits

- 移植自 [Fancy Components](https://fancycomponents.dev/docs/components/blocks/stacking-cards)。

::

---

### Cn 2.Components Cards Cube Carousel (`content/cn/2.components/cards/cube-carousel.md`)

---
title: 立方体轮播
description: 使用四个立方体面，在图片和视频之间拖动切换的 3D 轮播组件。
category: 卡片
tags: [css, tailwind, motion-v, carousel, 3d]
badge: New
---

::ComponentViewer{demoFile="CubeCarouselDemo.vue" config="CubeCarouselConfig" componentId="cube-carousel" :componentFiles='["CubeCarousel.vue", "index.ts"]'}

#api

## API

### `CubeCarousel`

| 属性名             | 类型                                     | 默认值                                            | 说明                                         |
| ------------------ | ---------------------------------------- | ------------------------------------------------- | -------------------------------------------- |
| `items`            | `CubeCarouselItem[]`                     | —                                                 | 放置在立方体面上的图片或视频，建议至少四项。 |
| `width`            | `number`                                 | —                                                 | 每个面的宽度，单位为像素。                   |
| `height`           | `number`                                 | —                                                 | 每个面的高度，单位为像素。                   |
| `class`            | `string`                                 | —                                                 | 轮播根元素的额外类名。                       |
| `debug`            | `boolean`                                | `false`                                           | 显示面颜色和项目 ID，用于检查立方体结构。    |
| `perspective`      | `number`                                 | `600`                                             | CSS 透视距离，单位为像素。                   |
| `direction`        | `"top" \| "bottom" \| "left" \| "right"` | `"left"`                                          | 旋转轴和方向。                               |
| `transition`       | `Record<string, unknown>`                | `{ duration: 1.25, ease: [...] }`                 | 按钮和键盘旋转使用的 Motion 过渡。           |
| `snapTransition`   | `Record<string, unknown>`                | `{ type: "spring", damping: 30, stiffness: 200 }` | 拖动释放后吸附到面的过渡。                   |
| `dragSpring`       | `CubeCarouselSpringConfig`               | `{ stiffness: 200, damping: 30 }`                 | 跟随指针拖动时使用的弹簧配置。               |
| `autoPlay`         | `boolean`                                | `false`                                           | 自动切换项目。                               |
| `autoPlayInterval` | `number`                                 | `3000`                                            | 自动切换间隔，单位为毫秒。                   |
| `onIndexChange`    | `(index: number) => void`                | —                                                 | 每次旋转完成后调用。                         |
| `enableDrag`       | `boolean`                                | `true`                                            | 启用指针和触摸拖动。                         |
| `dragSensitivity`  | `number`                                 | `0.5`                                             | 指针移动产生的旋转量。                       |

### `CubeCarouselItem`

| 属性名   | 类型                 | 必填 | 说明                   |
| -------- | -------------------- | ---- | ---------------------- |
| `id`     | `string`             | 是   | 项目的稳定标识符。     |
| `type`   | `"image" \| "video"` | 是   | 选择图片或视频渲染器。 |
| `src`    | `string`             | 是   | 图片或视频地址。       |
| `alt`    | `string`             | 否   | 图片的替代文本。       |
| `poster` | `string`             | 否   | 视频的封面图片地址。   |

## 交互

沿着轮播轴拖动即可旋转立方体，松开后会吸附到最近的四分之一转角。聚焦后可以使用对应轴向的方向键，也可以通过暴露的 `next`、`prev` 和 `getCurrentItemIndex` 方法控制轮播。

#credits

- 移植自 [Fancy Components Box Carousel](https://fancycomponents.dev/docs/components/carousel/box-carousel)。
- Demo 图片来自 [Daniel Petho](https://www.cosmos.so/danielpetho/box-carousel-demo)。
- 灵感来自 [Framer University](https://framer.university/resources/3d-box-carousel-in-framer)。

::

---

### Cn 2.Components Cards Direction Aware Hover (`content/cn/2.components/cards/direction-aware-hover.md`)

---
title: 方向感知悬停卡片
description: 方向感知的悬停卡片，在悬停时显示带动态效果的图片，并提供可自定义的内容覆盖层。
category: Card
tags: [css, tailwind, card, aceternity-ui]
---

::ComponentViewer{demoFile="DirectionAwareHoverDemo.vue" config="DirectionAwareHoverConfig" componentId="direction-aware-hover" :componentFiles='["DirectionAwareHover.vue"]'}

#api

## API

| 属性名          | 类型     | 默认值      | 描述                      |
| --------------- | -------- | ----------- | ------------------------- |
| `imageUrl`      | `string` | 必填        | 要显示的图片 URL。        |
| `class`         | `string` | `undefined` | 卡片容器的额外 CSS 类。   |
| `imageClass`    | `string` | `undefined` | 图片元素的额外 CSS 类。   |
| `childrenClass` | `string` | `undefined` | 内容覆盖层的额外 CSS 类。 |

#credits

- 感谢 [M Atif](https://github.com/atif0075) 移植该组件。
- 移植自 [Aceternity UI 的 Direction Aware Hover](https://ui.aceternity.com/components/direction-aware-hover)。

::

---

### Cn 2.Components Cards Fey Cards (`content/cn/2.components/cards/fey-cards.md`)

---
title: Fey Cards
description: 一个带有分层图片切换和电影感标题揭示效果的悬停卡片堆叠动画组件。
category: Card
tags: [css, tailwind, card, aceternity-ui]
---

::ComponentViewer{demoFile="FeyCardsDemo.vue" config="FeyCardsConfig" componentId="fey-cards" :componentFiles='["FeyCards.vue"]'}

#api

## API

| 属性名            | 类型           | 默认值                                                 | 描述                               |
| ----------------- | -------------- | ------------------------------------------------------ | ---------------------------------- |
| `imgSrc`          | `string[]`     | `[]`                                                   | 用于堆叠卡片的图片地址数组。       |
| `mainImg`         | `string`       | `-`                                                    | 卡片堆叠背后的主图。               |
| `idleImg`         | `string`       | `-`                                                    | 未悬停时显示的闲置图片。           |
| `cardSpacing`     | `number`       | `32`                                                   | 卡片之间的水平间距。               |
| `spring`          | `SpringConfig` | `{ type: "spring", visualDuration: 0.5, bounce: 0.2 }` | 进入动画和位移动画使用的弹簧配置。 |
| `shiftDistance`   | `number`       | `60`                                                   | 卡片在悬停状态下水平移动的距离。   |
| `swapDuration`    | `number`       | `0.5`                                                  | 图片切换过渡的时长，单位为秒。     |
| `entranceStagger` | `number`       | `0.2`                                                  | 每张卡片进入动画之间的延迟。       |
| `class`           | `string`       | `-`                                                    | 应用于外层容器的额外 Tailwind 类。 |

#credits

- 灵感来源于 [Aceternity UI](https://ui.aceternity.com/labs/fey-card)。

::

---

### Cn 2.Components Cards Flip Card (`content/cn/2.components/cards/flip-card.md`)

---
title: 翻转卡片
description: 一款动态的翻转卡片，沿 X 轴或 Y 轴平滑实现 180 度翻转，带来有趣的交互视觉效果。
category: Card
tags: [css, tailwind, card]
---

::ComponentViewer{demoFile="FlipCardDemo.vue" config="FlipCardConfig" componentId="flip-card" :componentFiles='["FlipCard.vue"]'}

#api

## API

| 属性名   | 类型     | 默认值 | 描述                   |
| -------- | -------- | ------ | ---------------------- |
| `class`  | `string` | `-`    | 应用于组件的类名。     |
| `rotate` | `x \| y` | `y`    | 传入希望沿哪个轴翻转。 |

| 插槽名    | 描述             |
| --------- | ---------------- |
| `default` | 前面显示的内容。 |
| `back`    | 背面显示的内容。 |

#credits

- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi) 提供该组件。

::

---

### Cn 2.Components Cards Floating Card (`content/cn/2.components/cards/floating-card.md`)

---
title: Floating Card
description: 一个带有透视、3D 倾斜和光泽跟随效果的悬停卡片组件，灵感来自 Perplexity Comet 网站。
category: Card
tags: [css, tailwind, card, motion, 3D, aceternity-ui]
---

::ComponentViewer{demoFile="FloatingCardDemo.vue" config="FloatingCardConfig" componentId="floating-card" :componentFiles='["FloatingCard.vue"]'}

#api

## API

| 属性名           | 类型     | 默认值 | 描述                               |
| ---------------- | -------- | ------ | ---------------------------------- |
| `rotateDepth`    | `number` | `17.5` | 卡片悬停时应用的最大 X/Y 旋转值。  |
| `translateDepth` | `number` | `20`   | 跟随光标时应用的最大 X/Y 平移值。  |
| `class`          | `string` | `-`    | 应用于外层容器的额外 Tailwind 类。 |

#credits

- 灵感来源于 [Aceternity UI](https://ui.aceternity.com/components/comet-card)。

::

---

### Cn 2.Components Cards Glare Card (`content/cn/2.components/cards/glare-card.md`)

---
title: 高光卡片
description: 悬停时出现高光效果的卡片，灵感来自 Linear 网站。
category: Card
tags: [css, tailwind, card, aceternity-ui]
---

::ComponentViewer{demoFile="GlareCardDemo.vue" config="GlareCardConfig" componentId="glare-card" :componentFiles='["GlareCard.vue"]'}

#api

## API

| 属性名  | 类型     | 默认值 | 描述                                 |
| ------- | -------- | ------ | ------------------------------------ |
| `class` | `string` | `-`    | 应用于卡片的额外 Tailwind CSS 类名。 |

#credits

- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi) 提供该组件。
- 灵感来自 [Aceternity UI](https://ui.aceternity.com/components/glare-card)。

::

---

### Cn 2.Components Cursors Fluid Cursor (`content/cn/2.components/cursors/fluid-cursor.md`)

---
title: 流体光标
description: GPU 加速的动画光标尾迹，模拟流体运动。
category: Cursor
tags: [css, tailwind, cursor, webgl, cursify]
---

::ComponentViewer{demoFile="FluidCursorDemo.vue" config="FluidCursorConfig" componentId="fluid-cursor" :componentFiles='["FluidCursor.vue"]'}

#api

## API

| 属性名                | 类型      | 默认值                   | 描述                                    |
| --------------------- | --------- | ------------------------ | --------------------------------------- |
| `simResolution`       | `number`  | `128`                    | 模拟网格的分辨率，影响流体细节与性能。  |
| `dyeResolution`       | `number`  | `1440`                   | 流体染色（颜色）纹理的分辨率。          |
| `captureResolution`   | `number`  | `512`                    | 捕获输入事件的分辨率。                  |
| `densityDissipation`  | `number`  | `3.5`                    | 颜色密度随时间消散的速度。              |
| `velocityDissipation` | `number`  | `2`                      | 速度随时间衰减的程度，影响动量保持。    |
| `pressure`            | `number`  | `0.1`                    | 流体物理计算中的压力系数。              |
| `pressureIterations`  | `number`  | `20`                     | 压力求解的迭代次数。                    |
| `curl`                | `number`  | `3`                      | 漩涡/旋度效果的强度，用于增强旋转运动。 |
| `splatRadius`         | `number`  | `0.2`                    | 指针在流体中的溅射半径。                |
| `splatForce`          | `number`  | `6000`                   | 指针作用于流体的力。                    |
| `shading`             | `boolean` | `true`                   | 是否启用流体颜色的明暗效果。            |
| `colorUpdateSpeed`    | `number`  | `10`                     | 指针颜色动态更新的速度。                |
| `backColor`           | `object`  | `{ r: 0.5, g: 0, b: 0 }` | 流体背景色，RGB 格式。                  |
| `transparent`         | `boolean` | `true`                   | 画布背景是否透明。                      |
| `class`               | `string`  | `undefined`              | 外层容器 div 的额外 CSS 类。            |

#credits

- 灵感来自 [Fluid Cursor by Cursify](https://cursify.vercel.app/components/fluid-cursor)。
- 使用 WebGL 1/2 上下文与自定义 GLSL 着色器实现流体物理与渲染。

::

---

### Cn 2.Components Cursors Image Trail Cursor (`content/cn/2.components/cursors/image-trail-cursor.md`)

---
title: 图像尾迹光标
description: 一种交互式光标效果，鼠标移动时呈现动态的图像尾迹，并提供多种动画变体。
category: Cursor
tags: [css, tailwind, cursor, codrops, gsap]
---

::ComponentViewer{demoFile="ImageTrailCursorDemo.vue" config="ImageTrailCursorConfig" componentId="image-trail-cursor" :componentFiles='["ImageTrailCursor.vue", "trail-variants.ts"]' dependencies="gsap"}

#api

## API

| 属性名    | 类型          | 默认值    | 描述                                     |
| --------- | ------------- | --------- | ---------------------------------------- |
| `images`  | `string[]`    | `[]`      | 用于尾迹显示的图片 URL 数组。            |
| `variant` | `VariantType` | `"type1"` | 动画变体类型（`"type1"` 至 `"type7"`）。 |

> 💡 该组件会创建全宽全高且 z-index 较高的容器以追踪光标。每张图像宽 190px，纵横比 1.1，带圆角。

#credits

- 灵感来自现代光标尾迹与图片悬停交互效果。
- 基于 Vue 3 组合式 API 构建，确保高响应性与性能。
- 移植自 [Codrops 文章](https://tympanus.net/codrops/2023/10/18/ideas-for-image-motion-trail-animations/)。

::

---

### Cn 2.Components Cursors Sleek Line Cursor (`content/cn/2.components/cursors/sleek-line-cursor.md`)

---
title: 流线光标
description: 具有平滑波动尾迹的响应式动画光标，使用弹簧物理和动态色彩波动。
category: Cursor
tags: [css, tailwind, cursor, webgl, cursify]
---

::ComponentViewer{demoFile="SleekLineCursorDemo.vue" config="SleekLineCursorConfig" componentId="sleek-line-cursor" :componentFiles='["SleekLineCursor.vue"]'}

## API

| 属性名      | 类型                 | 默认值      | 描述                                     |
| ----------- | -------------------- | ----------- | ---------------------------------------- |
| `class`     | `string \| string[]` | `undefined` | 画布容器元素的额外 CSS 类。              |
| `trails`    | `number`             | `20`        | 渲染在光标后的尾迹数量。                 |
| `size`      | `number`             | `50`        | 每条尾迹中由弹簧连接的节点数量。         |
| `friction`  | `number`             | `0.5`       | 施加到速度的全局摩擦。                   |
| `dampening` | `number`             | `0.25`      | 在连接节点间施加的速度阻尼。             |
| `tension`   | `number`             | `0.98`      | 减小尾部的弹簧强度，带来流畅的渐收运动。 |

> 💡 该组件默认使用 `pointer-events-none`，并固定为全屏。可通过 `class` 属性扩展或覆写样式。

#credits

- 移植自 [Canvas Cursor by Cursify](https://cursify.vercel.app/components/canvas-cursor)。

::

---

### Cn 2.Components Cursors Smooth Cursor (`content/cn/2.components/cursors/smooth-cursor.md`)

---
title: 平滑光标
description: 适用于 Vue 应用的可定制物理驱动平滑光标动画组件。
category: Cursor
tags: [css, tailwind, cursor, magic-ui]
---

::ComponentViewer{demoFile="SmoothCursorDemo.vue" config="SmoothCursorConfig" componentId="smooth-cursor" :componentFiles='["SmoothCursor.vue"]'}

#api

## API

| 属性名         | 类型           | 默认值          | 描述                               |
| -------------- | -------------- | --------------- | ---------------------------------- |
| `cursor`       | `Component`    | `DefaultCursor` | 用于替换默认光标的自定义光标组件。 |
| `springConfig` | `SpringConfig` | `See below`     | 弹簧动画的配置对象。               |

### SpringConfig 类型

```ts
interface springConfig {
  damping: number;
  stiffness: number;
  mass: number;
  restDelta: number;
}
```

#credits

- 感谢 [Whbbit1999](https://github.com/Whbbit1999) 提供该组件。
- 移植自 [Magic UI Smooth Cursor](https://magicui.design/docs/components/smooth-cursor)。

::

---

### Cn 2.Components Cursors Tailed Cursor (`content/cn/2.components/cursors/tailed-cursor.md`)

---
title: 尾迹光标
description: 使用 OGL 渲染的顺滑彩带尾迹光标，具备动态着色器和可定制的动画效果。
category: Cursor
tags: [css, tailwind, cursor, webgl, codrops]
---

::ComponentViewer{demoFile="TailedCursorDemo.vue" config="TailedCursorConfig" componentId="tailed-cursor" :componentFiles='["TailedCursor.vue"]' dependencies="ogl"}

#api

## API

| 属性名               | 类型       | 默认值                                         | 描述                                       |
| -------------------- | ---------- | ---------------------------------------------- | ------------------------------------------ |
| `colors`             | `string[]` | `["#ff9346", "#7cff67", "#ffee51", "#00d8ff"]` | 每条尾带使用的颜色数组。                   |
| `baseSpring`         | `number`   | `0.03`                                         | 尾迹移动的弹性力度。                       |
| `baseFriction`       | `number`   | `0.9`                                          | 减缓尾迹移动的摩擦系数。                   |
| `baseThickness`      | `number`   | `30`                                           | 尾带的基础厚度。                           |
| `offsetFactor`       | `number`   | `0.05`                                         | 每条尾带之间的水平偏移系数。               |
| `maxAge`             | `number`   | `500`                                          | 尾迹片段的最大存活时间，用于控制消失时机。 |
| `pointCount`         | `number`   | `50`                                           | 组成每条尾带的点数量。                     |
| `speedMultiplier`    | `number`   | `0.6`                                          | 控制动画速度的倍增值。                     |
| `enableFade`         | `boolean`  | `false`                                        | 是否启用尾缘的渐隐效果。                   |
| `enableShaderEffect` | `boolean`  | `false`                                        | 是否启用尾带的动态着色器波纹效果。         |
| `effectAmplitude`    | `number`   | `2`                                            | 启用着色器波纹时的振幅。                   |
| `backgroundColor`    | `number[]` | `[0, 0, 0, 0]`                                 | WebGL 画布的 RGBA 背景清除色。             |

#credits

- 基于轻量级 WebGL 框架 [OGL](https://github.com/oframe/ogl) 构建。
- 灵感来自 [Codrops 文章](https://tympanus.net/codrops/2019/09/24/crafting-stylised-mouse-trails-with-ogl/)。

::

---

### Cn 2.Components Device Mocks Iphone Mockup (`content/cn/2.components/device-mocks/iphone-mockup.md`)

---
title: iPhone 模型
description: iPhone 的 SVG 设备模型。
category: Device Mockup
tags: [css, tailwind, device-mockup, magic-ui]
---

::ComponentViewer{demoFile="iPhone15ProMockupDemo.vue" config="iPhone15ProMockupConfig" componentId="iphone-mockup" :componentFiles='["iPhone15ProMockup.vue"]'}

#api

## API

| 属性名   | 类型     | 默认值 | 描述                      |
| -------- | -------- | ------ | ------------------------- |
| `width`  | `number` | `433`  | 模型 SVG 的宽度（像素）。 |
| `height` | `number` | `882`  | 模型 SVG 的高度（像素）。 |
| `src`    | `string` | `null` | 在模型中显示的图片 URL。  |

#credits

- 移植自 [Magic UI](https://magicui.design/docs/components/iphone-15-pro)。

::

---

### Cn 2.Components Device Mocks Safari Mockup (`content/cn/2.components/device-mocks/safari-mockup.md`)

---
title: Safari 模型
description: Safari 浏览器的 SVG 模型。
category: Device Mockup
tags: [css, tailwind, device-mockup, magic-ui]
---

::ComponentViewer{demoFile="SafariMockupDemo.vue" config="SafariMockupConfig" componentId="safari-mockup" :componentFiles='["SafariMockup.vue"]'}

#api

## API

| 属性名   | 类型     | 默认值 | 描述                      |
| -------- | -------- | ------ | ------------------------- |
| `url`    | `string` | `null` | 模型地址栏中显示的 URL。  |
| `src`    | `string` | `null` | 在模型中显示的图片 URL。  |
| `width`  | `number` | `1203` | 模型 SVG 的宽度（像素）。 |
| `height` | `number` | `753`  | 模型 SVG 的高度（像素）。 |

#credits

- 移植自 [Magic UI](https://magicui.design/docs/components/safari)。

::

---

### Cn 2.Components Html In Canvas Html Ascii (`content/cn/2.components/html-in-canvas/html-ascii.md`)

---
title: HTML ASCII
description: 使用匹配亮度的位图字符重建实时 HTML。
category: HTML in Canvas
tags: [webgl, shader, canvas, ascii, typography]
badge: New
dependencies: []
---

::ComponentViewer{demoFile="HtmlAsciiDemo.vue" config="HtmlAsciiConfig" componentId="html-ascii" :componentFiles='["HtmlAscii.vue"]'}

按下效果表面可将字符输出切换为单色。

#api

## API

| 属性         | 类型      | 默认值  | 说明                                    |
| ------------ | --------- | ------- | --------------------------------------- |
| `cellSize`   | `number`  | `8`     | 字符单元像素尺寸，小于 `5` 时使用 `5`。 |
| `frameRate`  | `number`  | `60`    | 最大渲染帧率。                          |
| `pixelRatio` | `number`  | `1`     | 渲染比例，限制在 `0.25` 到 `2` 之间。   |
| `paused`     | `boolean` | `false` | 暂停渲染循环。                          |
| `autoPause`  | `boolean` | `true`  | 离开视口或页面隐藏时自动暂停。          |
| `class`      | `string`  | —       | 合并到效果表面的额外类名。              |

### 插槽

| 插槽      | 说明                       |
| --------- | -------------------------- |
| `default` | 通过效果渲染的 HTML 内容。 |

#credits

- 位图字符技术改编自 [movAX13h](https://www.shadertoy.com/user/movAX13h)。

::

---

### Cn 2.Components Html In Canvas Html Blaze (`content/cn/2.components/html-in-canvas/html-blaze.md`)

---
title: HTML 火焰
description: 使用上升热流、烟雾、火花和火光扭曲实时 HTML。
category: HTML in Canvas
tags: [webgl, shader, canvas, fire, animation]
badge: New
dependencies: []
---

::ComponentViewer{demoFile="HtmlBlazeDemo.vue" config="HtmlBlazeConfig" componentId="html-blaze" :componentFiles='["HtmlBlaze.vue"]'}

#api

## API

| 属性         | 类型      | 默认值  | 说明                                  |
| ------------ | --------- | ------- | ------------------------------------- |
| `strength`   | `number`  | `0.03`  | 热流位移强度。                        |
| `scale`      | `number`  | `6`     | 火焰噪声场的缩放比例。                |
| `speed`      | `number`  | `1`     | 火焰动画速度。                        |
| `frameRate`  | `number`  | `60`    | 最大渲染帧率。                        |
| `pixelRatio` | `number`  | `1`     | 渲染比例，限制在 `0.25` 到 `2` 之间。 |
| `paused`     | `boolean` | `false` | 暂停渲染循环。                        |
| `autoPause`  | `boolean` | `true`  | 离开视口或页面隐藏时自动暂停。        |
| `class`      | `string`  | —       | 合并到效果表面的额外类名。            |

### 插槽

| 插槽      | 说明                       |
| --------- | -------------------------- |
| `default` | 通过效果渲染的 HTML 内容。 |

#credits

- 使用 [Ashima Arts](https://github.com/ashima/webgl-noise) 的 MIT 许可 Simplex Noise 实现。

::

---

### Cn 2.Components Html In Canvas Html Chromatic (`content/cn/2.components/html-in-canvas/html-chromatic.md`)

---
title: HTML 色差
description: 根据指针位置分离实时 HTML 的颜色通道。
category: HTML in Canvas
tags: [webgl, shader, canvas, chromatic, interactive]
badge: New
dependencies: []
---

::ComponentViewer{demoFile="HtmlChromaticDemo.vue" config="HtmlChromaticConfig" componentId="html-chromatic" :componentFiles='["HtmlChromatic.vue"]'}

#api

## API

| 属性           | 类型      | 默认值  | 说明                                  |
| -------------- | --------- | ------- | ------------------------------------- |
| `strength`     | `number`  | `0.03`  | 红色与蓝色通道的最大分离距离。        |
| `mouseDamping` | `number`  | `0.9`   | 应用于指针移动的平滑系数。            |
| `frameRate`    | `number`  | `60`    | 最大渲染帧率。                        |
| `pixelRatio`   | `number`  | `1`     | 渲染比例，限制在 `0.25` 到 `2` 之间。 |
| `paused`       | `boolean` | `false` | 暂停渲染循环。                        |
| `autoPause`    | `boolean` | `true`  | 离开视口或页面隐藏时自动暂停。        |
| `class`        | `string`  | —       | 合并到效果表面的额外类名。            |

### 插槽

| 插槽      | 说明                       |
| --------- | -------------------------- |
| `default` | 通过效果渲染的 HTML 内容。 |

::

---

### Cn 2.Components Html In Canvas Html Cloth (`content/cn/2.components/html-in-canvas/html-cloth.md`)

---
title: HTML 布料
description: 通过持续运动的布料向量场折叠实时 HTML。
category: HTML in Canvas
tags: [webgl, shader, canvas, cloth, animation]
badge: New
dependencies: []
---

::ComponentViewer{demoFile="HtmlClothDemo.vue" config="HtmlClothConfig" componentId="html-cloth" :componentFiles='["HtmlCloth.vue"]'}

#api

## API

| 属性         | 类型      | 默认值  | 说明                                  |
| ------------ | --------- | ------- | ------------------------------------- |
| `strength`   | `number`  | `0.03`  | 向量场位移强度。                      |
| `scale`      | `number`  | `6`     | 布料场的缩放比例。                    |
| `speed`      | `number`  | `1`     | 向量场的动画速度。                    |
| `frameRate`  | `number`  | `60`    | 最大渲染帧率。                        |
| `pixelRatio` | `number`  | `1`     | 渲染比例，限制在 `0.25` 到 `2` 之间。 |
| `paused`     | `boolean` | `false` | 暂停渲染循环。                        |
| `autoPause`  | `boolean` | `true`  | 离开视口或页面隐藏时自动暂停。        |
| `class`      | `string`  | —       | 合并到效果表面的额外类名。            |

### 插槽

| 插槽      | 说明                       |
| --------- | -------------------------- |
| `default` | 通过效果渲染的 HTML 内容。 |

#credits

- 向量场基于 [MartinRGB](https://www.shadertoy.com/view/DttSRB) 的作品。

::

---

### Cn 2.Components Html In Canvas Html Drag (`content/cn/2.components/html-in-canvas/html-drag.md`)

---
title: HTML 拖拽
description: 使用滚动速度和按压拖动弯曲实时 HTML。
category: HTML in Canvas
tags: [webgl, shader, canvas, scroll, interactive]
badge: New
dependencies: []
---

::ComponentViewer{demoFile="HtmlDragDemo.vue" config="HtmlDragConfig" componentId="html-drag" :componentFiles='["HtmlDrag.vue"]'}

在效果表面滚动即可弯曲分段 WebGL 平面。启用 `mouseEnabled` 可加入按压拖动变形；保持禁用则可选择 HTML 文本。

#api

## API

| 属性           | 类型      | 默认值  | 说明                                  |
| -------------- | --------- | ------- | ------------------------------------- |
| `strength`     | `number`  | `1.25`  | 垂直表面弯曲强度。                    |
| `mouseDamping` | `number`  | `0.9`   | 应用于指针移动的平滑系数。            |
| `mouseEnabled` | `boolean` | `false` | 启用按压拖动变形并关闭文本选择。      |
| `frameRate`    | `number`  | `60`    | 最大渲染帧率。                        |
| `pixelRatio`   | `number`  | `1`     | 渲染比例，限制在 `0.25` 到 `2` 之间。 |
| `paused`       | `boolean` | `false` | 暂停渲染循环。                        |
| `autoPause`    | `boolean` | `true`  | 离开视口或页面隐藏时自动暂停。        |
| `class`        | `string`  | —       | 合并到效果表面的额外类名。            |

### 插槽

| 插槽      | 说明                       |
| --------- | -------------------------- |
| `default` | 通过效果渲染的 HTML 内容。 |

::

---

### Cn 2.Components Html In Canvas Html In Canvas (`content/cn/2.components/html-in-canvas/html-in-canvas.md`)

---
title: HTML in Canvas
description: 通过实验性的 HTML-in-Canvas API，将 ShaderToy 风格的片元着色器应用到实时 HTML 内容。
category: HTML in Canvas
tags: [webgl, shader, canvas, interactive]
badge: New
dependencies: []
---

::ComponentViewer{demoFile="HtmlInCanvasDemo.vue" config="HtmlInCanvasConfig" componentId="html-in-canvas" :componentFiles='["HtmlInCanvas.vue", "HtmlInCanvasRenderer.ts", "captureElement.ts", "index.ts"]'}

HTML in Canvas 仍是实验性浏览器 API。浏览器不支持时，组件会捕获带样式的 DOM 快照，并通过同一个 WebGL 着色器处理。原始 DOM 仍保留交互能力和可访问性。

片元着色器必须定义 `mainImage(out vec4 fragColor, in vec2 fragCoord)`。捕获的 HTML 可通过 `iChannel0` 访问。

需要精简且类型明确的效果 API 时，请使用 `HtmlLiquid`、`HtmlChromatic`、`HtmlAscii`、`HtmlCloth`、`HtmlBlaze` 或 `HtmlDrag`。这些组件统一复用本组件的渲染与降级逻辑。

如果效果还需要顶点阶段逻辑，可传入 `vertexShaderCode`。它必须定义 `main()`，且不能包含 `#version` 指令。分段平面提供内置的 `vec2 position` 和 `vec2 textureCoord` 属性，两个着色器阶段可使用相同的 uniform。

#api

## API

| 属性               | 类型             | 默认值  | 说明                                       |
| ------------------ | ---------------- | ------- | ------------------------------------------ |
| `shaderCode`       | `string`         | —       | 包含 `mainImage` 函数的片元着色器代码。    |
| `vertexShaderCode` | `string`         | —       | 可选的顶点着色器代码，需包含 `main` 函数。 |
| `uniforms`         | `ShaderUniforms` | `{}`    | 自定义数字、布尔值、向量或矩阵 uniform。   |
| `frameRate`        | `number`         | `60`    | 最大渲染帧率。                             |
| `pixelRatio`       | `number`         | `1`     | 渲染比例，限制在 `0.25` 到 `2` 之间。      |
| `speed`            | `number`         | `1`     | 应用于 `iTime` 的速度倍率。                |
| `mouseDamping`     | `number`         | `0.85`  | 指针移动的平滑程度。                       |
| `paused`           | `boolean`        | `false` | 暂停渲染循环。                             |
| `autoPause`        | `boolean`        | `true`  | 离开视口或页面隐藏时自动暂停。             |
| `interactive`      | `boolean`        | `true`  | 跟踪指针并更新 `iMouse`。                  |
| `class`            | `string`         | —       | 合并到根元素的额外类名。                   |

### 着色器输入

组件按照 ShaderToy 约定提供 `iResolution`、`iTime`、`iTimeDelta`、`iFrameRate`、`iFrame`、`iMouse`、`iDate`、`iHasContent`、`iChannel0` 和 `iChannelResolution`。`iPointerVelocity`、`iPointerEnergy` 和 `iPointerAge` 提供会逐渐衰减的指针冲量，适合制作移动后自然平复的效果。指针进入或离开表面时，`iPointerInside` 会在 `0` 和 `1` 之间平滑过渡。`iScrollVelocity` 提供逐渐衰减的垂直滚轮输入，用于顶点形变。HTML 纹理可用时，`iHasContent` 为 `1`。

### 事件

| 事件      | 参数      | 说明                               |
| --------- | --------- | ---------------------------------- |
| `ready`   | —         | 首个 HTML 纹理完成渲染后触发。     |
| `error`   | `string`  | 着色器编译或渲染失败时触发。       |
| `support` | `boolean` | 返回原生 HTML-in-Canvas 支持状态。 |

### 插槽

| 插槽      | 说明                             |
| --------- | -------------------------------- |
| `default` | 作为着色器纹理捕获的 HTML 内容。 |

#credits

- 基于 [WICG HTML-in-Canvas 提案](https://github.com/WICG/html-in-canvas) 构建。

::

---

### Cn 2.Components Html In Canvas Html Liquid (`content/cn/2.components/html-in-canvas/html-liquid.md`)

---
title: HTML 液体
description: 通过响应指针移动的流动液面折射实时 HTML。
category: HTML in Canvas
tags: [webgl, shader, canvas, liquid, interactive]
badge: New
dependencies: []
---

::ComponentViewer{demoFile="HtmlLiquidDemo.vue" config="HtmlLiquidConfig" componentId="html-liquid" :componentFiles='["HtmlLiquid.vue"]'}

#api

## API

| 属性           | 类型      | 默认值  | 说明                                  |
| -------------- | --------- | ------- | ------------------------------------- |
| `strength`     | `number`  | `0.03`  | 纹理位移强度。                        |
| `frequency`    | `number`  | `18`    | 流体表面与指针涟漪的密度。            |
| `speed`        | `number`  | `3`     | 液体场的运动速度。                    |
| `mouseDamping` | `number`  | `0.9`   | 应用于指针移动的平滑系数。            |
| `frameRate`    | `number`  | `60`    | 最大渲染帧率。                        |
| `pixelRatio`   | `number`  | `1`     | 渲染比例，限制在 `0.25` 到 `2` 之间。 |
| `paused`       | `boolean` | `false` | 暂停渲染循环。                        |
| `autoPause`    | `boolean` | `true`  | 离开视口或页面隐藏时自动暂停。        |
| `class`        | `string`  | —       | 合并到效果表面的额外类名。            |

### 插槽

| 插槽      | 说明                       |
| --------- | -------------------------- |
| `default` | 通过效果渲染的 HTML 内容。 |

::

---

### Cn 2.Components Input And Forms Balance Slider (`content/cn/2.components/input-and-forms/balance-slider.md`)

---
title: 平衡滑块
description: 具备可调颜色、限制和交互提示的动态平衡滑块。
category: Forms & Input
tags: [css, tailwind, input]
---

::ComponentViewer{demoFile="BalanceSliderDemo.vue" config="BalanceSliderConfig" componentId="balance-slider" :componentFiles='["BalanceSlider.vue"]'}

#api

## API

| 属性名           | 类型     | 默认值      | 描述                      |
| ---------------- | -------- | ----------- | ------------------------- |
| `initialValue`   | `number` | `50`        | 滑块的初始位置（0-100）。 |
| `leftColor`      | `string` | `"#e68a00"` | 滑块左侧的背景色。        |
| `rightColor`     | `string` | `"#ffffff"` | 滑块右侧的背景色。        |
| `minShiftLimit`  | `number` | `40`        | 启动位移动画的最小阈值。  |
| `maxShiftLimit`  | `number` | `68`        | 关闭位移动画的最大阈值。  |
| `leftContent`    | `string` | `"LEFT"`    | 左侧提示中显示的文本。    |
| `rightContent`   | `string` | `"RIGHT"`   | 右侧提示中显示的文本。    |
| `indicatorColor` | `string` | `"#FFFFFF"` | 滑块中央指示器的颜色。    |

#credits

- 灵感与移植来自 [Jhey 的 CSS 版 Balance Slider](https://x.com/jh3yy/status/1748809599598399792?s=46)。
- 原始概念由 [Malay Vasa](https://x.com/MalayVasa/status/1748726374079381930) 提出。

::

---

### Cn 2.Components Input And Forms Color Picker (`content/cn/2.components/input-and-forms/color-picker.md`)

---
title: 取色器
description: 全功能的取色组件，支持多种颜色格式、无障碍特性与自定义色板。
category: Forms & Input
tags: [css, tailwind, input, color-picker, uplusion23]
---

::ComponentViewer{demoFile="ColorPickerDemo.vue" config="ColorPickerConfig" componentId="color-picker" :componentFiles='["ColorPicker.vue", "ObjectColorInput.vue", "ContrastRatio.vue", "index.ts"]' dependencies="@uiw/color-convert"}

#api

## API

### ColorPicker Props

| 属性名                | 类型                                            | 默认值      | 描述                        |
| --------------------- | ----------------------------------------------- | ----------- | --------------------------- |
| `value`               | `string \| HsvaColor \| HslaColor \| RgbaColor` | `undefined` | 当前颜色值，支持多种格式。  |
| `type`                | `'hsl' \| 'hsla' \| 'rgb' \| 'rgba' \| 'hex'`   | `'hsl'`     | 输入中默认显示的颜色格式。  |
| `swatches`            | `HexColor[]`                                    | `[]`        | 预设色板数组。              |
| `hideContrastRatio`   | `boolean`                                       | `false`     | 隐藏无障碍对比度区域。      |
| `hideDefaultSwatches` | `boolean`                                       | `false`     | 隐藏默认色板。              |
| `class`               | `string`                                        | `""`        | 用于弹出内容的额外 CSS 类。 |
| `open`                | `boolean`                                       | `false`     | 控制取色器的打开/关闭状态。 |

### ColorPicker Events

| 事件名         | 类型                                | 描述                         |
| -------------- | ----------------------------------- | ---------------------------- |
| `value-change` | `(value: ColorPickerValue) => void` | 当所选颜色变化时触发。       |
| `update:open`  | `(value: boolean) => void`          | 当弹出层打开状态改变时触发。 |

### ColorPickerValue 类型

```typescript
interface ColorPickerValue {
  hex: string; // 十六进制颜色（例如 "#ff0000"）
  hsl: HslaColor; // 具有 h、s、l、a 属性的 HSL 颜色对象
  hsla: HslaColor; // 具有 h、s、l、a 属性的 HSLA 颜色对象
  rgb: RgbaColor; // 具有 r、g、b、a 属性的 RGB 颜色对象
  rgba: RgbaColor; // 具有 r、g、b、a 属性的 RGBA 颜色对象
}
```

#credits

- 感谢 [kalix127](https://github.com/kalix127) 移植该组件。
- 灵感来自 [@uplusion23](https://21st.dev/uplusion23/color-picker/color-picker-with-swatches-and-onchange)。

::

---

### Cn 2.Components Input And Forms File Upload (`content/cn/2.components/input-and-forms/file-upload.md`)

---
title: 文件上传
description: 现代文件上传组件，带 3D 卡片效果、拖放交互和响应式网格背景。
category: Forms & Input
tags: [css, tailwind, input, aceternity-ui]
---

::ComponentViewer{demoFile="FileUploadDemo.vue" config="FileUploadConfig" componentId="file-upload" :componentFiles='["FileUpload.vue", "FileUploadGrid.vue"]'}

#api

## API

### `FileUpload`

`FileUpload` 组件是文件上传效果的包装容器，处理鼠标事件以创建 3D 视角。

#### Props

| 属性名  | 类型   | 默认值 | 描述                       |
| ------- | ------ | ------ | -------------------------- |
| `class` | String | -      | 用于容器元素的额外样式类。 |

#### Emits

| 事件名     | 类型                      | 描述                        |
| ---------- | ------------------------- | --------------------------- |
| `onChange` | `(files: File[]) => void` | 添加/上传文件时触发的回调。 |

### `FileUploadGrid`

`FileUploadGrid` 组件为上传区域提供背景网格图案，应在 `FileUpload` 内使用，以在上传界面背后呈现网格效果。

#### Props

| 属性名  | 类型   | 默认值 | 描述                     |
| ------- | ------ | ------ | ------------------------ |
| `class` | String | -      | 用于自定义样式的额外类。 |

#credits

- 感谢 [kalix127](https://github.com/kalix127) 移植该组件。
- 灵感来自 [AcernityUI](https://ui.aceternity.com/components/file-upload)。

::

---

### Cn 2.Components Input And Forms Halo Search (`content/cn/2.components/input-and-forms/halo-search.md`)

---
title: 光晕搜索框
description: 具有多重发光环与细微动画光晕的未来感搜索输入，为界面带来沉浸式体验。
category: Forms & Input
tags: [css, tailwind, input, ui-verse]
---

::ComponentViewer{demoFile="HaloSearchDemo.vue" config="HaloSearchConfig" componentId="halo-search" :componentFiles='["HaloSearch.vue"]'}

#api

## API

| 属性名  | 类型     | 默认值 | 描述                  |
| ------- | -------- | ------ | --------------------- |
| `class` | `string` | `""`   | 根容器的额外 CSS 类。 |

#credits

- 设计灵感来自未来感 UI 概念与现代 Web/App 设计中流行的氛围光效。
- 来源于 UiVerse 搜索输入挑战。

::

---

### Cn 2.Components Input And Forms Input (`content/cn/2.components/input-and-forms/input.md`)

---
title: 输入框
description: 具有径向悬停效果的多功能动态输入框，适配现代 Web 应用。
category: Forms & Input
tags: [css, tailwind, input, aceternity-ui]
---

::ComponentViewer{demoFile="InputDemo.vue" config="InputConfig" componentId="input" :componentFiles='["IInput.vue"]'}

#api

## API

| 属性名           | 类型                | 默认值 | 描述                                |
| ---------------- | ------------------- | ------ | ----------------------------------- |
| `defaultValue`   | `string  \| number` | `""`   | 输入框的默认值。                    |
| `class`          | `string`            | `""`   | 用于自定义样式的额外 CSS 类。       |
| `containerClass` | `string`            | `""`   | 容器的额外 CSS 类，用于自定义样式。 |

#credits

- 构建于 ShadCN Vue Input 组件之上，并扩展以适配现代 UI/UX 需求。
- 移植自 [Aceternity UI 的 Signup Form Input 组件](https://ui.aceternity.com/components/signup-form)。

::

---

### Cn 2.Components Input And Forms Placeholders And Vanish Input (`content/cn/2.components/input-and-forms/placeholders-and-vanish-input.md`)

---
title: 占位符滚动与消失输入框
description: 输入框占位符滑入，并在提交时呈现消失效果。
category: Forms & Input
tags: [css, tailwind, input, aceternity-ui]
---

::ComponentViewer{demoFile="VanishingInputDemo.vue" config="VanishingInputConfig" componentId="vanishing-input" :componentFiles='["VanishingInput.vue"]'}

#api

## API

| 属性名         | 类型            | 默认值                                                | 描述                                 |
| -------------- | --------------- | ----------------------------------------------------- | ------------------------------------ |
| `placeholders` | `Array<string>` | `["Placeholder 1", "Placeholder 2", "Placeholder 3"]` | 占位文本数组，会在输入框中轮换显示。 |

该组件监听 `VanishingInput` 发出的以下事件：

| 事件名   | 参数     | 描述                 |
| -------- | -------- | -------------------- |
| `change` | `Event`  | 当输入值变化时触发。 |
| `submit` | `string` | 当提交输入时触发。   |

#credits

- 感谢 [M Atif](https://github.com/atif0075) 移植该组件。
- 移植自 [Aceternity UI 的 Placeholders And Vanish Input](https://ui.aceternity.com/components/placeholders-and-vanish-input)。

::

---

### Cn 2.Components Miscellaneous Animate Grid (`content/cn/2.components/miscellaneous/animate-grid.md`)

---
title: 动画网格
description: 倾斜动画网格，带投影效果。
category: Miscellaneous
tags: [css, tailwind, input]
---

::ComponentViewer{demoFile="AnimateGridDemo.vue" config="AnimateGridConfig" componentId="animate-grid" :componentFiles='["AnimateGrid.vue"]'}

#instructions

#### 添加 SVG 文件

在组件同目录至少添加一个 SVG 文件，并在组件中更新导入路径使用该文件。

#api

## API

| 属性名               | 类型     | 默认值              | 描述                                   |
| -------------------- | -------- | ------------------- | -------------------------------------- |
| `textGlowStartColor` | `string` | `"#38ef7d80"`       | 盒子阴影的起始颜色。                   |
| `textGlowEndColor`   | `string` | `"#38ef7d"`         | 盒子阴影的结束颜色。                   |
| `perspective`        | `number` | `600`               | 传递给 CSS `transform` 的透视值。      |
| `rotateX`            | `number` | `-1`                | 传递给 CSS `transform` 的 rotateX 值。 |
| `rotateY`            | `number` | `-15`               | 传递给 CSS `transform` 的 rotateY 值。 |
| `cards`              | `[]`     | `"[{logo: 'src'}]"` | 要在网格中展示的卡片。                 |
| `class`              | `string` | `""`                | 自定义样式的额外 Tailwind CSS 类。     |

#credits

- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi) 提供该组件。

::

---

### Cn 2.Components Miscellaneous Animated Circular Progressbar (`content/cn/2.components/miscellaneous/animated-circular-progressbar.md`)

---
title: 动画圆形进度条
description: 显示百分比的圆形仪表盘动画组件。
category: Miscellaneous
tags: [css, tailwind, input, magic-ui]
---

::ComponentViewer{demoFile="AnimatedCircularProgressBarDemo.vue" config="AnimatedCircularProgressBarConfig" componentId="animated-circular-progressbar" :componentFiles='["AnimatedCircularProgressBar.vue"]'}

#api

## API

| 属性名                | 类型      | 默认值               | 描述                 |
| --------------------- | --------- | -------------------- | -------------------- |
| `class`               | `string`  | `-`                  | 应用于组件的类名。   |
| `max`                 | `number`  | `100`                | 仪表的最大值。       |
| `min`                 | `number`  | `0`                  | 仪表的最小值。       |
| `value`               | `number`  | `0`                  | 仪表当前值。         |
| `gaugePrimaryColor`   | `string`  | `rgb(79 70 229)`     | 仪表主色。           |
| `gaugeSecondaryColor` | `string`  | `rgba(0, 0, 0, 0.1)` | 仪表副色。           |
| `circleStrokeWidth`   | `number`  | `10`                 | 圆形进度条宽度。     |
| `showPercentage`      | `boolean` | `true`               | 是否在圆内显示数值。 |
| `duration`            | `number`  | `1`                  | 动画持续时间（秒）。 |

#credits

- 感谢 [Magic UI](https://magicui.design/docs/components/animated-circular-progress-bar)。
- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi) 移植该组件。

::

---

### Cn 2.Components Miscellaneous Animated List (`content/cn/2.components/miscellaneous/animated-list.md`)

---
title: 动画列表
description: 逐个引入的动画列表，适合在落地页展示通知或事件。
category: Miscellaneous
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="AnimatedListDemo.vue" config="AnimatedListConfig" componentId="animated-list" :componentFiles='["AnimatedList.vue", "Notification.vue"]'}

#api

## API

| 属性名  | 类型     | 默认值 | 描述                             |
| ------- | -------- | ------ | -------------------------------- |
| `delay` | `number` | `1`    | 在每个项目添加前的延迟（毫秒）。 |

#credits

- 灵感来自 [Magic UI](https://magicui.design/docs/components/animated-list)。

::

---

### Cn 2.Components Miscellaneous Animated Modal (`content/cn/2.components/miscellaneous/animated-modal.md`)

---
title: Animated Modal
description: 带 3D 入场动画与背景模糊效果的弹窗组件。
category: Miscellaneous
tags: [css, tailwind, modal, motion, aceternity-ui]
---

::ComponentViewer{demoFile="AnimatedModalDemo.vue" config="AnimatedModalConfig" componentId="animated-modal" :componentFiles='["AnimatedModal.vue", "AnimatedModalBody.vue", "AnimatedModalContent.vue", "AnimatedModalFooter.vue", "AnimatedModalTrigger.vue", "AnimatedModalContext.ts", "useAnimatedModal.ts", "index.ts"]' dependencies="motion-v @vueuse/core"}

#api

## API

### `<AnimatedModal />`

#### Props

| 属性名        | 类型      | 默认值  | 描述                 |
| ------------- | --------- | ------- | -------------------- |
| `open`        | `boolean` | `-`     | 受控的打开状态。     |
| `defaultOpen` | `boolean` | `false` | 非受控初始打开状态。 |
| `closeOnEsc`  | `boolean` | `true`  | 按 `Esc` 关闭弹窗。  |

#### Events

| 事件名        | 负载      | 描述                         |
| ------------- | --------- | ---------------------------- |
| `update:open` | `boolean` | 打开状态变化时触发。         |
| `open`        | -         | 调用 `openModal()` 时触发。  |
| `close`       | -         | 调用 `closeModal()` 时触发。 |

#### Slots

| 插槽名    | 插槽参数                                    |
| --------- | ------------------------------------------- |
| `default` | `open`, `openModal`, `closeModal`, `toggle` |

#### Composable

- `useAnimatedModal()` — 在任意子组件中获取弹窗状态/方法（必须在 `<AnimatedModal />` 内使用）。

### `<AnimatedModalBody />`

#### Props

| 属性名           | 类型                    | 默认值   | 描述                     |
| ---------------- | ----------------------- | -------- | ------------------------ |
| `class`          | `string`                | `""`     | 弹窗面板额外类名。       |
| `overlayClass`   | `string`                | `""`     | 遮罩层额外类名。         |
| `contentClass`   | `string`                | `""`     | 内容容器额外类名。       |
| `showClose`      | `boolean`               | `true`   | 是否显示关闭按钮。       |
| `closeOnOutside` | `boolean`               | `true`   | 点击弹窗外部是否关闭。   |
| `lockScroll`     | `boolean`               | `true`   | 打开时是否锁定页面滚动。 |
| `zIndex`         | `number`                | `10000`  | 弹窗层级。               |
| `teleportTo`     | `string \| HTMLElement` | `"body"` | Teleport 目标容器。      |

#credits

- 移植自 [Aceternity UI 的 Animated Modal](https://ui.aceternity.com/components/animated-modal)。
- 动画基于 [motion-v](https://motion.dev/)。

::

---

### Cn 2.Components Miscellaneous Animated Tabs (`content/cn/2.components/miscellaneous/animated-tabs.md`)

---
title: Animated Tabs
description: 带共享布局选中态胶囊与堆叠内容切换动画的 Tabs 组件。
category: Miscellaneous
tags: [css, tailwind, tabs, aceternity-ui, motion-v]
---

::ComponentViewer{demoFile="AnimatedTabsDemo.vue" config="AnimatedTabsConfig" componentId="animated-tabs" :componentFiles='["AnimatedTabs.vue", "AnimatedTabsFadeInDiv.vue", "types.ts", "index.ts"]' dependencies="motion-v"}

#api

## API

### `<AnimatedTabs />`

提示：建议给外层容器一个固定高度（例如 `h-[20rem] md:h-[40rem]`），因为内容区使用了 absolute 堆叠定位。

#### Props

| 属性名               | 类型            | 默认值 | 说明                         |
| -------------------- | --------------- | ------ | ---------------------------- |
| `tabs`               | `AnimatedTab[]` | `-`    | Tabs 元数据列表。            |
| `modelValue`         | `string`        | `-`    | 受控的当前激活 tab value。   |
| `containerClassName` | `string`        | `""`   | tablist 容器额外类名。       |
| `tabClassName`       | `string`        | `""`   | 每个 tab 按钮的额外类名。    |
| `activeTabClassName` | `string`        | `""`   | 选中态胶囊背景的额外类名。   |
| `contentClassName`   | `string`        | `""`   | 每个堆叠内容卡片的额外类名。 |

#### Events

| 事件名              | 参数     | 说明                              |
| ------------------- | -------- | --------------------------------- |
| `update:modelValue` | `string` | 激活 tab 变化时触发（受控模式）。 |

#### Slots

| 插槽名    | 插槽参数                    | 说明                    |
| --------- | --------------------------- | ----------------------- |
| `content` | `tab`, `active`, `hovering` | 渲染 tab 内容（推荐）。 |

#### Types

##### `AnimatedTab`

| 字段             | 类型                  | 必填 | 说明                                        |
| ---------------- | --------------------- | ---- | ------------------------------------------- |
| `title`          | `string`              | 是   | tab 文案（默认 UI 会使用它）。              |
| `value`          | `string`              | 是   | tab 唯一标识，用于激活态。                  |
| `panelClassName` | `string`              | 否   | 内容面板背景类名（示例/使用方可自行使用）。 |
| `content`        | `Component`           | 否   | 未提供 `#content` 插槽时的兜底内容组件。    |
| `contentProps`   | `Record<string, any>` | 否   | 传给 `content` 组件的 props。               |

#credits

- 移植自 [Aceternity UI Tabs](https://ui.aceternity.com/components/tabs)。
- 动画由 [motion-v](https://motion.dev/docs/vue) 提供支持。

::

---

### Cn 2.Components Miscellaneous Animated Tooltip (`content/cn/2.components/miscellaneous/animated-tooltip.md`)

---
title: 动画提示
description: 炫酷的提示气泡，悬停时揭示并跟随鼠标。
category: Miscellaneous
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="AnimatedTooltipDemo.vue" config="AnimatedTooltipConfig" componentId="animated-tooltip" :componentFiles='["AnimatedTooltip.vue"]'}

#api

## API

| 属性名  | 类型                                                                    | 默认值 | 描述                                                         |
| ------- | ----------------------------------------------------------------------- | ------ | ------------------------------------------------------------ |
| `items` | `Array<{id: number, name: string, designation: string, image: string}>` | `[]`   | 项目数组，每个对象需包含 id、name、designation、image 字段。 |

#credits

- 感谢 [M Atif](https://github.com/atif0075) 提供该组件。
- 灵感来自 [Aceternity UI's Animated Tooltip](https://ui.aceternity.com/components/animated-tooltip)。

::

---

### Cn 2.Components Miscellaneous Bento Grid (`content/cn/2.components/miscellaneous/bento-grid.md`)

---
title: Bento 网格
description: 炫酷的 Bento 网格布局，可放置不同子组件。
category: Miscellaneous
tags: [css, tailwind, bento, aceternity-ui]
---

::ComponentViewer{demoFile="BentoGridDemo.vue" config="BentoGridConfig" componentId="bento-grid" :componentFiles='["BentoGrid.vue", "BentoGridCard.vue", "BentoGridItem.vue"]'}

#api

#### `BentoGridItem`

| 插槽名        | 描述                 |
| ------------- | -------------------- |
| `title`       | 作为标题显示的组件。 |
| `description` | 作为描述显示的组件。 |
| `icon`        | 作为图标显示的组件。 |
| `header`      | 作为页眉显示的组件。 |

#### `BentoGridCard`

| 插槽名       | 描述               |
| ------------ | ------------------ |
| `background` | 显示在背景的组件。 |

| 属性名        | 类型      | 描述               |
| ------------- | --------- | ------------------ |
| `name`        | `string`  | 卡片上显示的名称。 |
| `icon`        | `?string` | 卡片上显示的图标。 |
| `description` | `string`  | 卡片的描述内容。   |
| `href`        | `string`  | CTA 对应的链接。   |
| `cta`         | `string`  | CTA 上显示的文字。 |

#credits

- 感谢 [Aceternity UI](https://ui.aceternity.com/components/bento-grid) 与 [Magic UI](https://magicui.design/docs/components/bento-grid) 的出色组件。

::

---

### Cn 2.Components Miscellaneous Book (`content/cn/2.components/miscellaneous/book.md`)

---
title: 书本
description: 可自定义尺寸与渐变的 3D 书本组件。
category: Miscellaneous
tags: [css, tailwind, x-ui]
---

::ComponentViewer{demoFile="BookDemo.vue" config="BookConfig" componentId="book" :componentFiles='["Book.vue", "BookHeader.vue", "BookTitle.vue", "BookDescription.vue", "index.ts"]'}

#api

## API

#### `Book`

| 属性名       | 类型    | 默认值 | 描述                     |
| ------------ | ------- | ------ | ------------------------ |
| `class`      | String  | -      | 应用于组件的额外类。     |
| `duration`   | Number  | 1000   | 动画持续时间（毫秒）。   |
| `color`      | String  | "zinc" | 书本渐变的配色主题。     |
| `isStatic`   | Boolean | false  | 为 true 时禁用悬停动画。 |
| `size`       | String  | "md"   | 书本尺寸变体。           |
| `radius`     | String  | "md"   | 书本圆角变体。           |
| `shadowSize` | String  | "lg"   | 阴影大小变体。           |

#### `BookHeader`

| 属性名  | 类型   | 默认值 | 描述                 |
| ------- | ------ | ------ | -------------------- |
| `class` | String | -      | 自定义样式的额外类。 |

#### `BookTitle`

| 属性名  | 类型   | 默认值 | 描述                 |
| ------- | ------ | ------ | -------------------- |
| `class` | String | -      | 自定义样式的额外类。 |

#### `BookDescription`

| 属性名  | 类型   | 默认值 | 描述                 |
| ------- | ------ | ------ | -------------------- |
| `class` | String | -      | 自定义样式的额外类。 |

#credits

- 感谢 [x/UI](https://ui.3x.gl/docs/book) 带来的灵感。
- 感谢 [kalix127](https://github.com/kalix127) 移植该组件。

::

---

### Cn 2.Components Miscellaneous Circular Gallery (`content/cn/2.components/miscellaneous/circular-gallery.md`)

---
title: 环形画廊
description: 让插槽内容沿圆周排列，并支持持续旋转和悬停暂停。
category: 杂项
tags: [css, tailwind, gallery]
badge: New
---

::ComponentViewer{demoFile="CircularGalleryDemo.vue" config="CircularGalleryConfig" componentId="circular-gallery" :componentFiles='["CircularGallery.vue", "index.ts"]'}

#api

## API

| 属性名         | 类型                  | 默认值   | 说明                           |
| -------------- | --------------------- | -------- | ------------------------------ |
| `radius`       | `number`              | `100`    | 子元素距离圆心的像素距离。     |
| `duration`     | `number`              | `10`     | 完成一整圈旋转所需的秒数。     |
| `easing`       | `string`              | `linear` | 旋转使用的 CSS 缓动函数。      |
| `direction`    | `normal` \| `reverse` | `normal` | 旋转方向。                     |
| `class`        | `string`              | —        | 根元素的额外类名。             |
| `pauseOnHover` | `boolean`             | `false`  | 鼠标悬停在子元素上时暂停旋转。 |

## 使用方式

通过默认插槽传入需要沿圆周排列的元素：

```vue
<CircularGallery :radius="140" :duration="12" pause-on-hover>
  <img src="/images/one.jpg" alt="One" class="size-24 object-cover" />
  <img src="/images/two.jpg" alt="Two" class="size-24 object-cover" />
  <img src="/images/three.jpg" alt="Three" class="size-24 object-cover" />
</CircularGallery>
```

#credits

- 移植自 [Fancy Components Circling Elements](https://fancycomponents.dev/docs/components/blocks/circling-elements)。

::

---

### Cn 2.Components Miscellaneous Compare (`content/cn/2.components/miscellaneous/compare.md`)

---
title: 对比
description: 通过滑动比较两组内容——图像、设计、代码或自定义元素。
category: Miscellaneous
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="CompareDemo.vue" config="CompareConfig" componentId="compare" :componentFiles='["Compare.vue", "StarField.vue"]'}

#api

## API

### Props

| 属性名                    | 类型                | 默认值           | 描述                         |
| ------------------------- | ------------------- | ---------------- | ---------------------------- |
| `firstImage`              | `string`            | `""`             | 第一张图片的 URL。           |
| `secondImage`             | `string`            | `""`             | 第二张图片的 URL。           |
| `firstImageAlt`           | `string`            | `"First image"`  | 第一张图片的替代文本。       |
| `secondImageAlt`          | `string`            | `"Second image"` | 第二张图片的替代文本。       |
| `class`                   | `string`            | `""`             | 组件的额外类名。             |
| `firstContentClass`       | `string`            | `""`             | 应用于第一侧内容包装器的类。 |
| `secondContentClass`      | `string`            | `""`             | 应用于第二侧内容包装器的类。 |
| `initialSliderPercentage` | `number`            | `50`             | 滑块初始位置（0-100）。      |
| `slideMode`               | `"hover" \| "drag"` | `"hover"`        | 滑块的交互模式。             |
| `showHandlebar`           | `boolean`           | `true`           | 是否显示手柄。               |
| `autoplay`                | `boolean`           | `false`          | 是否启用自动播放。           |
| `autoplayDuration`        | `number`            | `5000`           | 自动播放周期（毫秒）。       |

### Events

| 事件名              | 负载     | 描述                          |
| ------------------- | -------- | ----------------------------- |
| `update:percentage` | `number` | 滑块位置变化时触发（0-100）。 |
| `drag:start`        | -        | 开始拖动时触发。              |
| `drag:end`          | -        | 结束拖动时触发。              |
| `hover:enter`       | -        | 鼠标进入组件时触发。          |
| `hover:leave`       | -        | 鼠标离开组件时触发。          |

### Slots

| 插槽名           | 默认内容                               | 描述                                             |
| ---------------- | -------------------------------------- | ------------------------------------------------ |
| `first-content`  | 若提供 `firstImage` 则为 `<img>` 元素  | 左/第一侧展示的内容，拥有容器的全部宽高。        |
| `second-content` | 若提供 `secondImage` 则为 `<img>` 元素 | 右/第二侧展示的内容，拥有容器的全部宽高。        |
| `handle`         | 默认带圆点图标的滑块手柄               | 自定义滑块手柄，需自行使用绝对定位放在分割线处。 |

#credits

- 感谢 [M Atif](https://github.com/atif0075) 提供该组件。
- 灵感来自 [Aceternity UI's Compare](https://ui.aceternity.com/components/compare)。

::

---

### Cn 2.Components Miscellaneous Container Scroll (`content/cn/2.components/miscellaneous/container-scroll.md`)

---
title: 容器滚动
description: 根据滚动进度变换内部内容的滚动效果，包含缩放与旋转的平滑过渡。
category: Miscellaneous
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="ContainerScrollDemo.vue" config="ContainerScrollConfig" componentId="container-scroll" :componentFiles='["ContainerScroll.vue", "ContainerScrollTitle.vue", "ContainerScrollCard.vue"]'}

#api

## API

### `ContainerScroll`

`ContainerScroll` 创建 3D 滚动效果。用户滚动时，容器内的内容会随滚动进行缩放、旋转与位移。

| 属性名       | 类型   | 默认值 | 描述                       |
| ------------ | ------ | ------ | -------------------------- |
| `rotate`     | Number | `0`    | 控制滚动时内层内容的旋转。 |
| `scale`      | Number | `1`    | 控制滚动时内容的缩放。     |
| `translateY` | Number | `0`    | 控制滚动时标题的垂直位移。 |

### `ContainerScrollTitle`

`ContainerScrollTitle` 处理标题的垂直平移效果。

| 属性名      | 类型   | 默认值 | 描述                 |
| ----------- | ------ | ------ | -------------------- |
| `translate` | Number | `0`    | 控制标题的垂直位移。 |

### `ContainerScrollCard`

`ContainerScrollCard` 在滚动中为卡片应用缩放与旋转效果。

| 属性名   | 类型   | 默认值 | 描述                 |
| -------- | ------ | ------ | -------------------- |
| `rotate` | Number | `0`    | 控制卡片的旋转效果。 |
| `scale`  | Number | `1`    | 控制卡片的缩放效果。 |

## CSS 变量

可通过以下 CSS 变量自定义滚动动画与响应表现：

- **`--scale-start`**：卡片的初始缩放值。
- **`--scale-end`**：滚动过程中卡片的最终缩放值。
- **`--rotate-start`**：卡片的初始旋转值。
- **`--rotate-end`**：滚动过程中卡片的最终旋转值。

#credits

- 灵感来自 [Aceternity UI Container Scroll Animation](https://ui.aceternity.com/components/container-scroll-animation)。

::

---

### Cn 2.Components Miscellaneous Dock (`content/cn/2.components/miscellaneous/dock.md`)

---
title: Dock
description: 类似 macOS 的 Dock，悬停时放大图标。
category: Miscellaneous
tags: [css, tailwind]
---

::ComponentViewer{demoFile="DockDemo.vue" config="DockConfig" componentId="dock" :componentFiles='["Dock.vue", "DockIcon.vue", "DockSeparator.vue", "index.ts", "types.ts", "injectionKeys.ts"]'}

#api

## API

### `Dock`

| 属性名          | 类型     | 描述                                                         |
| --------------- | -------- | ------------------------------------------------------------ |
| `class`         | `string` | Dock 容器的额外类名。                                        |
| `magnification` | `number` | 悬停时图标的放大倍数（默认 60）。                            |
| `distance`      | `number` | 放大作用的图标中心距离。                                     |
| `direction`     | `string` | 图标对齐方式（`top`、`middle`、`bottom`，默认 middle）。     |
| `orientation`   | `string` | Dock 的方向（`vertical` 或 `horizontal`，默认 horizontal）。 |

| 插槽名    | 描述                    |
| --------- | ----------------------- |
| `default` | Dock 图标或其他子组件。 |

### `DockIcon`

| 插槽名    | 描述                             |
| --------- | -------------------------------- |
| `default` | 显示在 Dock 图标中的组件或图标。 |

#credits

- 设计灵感来自 macOS Dock 及其出色的悬停放大效果。

::

---

### Cn 2.Components Miscellaneous Expandable Gallery (`content/cn/2.components/miscellaneous/expandable-gallery.md`)

---
title: 可扩展画廊
description: 响应式图片画廊，悬停时动态放大图片。
category: Miscellaneous
tags: [css, tailwind, gallery]
---

::ComponentViewer{demoFile="ExpandableGalleryDemo.vue" config="ExpandableGalleryConfig" componentId="expandable-gallery" :componentFiles='["ExpandableGallery.vue"]'}

#api

## API

| 属性名   | 类型       | 默认值 | 描述                        |
| -------- | ---------- | ------ | --------------------------- |
| `images` | `string[]` | `[]`   | 画廊中显示的图片 URL 数组。 |

#credits

- 灵感来自 [David Mráz 的 Expandable Gallery](https://x.com/davidm_ml/status/1872319793124282653)

::

---

### Cn 2.Components Miscellaneous Float (`content/cn/2.components/miscellaneous/float.md`)

---
title: Float
description: 在三维位置和旋转轴上添加连续且自然的运动。
category: Miscellaneous
tags: [css, tailwind, motion-v, 3d, animation]
badge: New
dependencies: motion-v
---

::ComponentViewer{demoFile="FloatDemo.vue" config="FloatConfig" componentId="float" :componentFiles='["Float.vue", "index.ts"]'}

#api

## API

| 属性名          | 类型                       | 默认值          | 描述                                   |
| --------------- | -------------------------- | --------------- | -------------------------------------- |
| `speed`         | `number`                   | `0.5`           | 每帧的时间推进量。                     |
| `amplitude`     | `[number, number, number]` | `[10, 30, 30]`  | X、Y、Z 轴的位置移动范围，单位为像素。 |
| `rotationRange` | `[number, number, number]` | `[15, 15, 7.5]` | X、Y、Z 轴的旋转范围，单位为度。       |
| `timeOffset`    | `number`                   | `0`             | 用于错开多个浮动元素动画相位的偏移量。 |
| `class`         | `string`                   | —               | 合并到动画包装器的额外 class。         |

通过默认插槽传入需要动画的内容。组件会保留三维变换，并在每个动画帧更新位置。

#credits

- 移植自 [Fancy Components Float](https://fancycomponents.dev/docs/components/blocks/float)。

::

---

### Cn 2.Components Miscellaneous Images Slider (`content/cn/2.components/miscellaneous/images-slider.md`)

---
title: 图片滑块
description: 全屏图片滑块，可使用键盘导航。
category: Miscellaneous
tags: [css, tailwind, images, aceternity-ui]
---

::ComponentViewer{demoFile="ImagesSliderDemo.vue" config="ImagesSliderConfig" componentId="images-slider" :componentFiles='["ImagesSlider.vue"]'}

#api

## API

| 属性名             | 类型                       | 默认值                                            | 描述                                         |
| ------------------ | -------------------------- | ------------------------------------------------- | -------------------------------------------- |
| `images`           | `string[]`                 | `[]`                                              | 要在滑块中展示的图片 URL 数组。              |
| `hideOverlay`      | `boolean`                  | `false`                                           | 是否隐藏图片滑块的覆盖层（槽位将不会渲染）。 |
| `overlayClass`     | `string`                   | `''`                                              | 应用于覆盖层容器的类名。                     |
| `imageClass`       | `string`                   | `'bg-cover bg-center bg-no-repeat'`               | 应用于每张图片的类名。                       |
| `enterFromClass`   | `string`                   | `'scale-0 origin-center'`                         | 进入过渡的初始类名。                         |
| `enterActiveClass` | `string`                   | `'transition-transform duration-300 ease-in-out'` | 进入过渡的激活类名。                         |
| `leaveActiveClass` | `string`                   | `'transition-transform duration-300 ease-in-out'` | 离开过渡的激活类名。                         |
| `autoplay`         | `boolean\|number`          | `false`                                           | 自动播放间隔（毫秒），或 `false` 禁用。      |
| `direction`        | `'vertical'\|'horizontal'` | `'vertical'`                                      | 滑块运行的轴向。                             |
| `perspective`      | `string`                   | `'1000px'`                                        | 应用于滑块容器的透视值。                     |
| `modelValue`       | `number`                   | `0`                                               | 当前幻灯片索引的双向绑定。                   |

#credits

- 由 [Craig Riley](https://github.com/craigrileyuk) 移植此组件。
- 灵感来自 [Aceternity UI](https://ui.aceternity.com/components/images-slider)。

::

---

### Cn 2.Components Miscellaneous Lens (`content/cn/2.components/miscellaneous/lens.md`)

---
title: 放大镜
description: 用于放大图片、视频或任意元素的镜头组件。
category: Miscellaneous
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="LensDemo.vue" config="LensConfig" componentId="lens" :componentFiles='["Lens.vue", "Rays.vue", "Beams.vue"]'}

#api

## API

| 属性名       | 类型                       | 默认值               | 描述                                 |
| ------------ | -------------------------- | -------------------- | ------------------------------------ |
| `zoomFactor` | `number`                   | `1.5`                | 镜头的放大倍率。                     |
| `lensSize`   | `number`                   | `170`                | 镜头直径（像素）。                   |
| `position`   | `{ x: number, y: number }` | `{ x: 200, y: 150 }` | 静态模式下镜头的位置。               |
| `isStatic`   | `boolean`                  | `false`              | 为 `true` 时镜头固定；否则跟随鼠标。 |
| `hovering`   | `boolean`                  | `"false"`            | 外部控制悬停状态。                   |

#credits

- 感谢 [Aceternity UI](https://ui.aceternity.com/components/lens)。
- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi) 移植该组件。

::

---

### Cn 2.Components Miscellaneous Link Preview (`content/cn/2.components/miscellaneous/link-preview.md`)

---
title: 链接预览
description: 为锚点生成动态链接预览。
category: Miscellaneous
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="LinkPreviewDemo.vue" config="LinkPreviewConfig" componentId="link-preview" :componentFiles='["LinkPreview.vue"]' dependencies="qss"}

#api

## API

| 属性名      | 类型      | 默认值  | 描述                                                           |
| ----------- | --------- | ------- | -------------------------------------------------------------- |
| `class`     | `string`  | `""`    | 应用于主元素的自定义类。                                       |
| `linkClass` | `string`  | `""`    | 应用于链接元素的自定义类。                                     |
| `width`     | `number`  | `200`   | 预览图的宽度。                                                 |
| `height`    | `number`  | `125`   | 预览图的高度。                                                 |
| `isStatic`  | `boolean` | `false` | 预览图是否为静态图；设为 `true` 使用静态模式。                 |
| `imageSrc`  | `string`  | `""`    | 静态模式下要显示的图片来源（`isStatic` 为 `true` 时必填）。    |
| `url`       | `string`  | `""`    | 链接的 URL，同时用于生成预览（`isStatic` 为 `false` 时必填）。 |

#credits

- 感谢 [M Atif](https://github.com/atif0075) 移植该组件。
- 移植自 [Aceternity UI's Link Preview](https://ui.aceternity.com/components/link-preview)。

::

---

### Cn 2.Components Miscellaneous Marquee (`content/cn/2.components/miscellaneous/marquee.md`)

---
title: 跑马灯
description: 可定制的循环滚动组件，支持水平/垂直方向、悬停暂停与重复次数。
category: Miscellaneous
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="MarqueeDemo.vue" config="MarqueeConfig" componentId="marquee" :componentFiles='["Marquee.vue", "ReviewCard.vue"]'}

#api

## API

| 属性名         | 类型      | 默认值  | 描述                                     |
| -------------- | --------- | ------- | ---------------------------------------- |
| `class`        | `string`  | `''`    | 应用于最外层容器的自定义类。             |
| `reverse`      | `boolean` | `false` | 设置滚动方向为反向（从右到左或下到上）。 |
| `pauseOnHover` | `boolean` | `false` | 悬停时暂停跑马灯动画。                   |
| `vertical`     | `boolean` | `false` | 将滚动方向设为垂直。                     |
| `repeat`       | `number`  | `4`     | 内容重复的次数。                         |

## CSS 变量

可通过以下 CSS 变量自定义速度与间距：

- **`--duration`**：控制跑马灯动画速度。
- **`--gap`**：设置重复项之间的间距。

#credits

- 灵感来自 [Magic UI](https://magicui.design/docs/components/marquee)。

::

---

### Cn 2.Components Miscellaneous Media Text (`content/cn/2.components/miscellaneous/media-text.md`)

---
title: 媒体文字
description: 在两段文字之间显示图片或视频，并支持悬停、进入视口或 ref 触发。
category: Miscellaneous
tags: [media, image, video, motion-v]
badge: New
dependencies: []
---

::ComponentViewer{demoFile="MediaTextDemo.vue" config="MediaTextConfig" componentId="media-text" :componentFiles='["MediaText.vue", "index.ts"]'}

#api

## API

| 属性名                | 类型                           | 默认值                        | 描述                             |
| --------------------- | ------------------------------ | ----------------------------- | -------------------------------- |
| `firstText`           | `string`                       | —                             | 媒体前显示的文字。               |
| `secondText`          | `string`                       | —                             | 媒体后显示的文字。               |
| `mediaUrl`            | `string`                       | —                             | 图片或视频地址。                 |
| `mediaType`           | `"image" \| "video"`           | —                             | 要渲染的媒体类型。               |
| `mediaContainerClass` | `string`                       | —                             | 应用于媒体动画容器的 class。     |
| `fallbackUrl`         | `string`                       | —                             | 视频使用的封面地址。             |
| `as`                  | `string`                       | `p`                           | 文字片段使用的 HTML 元素。       |
| `autoPlay`            | `boolean`                      | `true`                        | 视频是否自动播放。               |
| `loop`                | `boolean`                      | `true`                        | 视频是否循环播放。               |
| `muted`               | `boolean`                      | `true`                        | 视频是否静音。                   |
| `playsInline`         | `boolean`                      | `true`                        | 是否在移动设备中以内联方式播放。 |
| `alt`                 | `string`                       | 自动生成                      | 图片的替代文本。                 |
| `triggerType`         | `"hover" \| "ref" \| "inView"` | `hover`                       | 媒体显示的触发方式。             |
| `useInViewOptions`    | `UseInViewOptions`             | `{ once: true, amount: 0.5 }` | 传给视口触发器的配置。           |
| `animationVariants`   | `object`                       | 宽度弹簧展开                  | 媒体容器使用的 Motion variants。 |
| `class`               | `string`                       | —                             | 合并到根元素的 class。           |
| `leftTextClass`       | `string`                       | —                             | 第一个文字片段的 class。         |
| `rightTextClass`      | `string`                       | —                             | 第二个文字片段的 class。         |

使用 `ref` 触发时，组件会暴露 `animate()` 和 `reset()` 方法。

#credits

- 移植自 [Fancy Components Media Between Text](https://fancycomponents.dev/docs/components/blocks/media-between-text)。

::

---

### Cn 2.Components Miscellaneous Morphing Tabs (`content/cn/2.components/miscellaneous/morphing-tabs.md`)

---
title: 变形标签页
description: 复刻 Preet 的胶状变形标签交互，包含粘连效果。
category: Miscellaneous
tags: [css, tailwind]
---

::ComponentViewer{demoFile="MorphingTabsDemo.vue" config="MorphingTabsConfig" componentId="morphing-tabs" :componentFiles='["MorphingTabs.vue"]'}

#api

## API

| 属性名             | 类型       | 默认值 | 描述                         |
| ------------------ | ---------- | ------ | ---------------------------- |
| `class`            | `string`   | `""`   | 用于样式的额外类名。         |
| `tabs`             | `string[]` | `[]`   | 标签集合。                   |
| `activeTab`        | `string`   | `""`   | 当前激活的标签。             |
| `margin`           | `number`   | `20`   | 激活标签左右的外边距。       |
| `blurStdDeviation` | `number`   | `6`    | SVG 模糊的 stdDeviation 值。 |

#credits

- 感谢 [Whbbit1999](https://github.com/Whbbit1999) 提供该组件。
- 灵感并移植自 [@Preet \"Exclusion tabs\"](https://x.com/wickedmishra/status/1823026659894940124)。

::

---

### Cn 2.Components Miscellaneous Multi Step Loader (`content/cn/2.components/miscellaneous/multi-step-loader.md`)

---
title: 多步加载器
description: 多步骤加载组件，支持异步条件。
category: Miscellaneous
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="MultiStepLoaderDemo.vue" config="MultiStepLoaderConfig" componentId="multi-step-loader" :componentFiles='["MultiStepLoader.vue"]'}

#api

## API

| 属性名            | 类型      | 默认值  | 描述                                 |
| ----------------- | --------- | ------- | ------------------------------------ |
| `loading`         | `boolean` | `false` | 控制加载器可见性，为 `true` 时显示。 |
| `steps`           | `Step[]`  | `[]`    | 定义加载序列的步骤数组。             |
| `defaultDuration` | `number`  | `1500`  | 每个步骤的持续时间（毫秒）。         |
| `preventClose`    | `boolean` | `false` | 若为 `true`，不显示关闭按钮。        |

| 事件名         | 负载类型 | 描述                                 |
| -------------- | -------- | ------------------------------------ |
| `state-change` | `number` | 当前步骤变化时触发，返回新步骤索引。 |
| `complete`     | `void`   | 所有步骤完成时触发。                 |
| `close`        | `void`   | 点击按钮关闭加载器时触发。           |

#credits

- 感谢 [M Atif](https://github.com/atif0075) 提供该组件。
- 灵感来自 [Aceternity UI's Multi Step Loader](https://ui.aceternity.com/components/multi-step-loader)。

::

---

### Cn 2.Components Miscellaneous Parallax Float (`content/cn/2.components/miscellaneous/parallax-float.md`)

---
title: 视差浮动
description: 为分层内容添加由光标驱动的深度和独立浮动效果。
category: 杂项
tags: [motion, parallax, images]
badge: New
dependencies: motion-v
---

::ComponentViewer{demoFile="ParallaxFloatDemo.vue" config="ParallaxFloatConfig" componentId="parallax-float" :componentFiles='["ParallaxFloat.vue", "ParallaxFloatElement.vue", "ParallaxFloatContext.ts", "index.ts"]'}

#api

## API

### ParallaxFloat

| 属性名         | 类型     | 默认值 | 说明                           |
| -------------- | -------- | ------ | ------------------------------ |
| `sensitivity`  | `number` | `1`    | 应用于每个元素深度的移动倍数。 |
| `easingFactor` | `number` | `0.05` | 每帧向目标位置插值的比例。     |
| `class`        | `string` | —      | 容器的额外类名。               |

### ParallaxFloatElement

| 属性名  | 类型     | 默认值 | 说明                       |
| ------- | -------- | ------ | -------------------------- |
| `depth` | `number` | `1`    | 元素相对于光标的移动深度。 |
| `class` | `string` | —      | 元素的位置和样式类名。     |

## 使用方式

使用 `ParallaxFloat` 作为容器，将每个需要独立移动的图层放入 `ParallaxFloatElement`：

```vue
<ParallaxFloat :sensitivity="-1">
  <ParallaxFloatElement :depth="2" class="top-1/4 left-1/3">
    <img src="/images/portrait.jpg" alt="Portrait" class="size-32 object-cover" />
  </ParallaxFloatElement>
</ParallaxFloat>
```

#credits

- 移植自 [Fancy Components Parallax Floating](https://fancycomponents.dev/docs/components/image/parallax-floating)。

::

---

### Cn 2.Components Miscellaneous Path Marquee (`content/cn/2.components/miscellaneous/path-marquee.md`)

---
title: 路径跑马灯
description: 让重复内容沿 SVG 路径移动，并支持悬停减速和拖拽控制。
category: Miscellaneous
tags: [svg, motion-v, marquee, drag]
badge: New
dependencies: []
---

::ComponentViewer{demoFile="PathMarqueeDemo.vue" config="PathMarqueeConfig" componentId="path-marquee" :componentFiles='["PathMarquee.vue", "index.ts"]'}

#api

## API

| 属性                       | 类型                        | 默认值                            | 描述                              |
| -------------------------- | --------------------------- | --------------------------------- | --------------------------------- |
| `path`                     | `string`                    | —                                 | 用于定位每个项目的 SVG 路径数据。 |
| `pathId`                   | `string`                    | 自动生成                          | SVG 路径使用的 ID。               |
| `showPath`                 | `boolean`                   | `false`                           | 是否显示路径线条。                |
| `width`                    | `string \| number`          | `"100%"`                          | SVG 宽度。                        |
| `height`                   | `string \| number`          | `"100%"`                          | SVG 高度。                        |
| `viewBox`                  | `string`                    | `"0 0 100 100"`                   | SVG 坐标系统。                    |
| `preserveAspectRatio`      | `string`                    | `"xMidYMid meet"`                 | SVG 宽高比行为。                  |
| `baseVelocity`             | `number`                    | `5`                               | 自动移动速度。                    |
| `direction`                | `"normal" \| "reverse"`     | `"normal"`                        | 初始移动方向。                    |
| `easing`                   | `(value: number) => number` | —                                 | 可选的路径进度缓动函数。          |
| `slowdownOnHover`          | `boolean`                   | `false`                           | 悬停项目时降低移动速度。          |
| `slowDownFactor`           | `number`                    | `0.3`                             | 悬停时的速度倍率。                |
| `slowDownSpringConfig`     | `object`                    | `{ damping: 50, stiffness: 400 }` | 悬停速度变化使用的弹簧配置。      |
| `useScrollVelocity`        | `boolean`                   | `false`                           | 将滚动速度加入移动速度。          |
| `scrollAwareDirection`     | `boolean`                   | `false`                           | 根据最近的滚动方向改变移动方向。  |
| `scrollSpringConfig`       | `object`                    | `{ damping: 50, stiffness: 400 }` | 滚动速度使用的弹簧配置。          |
| `repeat`                   | `number`                    | `3`                               | 默认插槽内容的重复次数。          |
| `draggable`                | `boolean`                   | `false`                           | 是否允许沿路径拖拽。              |
| `dragSensitivity`          | `number`                    | `0.2`                             | 应用于拖拽速度的倍率。            |
| `dragVelocityDecay`        | `number`                    | `0.96`                            | 释放拖拽后的动量衰减。            |
| `dragAwareDirection`       | `boolean`                   | `false`                           | 是否自动跟随最近一次拖拽方向。    |
| `grabCursor`               | `boolean`                   | `false`                           | 可拖拽时是否使用抓取光标。        |
| `enableRollingZIndex`      | `boolean`                   | `true`                            | 是否根据路径位置设置项目层级。    |
| `zIndexBase`               | `number`                    | `1`                               | 起始 z-index。                    |
| `zIndexRange`              | `number`                    | `10`                              | 沿路径使用的层级范围。            |
| `cssVariableInterpolation` | `object[]`                  | `[]`                              | 根据路径进度插值 CSS 变量。       |
| `responsive`               | `boolean`                   | `false`                           | 是否缩放坐标空间以适应容器。      |
| `class`                    | `string`                    | —                                 | 合并到根元素的额外 class。        |

通过默认插槽传入一个或多个元素。每个插槽元素会被重复，并沿路径定位。

#credits

- 移植自 [Fancy Components Marquee Along SVG Path](https://fancycomponents.dev/docs/components/blocks/marquee-along-svg-path)。

::

---

### Cn 2.Components Miscellaneous Photo Gallery (`content/cn/2.components/miscellaneous/photo-gallery.md`)

---
title: 照片画廊
description: 用精美的画廊展示团队风采。
category: Miscellaneous
tags: [css, tailwind, gallery]
---

::ComponentViewer{demoFile="PhotoGalleryDemo.vue" config="PhotoGalleryConfig" componentId="photo-gallery" :componentFiles='["PhotoGallery.vue"]'}

#api

## API

| 属性名           | 类型                | 默认值 | 描述                               |
| ---------------- | ------------------- | ------ | ---------------------------------- |
| `items`          | `"[{src: string}]"` | `[]`   | 传入要动画的图片项/图片源。        |
| `containerClass` | `string`            | `""`   | 容器的额外 Tailwind CSS 类。       |
| `class`          | `string`            | `""`   | 自定义样式的额外 Tailwind CSS 类。 |

#credits

- 所有图片来自 [Pexels](https://www.pexels.com/@soldiervip/)
- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi) 提供该组件。

::

---

### Cn 2.Components Miscellaneous Scroll Island (`content/cn/2.components/miscellaneous/scroll-island.md`)

---
title: 滚动岛
description: 具备动态动画的交互组件，展示滚动进度，并带可展开的附加内容区域。
category: Miscellaneous
tags: [css, tailwind, number-flow]
---

::ComponentViewer{demoFile="ScrollIslandDemo.vue" config="ScrollIslandConfig" componentId="scroll-island" :componentFiles='["ScrollIsland.vue"]' dependencies="@number-flow/vue"}

#api

## API

| 属性名   | 类型     | 默认值       | 描述                      |
| -------- | -------- | ------------ | ------------------------- |
| `class`  | `string` | `""`         | 自定义样式的额外 CSS 类。 |
| `title`  | `string` | `"Progress"` | 组件头部显示的标题。      |
| `height` | `string` | `44`         | 组件高度。                |

#credits

- 灵感来自 [Ali Samadi](https://x.com/alisamadi__/status/1854312982559502556) 与 [Nitish Khagwal](https://x.com/nitishkmrk)
- [NumberFlow by Maxwell Barvian](https://number-flow.barvian.me/vue) 用于数字格式化与动画。

::

---

### Cn 2.Components Miscellaneous Shader Toy (`content/cn/2.components/miscellaneous/shader-toy.md`)

---
title: Shader Toy Viewer
description: 在浏览器中渲染 ShaderToy GLSL 着色器的强大灵活组件。
category: Miscellaneous
tags: [css, tailwind, shader-toy, ogl, webgl]
badge: Updated
---

::ComponentViewer{demoFile="ShaderToyDemo.vue" config="ShaderToyConfig" componentId="shader-toy" :componentFiles='["ShaderToy.vue", "InspiraShaderToy.ts"]' dependencies="ogl"}

#api

## API

| 属性名       | 类型                                 | 默认值    | 描述                                    |
| ------------ | ------------------------------------ | --------- | --------------------------------------- |
| `shaderCode` | `string`                             | `-`       | 来自 ShaderToy 的 GLSL 片段着色器源码。 |
| `uniforms`   | `Record<string, number \| number[]>` | `{}`      | 着色器中声明的自定义 uniform 值。       |
| `mouseMode`  | `'click' \| 'hover'`                 | `'click'` | 鼠标跟踪模式：点击或持续悬停。          |
| `hue`        | `number`                             | `0`       | 调整着色器输出的色相。                  |
| `saturation` | `number`                             | `1`       | 调整着色器输出的饱和度。                |
| `brightness` | `number`                             | `1`       | 调整着色器输出的亮度。                  |
| `speed`      | `number`                             | `1`       | 调整着色器输出的速度。                  |
| `frameRate`  | `number`                             | `60`      | 为较重的着色器限制渲染帧率。            |
| `pixelRatio` | `number`                             | `1`       | 控制画布渲染倍率，平衡清晰度与性能。    |
| `paused`     | `boolean`                            | `false`   | 手动暂停播放。                          |
| `autoPause`  | `boolean`                            | `true`    | 离开视口或标签页隐藏时暂停渲染。        |
| `class`      | `string`                             | `-`       | 应用于容器的自定义类。                  |

#credits

- 使用 [OGL](https://github.com/oframe/ogl) 构建。
- 灵感来自 [Shadertoy](https://shadertoy.com/)，并为 Vue 兼容性做了适配。

::

---

### Cn 2.Components Miscellaneous Svg Mask (`content/cn/2.components/miscellaneous/svg-mask.md`)

---
title: SVG 遮罩
description: 通过悬停与鼠标移动揭示内容的动态 SVG 遮罩组件。
category: Miscellaneous
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="SvgMaskDemo.vue" config="SvgMaskConfig" componentId="svg-mask" :componentFiles='["SVGMask.vue"]'}

#api

## API

| 属性名       | 类型     | 默认值 | 描述                          |
| ------------ | -------- | ------ | ----------------------------- |
| `class`      | `string` | `""`   | 用于自定义样式的额外 CSS 类。 |
| `size`       | `number` | `10`   | 遮罩的初始大小（像素）。      |
| `revealSize` | `number` | `600`  | 悬停时遮罩的大小（像素）。    |

#credits

- 移植自 [Aceternity UI's SVG Mask Effect](https://ui.aceternity.com/components/text-generate-effect)。

::

---

### Cn 2.Components Miscellaneous Timeline (`content/cn/2.components/miscellaneous/timeline.md`)

---
title: 时间线
description: 视觉化、交互式的时间线组件，带平滑动画、粘性标签与渐变滚动效果。
category: Miscellaneous
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="TimelineDemo.vue" config="TimelineConfig" componentId="timeline" :componentFiles='["Timeline.vue"]'}

#api

## API

| 属性名           | 类型                               | 默认值 | 描述                                 |
| ---------------- | ---------------------------------- | ------ | ------------------------------------ |
| `containerClass` | `string`                           | `""`   | 时间线容器的额外 CSS 类。            |
| `class`          | `string`                           | `""`   | 其他样式的额外 CSS 类。              |
| `items`          | `{ id: string; label: string; }[]` | `[]`   | 时间线条目列表，每项包含 ID 与标签。 |
| `title`          | `string`                           | `""`   | 时间线部分的标题。                   |
| `description`    | `string`                           | `""`   | 显示在标题下方的描述文字。           |

#credits

- 灵感并移植自 [Aceternity UI's Timeline](https://ui.aceternity.com/components/timeline)。

::

---

### Cn 2.Components Miscellaneous Tracing Beam (`content/cn/2.components/miscellaneous/tracing-beam.md`)

---
title: 跟踪光束
description: 渲染跟踪光束效果的组件，支持动态滚动动画与渐变描边。
category: Miscellaneous
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="TracingBeamDemo.vue" config="TracingBeamConfig" componentId="tracing-beam" :componentFiles='["TracingBeam.vue"]'}

#api

## API

| 属性名  | 类型     | 默认值 | 描述                          |
| ------- | -------- | ------ | ----------------------------- |
| `class` | `string` | `""`   | 用于自定义样式的额外 CSS 类。 |

#credits

- 移植自 [Aceternity UI](https://ui.aceternity.com/components/tracing-beam);

::

---

### Cn 2.Components Special Effects Animated Beam (`content/cn/2.components/special-effects/animated-beam.md`)

---
title: 动画光束
description: 通过 SVG 连接元素的光束动画。
category: Special Effects
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="AnimatedBeamDemo.vue" config="AnimatedBeamConfig" componentId="animated-beam" :componentFiles='["AnimatedBeam.vue"]'}

#api

## API

| 属性名               | 类型          | 默认值                 | 描述                                  |
| -------------------- | ------------- | ---------------------- | ------------------------------------- |
| `class`              | `string`      | `""`                   | 应用于组件的额外 CSS 类，便于自定义。 |
| `containerRef`       | `HTMLElement` | N/A                    | 渲染光束的容器元素引用。              |
| `fromRef`            | `HTMLElement` | N/A                    | 光束起点元素的引用。                  |
| `toRef`              | `HTMLElement` | N/A                    | 光束终点元素的引用。                  |
| `curvature`          | `number`      | `0`                    | 控制光束弯曲程度，值越大弯曲越明显。  |
| `reverse`            | `boolean`     | `false`                | 为 `true` 时反转光束动画方向。        |
| `pathColor`          | `string`      | `"gray"`               | 光束路径的颜色。                      |
| `pathWidth`          | `number`      | `2`                    | 光束路径的描边宽度。                  |
| `pathOpacity`        | `number`      | `0.2`                  | 光束路径的不透明度。                  |
| `gradientStartColor` | `string`      | `"#FFAA40"`            | 光束渐变动画的起始颜色。              |
| `gradientStopColor`  | `string`      | `"#9C40FF"`            | 光束渐变动画的结束颜色。              |
| `delay`              | `number`      | `0`                    | 动画开始前的延迟（秒）。              |
| `duration`           | `number`      | `Random between 4–7 s` | 光束动画循环的持续时间（秒）。        |
| `startXOffset`       | `number`      | `0`                    | 光束起点的水平偏移。                  |
| `startYOffset`       | `number`      | `0`                    | 光束起点的垂直偏移。                  |
| `endXOffset`         | `number`      | `0`                    | 光束终点的水平偏移。                  |
| `endYOffset`         | `number`      | `0`                    | 光束终点的垂直偏移。                  |

#credits

- 灵感并移植自 [Magic UI Animated Beam](https://magicui.design/docs/components/animated-beam)。

::

---

### Cn 2.Components Special Effects Border Beam (`content/cn/2.components/special-effects/border-beam.md`)

---
title: 边框光束
description: 可定制尺寸、时长、颜色与延迟的炫酷动画边框光束效果。
category: Special Effects
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="BorderBeamDemo.vue" config="BorderBeamConfig" componentId="border-beam" :componentFiles='["BorderBeam.vue"]'}

#api

## API

| 属性名        | 类型     | 默认值      | 描述                               |
| ------------- | -------- | ----------- | ---------------------------------- |
| `class`       | `string` | `""`        | 用于自定义样式的额外 CSS 类。      |
| `size`        | `number` | `200`       | 动画边框光束的尺寸。               |
| `duration`    | `number` | `15`        | 动画持续时间（秒）。               |
| `borderWidth` | `number` | `1.5`       | 光束边框的宽度。                   |
| `anchor`      | `number` | `90`        | 光束的锚点，决定其在边框上的位置。 |
| `colorFrom`   | `string` | `"#ffaa40"` | 光束渐变的起始颜色。               |
| `colorTo`     | `string` | `"#9c40ff"` | 光束渐变的结束颜色。               |
| `delay`       | `number` | `0`         | 动画开始前的延迟时间（秒）。       |

#credits

- 移植自 [Magic UI](https://magicui.design/docs/components/border-beam)。

::

---

### Cn 2.Components Special Effects Confetti (`content/cn/2.components/special-effects/confetti.md`)

---
title: 彩带
description: 用于彩带动画的 Vue 组件。
category: Special Effects
tags: [css, tailwind, canvas, magic-ui]
---

::ComponentViewer{demoFile="ConfettiDemo.vue" config="ConfettiConfig" componentId="confetti" :componentFiles='["Confetti.vue", "ConfettiButton.vue"]' dependencies="canvas-confetti" devDependencies="@types/canvas-confetti"}

#api

## API

### Props

#### `Confetti`

| 属性名          | 类型                    | 默认值  | 描述                                  |
| --------------- | ----------------------- | ------- | ------------------------------------- |
| `options`       | `ConfettiOptions`       | `{}`    | 单次彩带的配置项。                    |
| `globalOptions` | `ConfettiGlobalOptions` | `{}`    | 彩带实例的全局配置（如自适应尺寸）。  |
| `manualstart`   | `boolean`               | `false` | 若为 `true`，组件挂载时不会自动启动。 |

#### `ConfettiOptions`

| 属性                      | 类型                        | 默认值                                                                          | 描述                                        |
| ------------------------- | --------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------- |
| `particleCount`           | `number`                    | `50`                                                                            | 发射的彩带颗粒数量。                        |
| `angle`                   | `number`                    | `90`                                                                            | 发射彩带的角度（度）。                      |
| `spread`                  | `number`                    | `45`                                                                            | 彩带的扩散角度（度）。                      |
| `startVelocity`           | `number`                    | `45`                                                                            | 彩带颗粒的初始速度。                        |
| `decay`                   | `number`                    | `0.9`                                                                           | 彩带颗粒减速的速率。                        |
| `gravity`                 | `number`                    | `1`                                                                             | 作用于彩带颗粒的重力。                      |
| `drift`                   | `number`                    | `0`                                                                             | 彩带颗粒的水平漂移。                        |
| `ticks`                   | `number`                    | `200`                                                                           | 彩带动画持续的帧数。                        |
| `origin`                  | `{ x: number, y: number }`  | `{ x: 0.5, y: 0.5 }`                                                            | 彩带发射的原点（0 到 1 之间）。             |
| `colors`                  | `string[]`                  | `['#26ccff', '#a25afd', '#ff5e7e', '#88ff5a', '#fcff42', '#ffa62d', '#ff36ff']` | 彩带颗粒的 HEX 颜色数组。                   |
| `shapes`                  | `string[]`                  | `['square', 'circle']`                                                          | 彩带颗粒的形状数组。                        |
| `scalar`                  | `number`                    | `1`                                                                             | 彩带颗粒大小的缩放因子。                    |
| `zIndex`                  | `number`                    | `100`                                                                           | 彩带画布元素的 z-index。                    |
| `disableForReducedMotion` | `boolean`                   | `false`                                                                         | 若用户偏好减少动画时禁用彩带。              |
| `useWorker`               | `boolean`                   | `true`                                                                          | 使用 Web Worker 以获得更好性能。            |
| `resize`                  | `boolean`                   | `true`                                                                          | 窗口尺寸变化时是否自动调整画布大小。        |
| `canvas`                  | `HTMLCanvasElement \| null` | `null`                                                                          | 自定义用于绘制彩带的 canvas 元素。          |
| `gravity`                 | `number`                    | `1`                                                                             | 作用于彩带颗粒的重力。                      |
| `drift`                   | `number`                    | `0`                                                                             | 彩带颗粒的水平漂移。                        |
| `flat`                    | `boolean`                   | `false`                                                                         | 若为 `true`，彩带颗粒将不旋转或无 3D 效果。 |

#### `ConfettiButton`

| 属性名    | 类型                                               | 默认值 | 描述                   |
| --------- | -------------------------------------------------- | ------ | ---------------------- |
| `options` | `ConfettiOptions & { canvas?: HTMLCanvasElement }` | `{}`   | 点击按钮时的彩带配置。 |

#credits

- 基于 [canvas-confetti](https://www.npmjs.com/package/canvas-confetti) 库构建。
- 移植自 [Magic UI Confetti](https://magicui.design/docs/components/confetti)。

::

---

### Cn 2.Components Special Effects Dither Shader (`content/cn/2.components/special-effects/dither-shader.md`)

---
title: 抖动着色器
description: 用于图像的实时有序抖动效果，非常适合像素艺术和复古风格。
category: Special Effects
tags: [tailwind, background, card, aceternity-ui]
---

::ComponentViewer{demoFile="DitherShaderDemo.vue" config="DitherShaderConfig" componentId="dither-shader" :componentFiles='["DitherShader.vue"]'}

#api

## API

| 属性              | 类型                                                 | 默认值                   | 描述                                          |
| ----------------- | ---------------------------------------------------- | ------------------------ | --------------------------------------------- |
| `src`             | `string`                                             | `-`                      | 源图像的 URL。                                |
| `gridSize`        | `number`                                             | `4`                      | 抖动网格单元的尺寸。                          |
| `ditherMode`      | `"bayer" \| "halftone" \| "noise" \| "crosshatch"`   | `"bayer"`                | 抖动的图案类型。                              |
| `colorMode`       | `"original" \| "grayscale" \| "duotone" \| "custom"` | `"original"`             | 颜色处理模式。                                |
| `invert`          | `boolean`                                            | `false`                  | 是否反转抖动后的输出颜色。                    |
| `pixelRatio`      | `number`                                             | `1`                      | 像素化倍数（1 表示无像素化，越大越像素化）。  |
| `primaryColor`    | `string`                                             | `"#000000"`              | 双色调模式下的主色。                          |
| `secondaryColor`  | `string`                                             | `"#ffffff"`              | 双色调模式下的次色。                          |
| `customPalette`   | `string[]`                                           | `["#000000", "#ffffff"]` | 自定义模式下的调色板数组。                    |
| `brightness`      | `number`                                             | `0`                      | 亮度调节（-1 至 1）。                         |
| `contrast`        | `number`                                             | `1`                      | 对比度调节（0 至 2，1 为正常）。              |
| `backgroundColor` | `string`                                             | `"transparent"`          | 抖动图像背后的背景色。                        |
| `objectFit`       | `"cover" \| "contain" \| "fill" \| "none"`           | `"cover"`                | 图像的填充方式。                              |
| `threshold`       | `number`                                             | `0.5`                    | 抖动阈值偏移（0 至 1）。                      |
| `animated`        | `boolean`                                            | `false`                  | 是否启用动画效果。                            |
| `animationSpeed`  | `number`                                             | `0.02`                   | 动画速度（数值越小越慢）。                    |
| `class`           | `string`                                             | `-`                      | 容器的额外 CSS 类（可用 Tailwind 设置尺寸）。 |

#credits

- 灵感并移植自 [Aceternity UI Dither Shader](https://ui.aceternity.com/components/dither-shader)。

::

---

### Cn 2.Components Special Effects Glow Border (`content/cn/2.components/special-effects/glow-border.md`)

---
title: 发光边框
description: 动态的发光边框效果。
category: Special Effects
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="GlowBorderDemo.vue" config="GlowBorderConfig" componentId="glow-border" :componentFiles='["GlowBorder.vue"]'}

#api

## API

| 属性名         | 类型                 | 默认值 | 描述                             |
| -------------- | -------------------- | ------ | -------------------------------- |
| `duration`     | `number`             | `10`   | 发光边框动画的持续时间。         |
| `color`        | `string \| string[]` | `#FFF` | 应用于发光边框的颜色或颜色数组。 |
| `borderRadius` | `number`             | `10`   | 边框的圆角半径。                 |
| `borderWidth`  | `number`             | `2`    | 边框宽度。                       |

#instructions

在 `main.css` 的 inline theme 中添加以下内容：

```css
@theme inline {
  --animate-glow: glow var(--duration) infinite linear;
  @keyframes glow {
    0% {
      background-position: 0% 0%;
    }
    50% {
      background-position: 100% 100%;
    }
    to {
      background-position: 0% 0%;
    }
  }
}
```

#credits

- 感谢 [Magic UI](https://magicui.design/docs/components/shine-border) 提供这个出色的组件。

::

---

### Cn 2.Components Special Effects Glowing Effect (`content/cn/2.components/special-effects/glowing-effect.md`)

---
title: 发光效果
description: 基于距离的动态发光效果，对鼠标移动与滚动作出响应，适合突出可交互元素。
category: Special Effects
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="GlowingEffectDemo.vue" config="GlowingEffectConfig" componentId="glowing-effect" :componentFiles='["GlowingEffect.vue"]'}

#api

## API

| 属性名             | 类型                   | 默认值      | 描述                                           |
| ------------------ | ---------------------- | ----------- | ---------------------------------------------- |
| `blur`             | `number`               | `0`         | 应用于发光层的模糊半径。                       |
| `inactiveZone`     | `number`               | `0.7`       | 定义发光静止的内半径，占元素短边的比例。       |
| `proximity`        | `number`               | `0`         | 额外的距离（像素），当光标接近元素时触发发光。 |
| `spread`           | `number`               | `20`        | 发光效果围绕元素扩散的大小。                   |
| `variant`          | `"default" \| "white"` | `"default"` | 发光样式的变体（如白色主题版本）。             |
| `glow`             | `boolean`              | `false`     | 控制静态发光边框的显示。                       |
| `class`            | `string`               | `""`        | 用于自定义样式的额外 CSS 类。                  |
| `disabled`         | `boolean`              | `true`      | 设为 `true` 时，禁用距离检测与发光动画。       |
| `movementDuration` | `number`               | `2`         | 平滑旋转动画的持续时间（秒）。                 |
| `borderWidth`      | `number`               | `1`         | 应用于发光效果的边框宽度（像素）。             |

#credits

- 移植自 [Aceternity UI Glowing Effect](https://ui.aceternity.com/components/glowing-effect)

::

---

### Cn 2.Components Special Effects Images Badge (`content/cn/2.components/special-effects/images-badge.md`)

---
title: 图片徽章
description: 一个带有图片的徽章，悬停时可展示更多图片。
category: Special Effects
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="ImagesBadgeDemo.vue" config="ImagesBadgeConfig" componentId="images-badge" :componentFiles='["ImagesBadge.vue"]'}

#api

## API

| 属性名            | 类型                                | 默认值                      | 描述                                                       |
| ----------------- | ----------------------------------- | --------------------------- | ---------------------------------------------------------- |
| `text`            | `string`                            | —                           | 显示在文件夹徽章旁边的文字标签。                           |
| `images`          | `string[]`                          | —                           | 要显示的图片 URL 数组（最多显示 3 张）。                   |
| `class`           | `string`                            | —                           | 根元素的附加 CSS 类。                                      |
| `href`            | `string`                            | —                           | 可选链接 URL；提供时渲染为 `<a>` 标签而非 `<div>`。        |
| `target`          | `string`                            | —                           | 链接的 target 属性（例如 `_blank` 表示在新标签页中打开）。 |
| `folderSize`      | `{ width: number; height: number }` | `{ width: 32, height: 24 }` | 文件夹图标尺寸（像素）。                                   |
| `teaserImageSize` | `{ width: number; height: number }` | `{ width: 20, height: 14 }` | 预览状态（空闲状态）下的图片尺寸（像素）。                 |
| `hoverImageSize`  | `{ width: number; height: number }` | `{ width: 48, height: 32 }` | 悬停时的图片尺寸（像素）。                                 |
| `hoverTranslateY` | `number`                            | `-35`                       | 悬停时图片向上移动的距离（像素）。                         |
| `hoverSpread`     | `number`                            | `20`                        | 悬停时图片之间的水平间距（像素）。                         |
| `hoverRotation`   | `number`                            | `15`                        | 悬停时图片的扇形旋转角度（度）。                           |

#credits

- 移植自 [Aceternity UI Images Badge](https://ui.aceternity.com/components/images-badge)

::

---

### Cn 2.Components Special Effects Meteors (`content/cn/2.components/special-effects/meteors.md`)

---
title: 流星雨
description: 展示流星雨动画的组件，可自定义流星数量与样式。
category: Special Effects
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="MeteorsDemo.vue" config="MeteorsConfig" componentId="meteors" :componentFiles='["Meteors.vue"]'}

#api

## API

| 属性名  | 类型     | 默认值 | 描述                                  |
| ------- | -------- | ------ | ------------------------------------- |
| `count` | `number` | `20`   | 动画中显示的流星数量。                |
| `class` | `string` | `""`   | 应用于流星的额外 CSS 类，便于自定义。 |

#instructions

在 `main.css` 的 inline theme 中添加以下内容：

```css
@theme inline {
  --animate-meteor-effect: meteor 5s linear infinite;
  @keyframes meteor {
    0% {
      transform: rotate(215deg) translateX(0);
      opacity: 1;
    }
    70% {
      opacity: 1;
    }
    100% {
      transform: rotate(215deg) translateX(-500px);
      opacity: 0;
    }
  }
}
```

#credits

- 移植自 [Aceternity UI 的 Meteor Effect](https://ui.aceternity.com/components/meteors)

::

---

### Cn 2.Components Special Effects Neon Border (`content/cn/2.components/special-effects/neon-border.md`)

---
title: 霓虹边框
description: 视觉吸引力强的霓虹边框组件，可自定义动画与颜色。
category: Special Effects
tags: [css, tailwind, border]
---

::ComponentViewer{demoFile="NeonBorderDemo.vue" config="NeonBorderConfig" componentId="neon-border" :componentFiles='["NeonBorder.vue"]'}

#api

## API

| 属性名          | 类型                         | 默认值      | 描述                    |
| --------------- | ---------------------------- | ----------- | ----------------------- |
| `color1`        | `string`                     | `"#0496ff"` | 霓虹边框的主色。        |
| `color2`        | `string`                     | `"#ff0a54"` | 霓虹边框的辅色。        |
| `animationType` | `"none" \| "half" \| "full"` | `"half"`    | 应用于边框的动画类型。  |
| `duration`      | `number`                     | `6`         | 动画持续时间（秒）。    |
| `class`         | `string`                     | `""`        | 用于样式的额外 CSS 类。 |

#instructions

在 `main.css` 的 inline theme 中添加以下内容：

```css
@theme inline {
  --animate-neon-border: neon-border var(--neon-border-duration) linear infinite;
  @keyframes neon-border {
    0% {
      transform: rotate(0deg);
    }
    100% {
      transform: rotate(360deg);
    }
  }
}
```

#credits

- 灵感来自现代霓虹边框效果。

::

---

### Cn 2.Components Special Effects Particle Image (`content/cn/2.components/special-effects/particle-image.md`)

---
title: 粒子图像
description: 将粒子动画应用到图像上的炫酷效果，类似 NuxtLabs.com 上的展示。
category: Special Effects
tags: [css, tailwind, canvas, particles]
---

::ComponentViewer{demoFile="ParticleImageDemo.vue" config="ParticleImageConfig" componentId="particle-image" :componentFiles='["ParticleImage.vue", "inspiraImageParticles.js", "inspiraImageParticles.d.ts"]'}

#api

## API

| 属性名            | 类型                                                                          | 默认值   | 描述                                       |
| ----------------- | ----------------------------------------------------------------------------- | -------- | ------------------------------------------ |
| `imageSrc`        | `string`                                                                      | `null`   | 应用粒子效果的图像源 URL。                 |
| `class`           | `string`                                                                      | `null`   | 应用于图像元素的额外 CSS 类。              |
| `canvasWidth`     | `string`                                                                      | `null`   | 粒子效果画布的宽度。                       |
| `canvasHeight`    | `string`                                                                      | `null`   | 粒子效果画布的高度。                       |
| `gravity`         | `string`                                                                      | `null`   | 影响粒子运动的重力。                       |
| `particleSize`    | `string`                                                                      | `null`   | 粒子的大小。                               |
| `particleGap`     | `string`                                                                      | `null`   | 粒子之间的间距。                           |
| `mouseForce`      | `string`                                                                      | `null`   | 鼠标移动对粒子施加的力。                   |
| `renderer`        | `"default" \| "webgl"`                                                        | `null`   | 粒子生成所用的渲染器，可选默认或 WebGL。   |
| `color`           | `string`                                                                      | `#FFF`   | 粒子的十六进制颜色，支持 3 位或 6 位代码。 |
| `colorArr`        | `number[]`                                                                    | `null`   | 用于定义多色粒子的数字数组。               |
| `initPosition`    | `"random" \| "top" \| "left" \| "bottom" \| "right" \| "misplaced" \| "none"` | `random` | 动画开始时粒子的初始位置。                 |
| `initDirection`   | `"random" \| "top" \| "left" \| "bottom" \| "right" \| "none"`                | `random` | 动画开始时粒子的初始方向。                 |
| `fadePosition`    | `"explode" \| "top" \| "left" \| "bottom" \| "right" \| "random" \| "none"`   | `none`   | 粒子淡出的位置。                           |
| `fadeDirection`   | `"random" \| "top" \| "left" \| "bottom" \| "right" \| "none"`                | `none`   | 粒子淡出的方向。                           |
| `noise`           | `number`                                                                      | `null`   | 粒子的噪声值。                             |
| `responsiveWidth` | `boolean`                                                                     | `false`  | 画布是否自适应宽度。                       |

#credits

- 感谢 [Nuxt Labs](https://nuxtlabs.com) 提供灵感。
- 感谢 [NextParticles](https://nextparticle.nextco.de) 提供动画库基础。

::

---

### Cn 2.Components Special Effects Progressive Blur (`content/cn/2.components/special-effects/progressive-blur.md`)

---
title: 渐进模糊
description: 一种分层的背景模糊效果，会在指定方向上逐渐增强强度，适合营造景深、聚焦与视觉分隔。
category: Special Effects
tags: [css, tailwind, motion-v, blur, backdrop-filter]
---

::ComponentViewer{demoFile="ProgressiveBlurDemo.vue" config="ProgressiveBlurConfig" componentId="progressive-blur" :componentFiles='["ProgressiveBlur.vue"]'}

#api

## API

| 属性名          | 类型                                     | 默认值     | 描述                         |
| --------------- | ---------------------------------------- | ---------- | ---------------------------- |
| `direction`     | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | 模糊逐渐增强的方向。         |
| `blurLayers`    | `number`                                 | `8`        | 用于创建渐进效果的模糊层数。 |
| `blurIntensity` | `number`                                 | `0.25`     | 每层的模糊强度系数（像素）。 |
| `class`         | `string`                                 | `""`       | 应用于外层容器的可选类名。   |

> 该组件也支持 `div` 的所有有效 `motion-v` 属性。

#credits

- 移植自 [Motion Primitives Progressive Blur](https://motion-primitives.com/docs/progressive-blur)。
- 由 `motion-v` 驱动。

::

---

### Cn 2.Components Special Effects Scales (`content/cn/2.components/special-effects/scales.md`)

---
title: 鳞片纹理
description: 一种重复的对角线、水平线或垂直线图案背景效果。
category: Special Effects
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="ScalesDemo.vue" config="ScalesConfig" componentId="scales" :componentFiles='["Scales.vue"]'}

#api

## API

| 属性名           | 类型                                       | 默认值       | 描述                          |
| ---------------- | ------------------------------------------ | ------------ | ----------------------------- |
| `orientation`    | `"horizontal" \| "vertical" \| "diagonal"` | `"diagonal"` | 重复线条图案的方向。          |
| `size`           | `number`                                   | `10`         | 每个重复贴片的尺寸（像素）。  |
| `color`          | `string`                                   | —            | 图案线条的 CSS 颜色值。       |
| `class`          | `string`                                   | —            | 内部图案遮罩层的附加 CSS 类。 |
| `containerClass` | `string`                                   | —            | 外部容器元素的附加 CSS 类。   |

#credits

- 移植自 [Aceternity UI Scales](https://ui.aceternity.com/components/scales).

::

---

### Cn 2.Components Special Effects Scratch To Reveal (`content/cn/2.components/special-effects/scratch-to-reveal.md`)

---
title: 刮刮乐揭示
description: 互动式刮刮乐效果，可自定义尺寸与动画，在刮开后显示隐藏内容。
category: Special Effects
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="ScratchToRevealDemo.vue" config="ScratchToRevealConfig" componentId="scratch-to-reveal" :componentFiles='["ScratchToReveal.vue"]'}

#api

## API

| 属性名                 | 类型                     | 默认值 | 描述                                      |
| ---------------------- | ------------------------ | ------ | ----------------------------------------- |
| `class`                | `string`                 | `""`   | 应用于组件的类名。                        |
| `width`                | `number`                 | `""`   | 刮刮区域的宽度。                          |
| `height`               | `number`                 | `""`   | 刮刮区域的高度。                          |
| `minScratchPercentage` | `number`                 | `50`   | 视为完成的最小刮开比例（0 到 100 之间）。 |
| `gradientColors`       | `[string,string,string]` | `-`    | 刮刮效果的渐变颜色。                      |

| 事件名     | 负载 | 描述                       |
| ---------- | ---- | -------------------------- |
| `complete` | `-`  | 刮开完成时调用的回调函数。 |

| 插槽名    | 默认内容 | 描述                     |
| --------- | -------- | ------------------------ |
| `default` | `-`      | 刮开后显示的文字或内容。 |

#credits

- 感谢 [Whbbit1999](https://github.com/Whbbit1999) 提供该组件。
- 灵感来自 [MagicUI Scratch To Reveal](https://magicui.design/docs/components/scratch-to-reveal)。

::

---

### Cn 2.Components Special Effects Spring Calendar (`content/cn/2.components/special-effects/spring-calendar.md`)

---
title: 弹性日历
description: 带弹簧动画的日历组件，可展开查看事件，使用 Motion-V 实现平滑过渡。
category: Special Effects
tags: [css, tailwind, motion-v]
---

::ComponentViewer{demoFile="SpringCalendarDemo.vue" config="SpringCalendarConfig" componentId="spring-calendar" :componentFiles='["SpringCalendar.vue", "TextMorph.vue"]'}

#api

## API

| 属性名         | 类型                                                                                                           | 默认值 | 描述                                 |
| -------------- | -------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------ |
| `calendarData` | `Array<{ month: string; date: number; day: string; events?: { title: string; day: string; time: string }[] }>` | **—**  | 定义每一天及可选事件的数组。_必填。_ |
| `initialIndex` | `number`                                                                                                       | `0`    | 初始选中的日期索引。                 |

### Emits

| 事件名               | 负载     | 描述                                     |
| -------------------- | -------- | ---------------------------------------- |
| `update:activeIndex` | `number` | 当点击日期按钮时触发，返回新的激活索引。 |

#credits

- 灵感来自 [sekachov](https://x.com/sekachov) 的作品。

::

---

### Cn 2.Components Testimonials Animated Testimonials (`content/cn/2.components/testimonials/animated-testimonials.md`)

---
title: 动态评价
description: 展示用户反馈的动态组件，包含过渡与自动播放功能。
category: Miscellaneous
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="AnimatedTestimonialsDemo.vue" config="AnimatedTestimonialsConfig" componentId="animated-testimonials" :componentFiles='["AnimatedTestimonials.vue"]'}

#api

## API

| 属性名         | 类型            | 默认值  | 描述                                       |
| -------------- | --------------- | ------- | ------------------------------------------ |
| `testimonials` | `Testimonial[]` | `[]`    | 评价对象数组，包含引用、姓名、头像与职称。 |
| `autoplay`     | `boolean`       | `false` | 是否自动轮播评价。                         |
| `duration`     | `number`        | `5000`  | 自动切换到下一条评价前等待的时间（毫秒）。 |

### Testimonial 对象

每个评价对象需包含以下字段：

| 属性          | 类型     | 描述                                |
| ------------- | -------- | ----------------------------------- |
| `quote`       | `string` | 评价文本。                          |
| `name`        | `string` | 提供评价的人员姓名或实体。          |
| `designation` | `string` | 评价者的职位/角色（如 CEO、用户）。 |
| `image`       | `string` | 评价者头像或图片的 URL。            |

#credits

- 移植自 [Aceternity UI Animated Testimonials](https://ui.aceternity.com/components/animated-testimonials)。

::

---

### Cn 2.Components Testimonials Design Testimonials (`content/cn/2.components/testimonials/design-testimonials.md`)

---
title: 设计感评价
description: 一个高级、设计优先的评价版块，包含电影感排版、磁性视差、逐词动画与自动轮播导航。
category: Testimonials
tags: [css, tailwind, motion-v, testimonial, animation]
---

::ComponentViewer{demoFile="DesignTestimonialsDemo.vue" config="DesignTestimonialsConfig" componentId="design-testimonials" :componentFiles='["DesignTestimonials.vue"]'}

#api

## API

| 属性名         | 类型                | 默认值           | 描述                                   |
| -------------- | ------------------- | ---------------- | -------------------------------------- |
| `title`        | `string`            | `"Testimonials"` | 布局左侧显示的垂直标签。               |
| `duration`     | `number`            | `6000`           | 自动切换到下一条评价前的时间（毫秒）。 |
| `testimonials` | `TestimonialItem[]` | **必填**         | 要渲染并动画化的评价列表。             |

### `TestimonialItem` 对象

每条评价需包含以下字段：

| 属性      | 类型     | 描述                                   |
| --------- | -------- | -------------------------------------- |
| `quote`   | `string` | 评价文本，逐词动画显示。               |
| `author`  | `string` | 评价作者姓名。                         |
| `role`    | `string` | 作者的角色或职务。                     |
| `company` | `string` | 公司或组织名称（用于徽章和滚动字幕）。 |

#credits

- 动画由 `motion-v` 提供支持
- 移植自 [Jatin Yadav 的 Design Testimonials](https://21st.dev/community/components/jatin-yadav05/design-testimonial/default)

::

---

### Cn 2.Components Testimonials Testimonial Slider (`content/cn/2.components/testimonials/testimonial-slider.md`)

---
title: 评价滑块
description: 轻量的评价滑块，包含图片旋转、文字过渡与可选自动轮播。
category: Miscellaneous
tags: [css, tailwind]
---

::ComponentViewer{demoFile="TestimonialSliderDemo.vue" config="TestimonialSliderConfig" componentId="testimonial-slider" :componentFiles='["TestimonialSlider.vue"]'}

#api

## API

| 属性名         | 类型                                                                | 默认值 | 描述                                          |
| -------------- | ------------------------------------------------------------------- | ------ | --------------------------------------------- |
| `testimonials` | `Array<{ img: string; quote: string; name: string; role: string }>` | `[]`   | 滑块中显示的评价对象数组。                    |
| `autoRotate`   | `boolean`                                                           | `true` | 若为 `true`，滑块每隔 `duration` 秒自动切换。 |
| `duration`     | `number`                                                            | `5`    | 启用自动轮播时的切换间隔（秒）。              |

::

---

### Cn 2.Components Text Animations 3d Text (`content/cn/2.components/text-animations/3d-text.md`)

---
title: 3D 文字
description: 时尚的 3D 文字组件，可自定义颜色、阴影与动画选项。
category: Text Animation
tags: [css, tailwind, 3d]
---

::ComponentViewer{demoFile="Text3dDemo.vue" config="Text3dConfig" componentId="text-3d" :componentFiles='["Text3d.vue"]'}

#api

## API

| 属性名              | 类型      | 默认值     | 描述                          |
| ------------------- | --------- | ---------- | ----------------------------- |
| `textColor`         | `string`  | `"white"`  | 主文字颜色。                  |
| `letterSpacing`     | `number`  | `-0.1`     | 字符间距，单位为 `ch`。       |
| `strokeColor`       | `string`  | `"black"`  | 描边颜色。                    |
| `shadowColor`       | `string`  | `"yellow"` | 阴影颜色。                    |
| `strokeSize`        | `number`  | `20`       | 描边厚度（像素）。            |
| `shadow1Size`       | `number`  | `7`        | 第一层阴影尺寸（像素）。      |
| `shadow2Size`       | `number`  | `10`       | 第二层阴影尺寸（像素）。      |
| `class`             | `string`  | `""`       | 用于自定义样式的额外 CSS 类。 |
| `animate`           | `boolean` | `true`     | 为 `true` 时启用晃动动画。    |
| `animationDuration` | `number`  | `1500`     | 晃动动画时长（毫秒）。        |

::

---

### Cn 2.Components Text Animations Blur Reveal (`content/cn/2.components/text-animations/blur-reveal.md`)

---
title: 模糊揭示
description: 平滑模糊淡入内容的组件。
category: Text Animation
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="BlurRevealDemo.vue" config="BlurRevealConfig" componentId="blur-reveal" :componentFiles='["BlurReveal.vue"]'}

#api

## API

| 属性名     | 类型     | 默认值 | 描述                     |
| ---------- | -------- | ------ | ------------------------ |
| `duration` | `number` | `1`    | 模糊淡入动画的持续时间。 |
| `delay`    | `number` | `1`    | 子组件依次揭示的延迟。   |
| `blur`     | `string` | `10px` | 应用于子组件的模糊量。   |
| `yOffset`  | `number` | `20`   | 入场动画的垂直偏移距离。 |

#credits

- 感谢 [Magic UI](https://magicui.design/docs/components/blur-fade) 提供该组件。

::

---

### Cn 2.Components Text Animations Box Reveal (`content/cn/2.components/text-animations/box-reveal.md`)

---
title: 盒子揭示
description: 可自定义颜色、时长与延迟的盒子揭示动画。
category: Text Animation
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="BoxRevealDemo.vue" config="BoxRevealConfig" componentId="box-reveal" :componentFiles='["BoxReveal.vue"]'}

#api

## API

| 属性名     | 类型     | 默认值      | 描述                          |
| ---------- | -------- | ----------- | ----------------------------- |
| `color`    | `string` | `"#5046e6"` | 揭示盒子的背景色。            |
| `duration` | `number` | `0.5`       | 揭示动画的持续时间（秒）。    |
| `delay`    | `number` | `0.25`      | 动画开始前的延迟（秒）。      |
| `class`    | `string` | `""`        | 用于自定义样式的额外 CSS 类。 |

#credits

- 移植自 [Magic UI Box Reveal](https://magicui.design/docs/components/box-reveal)。

::

---

### Cn 2.Components Text Animations Breathing Text (`content/cn/2.components/text-animations/breathing-text.md`)

---
title: 呼吸文字
description: 通过错开的节奏持续动画化可变字体轴，呈现呼吸般的文字效果。
category: 文字动画
tags: [css, tailwind, motion-v, variable-font]
badge: New
dependencies: motion-v
---

::ComponentViewer{demoFile="BreathingTextDemo.vue" config="BreathingTextConfig" componentId="breathing-text" :componentFiles='["BreathingText.vue", "index.ts"]'}

#api

## API

| 属性                        | 类型                                      | 默认值                                 | 描述                                 |
| --------------------------- | ----------------------------------------- | -------------------------------------- | ------------------------------------ |
| `text`                      | `string`                                  | 插槽内容                               | 要拆分并独立动画的文字。             |
| `as`                        | `string`                                  | `"span"`                               | 根文本节点使用的 HTML 元素。         |
| `fromFontVariationSettings` | `string`                                  | —                                      | 每个动画周期开始时使用的字体轴设置。 |
| `toFontVariationSettings`   | `string`                                  | —                                      | 每个动画周期结束时使用的字体轴设置。 |
| `transition`                | `Transition`                              | `{ duration: 1.5, ease: "easeInOut" }` | 每个字母使用的 Motion transition。   |
| `staggerDuration`           | `number`                                  | `0.1`                                  | 每个字母之间的动画延迟。             |
| `staggerFrom`               | `"first" \| "last" \| "center" \| number` | `"first"`                              | 计算错开顺序的起点。                 |
| `repeatDelay`               | `number`                                  | `0.1`                                  | 每次呼吸动画周期之间的延迟。         |
| `class`                     | `string`                                  | —                                      | 合并到根元素的额外 class。           |

请使用可变字体，并传入它支持的字体轴。例如，Roboto Flex 支持 `wght` 和 `wdth`。

#credits

- 移植自 [Fancy Components Breathing Text](https://fancycomponents.dev/docs/components/text/breathing-text)。

::

---

### Cn 2.Components Text Animations Colorful Text (`content/cn/2.components/text-animations/colorful-text.md`)

---
title: 彩色文字
description: 多彩文字组件，带滤镜与缩放效果。
category: Text Animation
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="ColourfulTextDemo.vue" config="ColourfulTextConfig" componentId="colourful-text" :componentFiles='["ColourfulText.vue"]'}

#api

## API

| 属性名       | 类型       | 默认值                                                                                                                                                                                                             | 描述                                               |
| ------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
| `text`       | `string`   | `"black"`                                                                                                                                                                                                          | 要渲染的文字，每个字符都会单独进行颜色和动效动画。 |
| `colors`     | `string[]` | `[ "rgb(131, 179, 32)", "rgb(47, 195, 106)", "rgb(42, 169, 210)", "rgb(4, 112, 202)", "rgb(107, 10, 255)", "rgb(183, 0, 218)", "rgb(218, 0, 171)", "rgb(230, 64, 92)", "rgb(232, 98, 63)", "rgb(249, 129, 47)", ]` | 文字使用的颜色列表。                               |
| `startColor` | `string`   | `"rgb(255,255,255)"`                                                                                                                                                                                               | 字符的初始颜色。                                   |
| `duration`   | `number`   | `5`                                                                                                                                                                                                                | 动画持续时间（秒）。                               |

#credits

- 感谢 [Whbbit1999](https://github.com/Whbbit1999) 提供该组件。
- 移植自 [Aceternity UI Colourful Text](https://ui.aceternity.com/components/colourful-text)

::

---

### Cn 2.Components Text Animations Container Text Flip (`content/cn/2.components/text-animations/container-text-flip.md`)

---
title: 容器文字翻转
description: 一个循环翻转单词的容器，并随文字宽度动画。
category: Text Animation
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="ContainerTextFlipDemo.vue" config="ContainerTextFlipConfig" componentId="container-text-flip" :componentFiles='["ContainerTextFlip.vue"]'}

#api

## API

| 属性名              | 类型       | 默认值                                         | 描述                      |
| ------------------- | ---------- | ---------------------------------------------- | ------------------------- |
| `words`             | `string[]` | `["better", "modern", "beautiful", "awesome"]` | 循环显示的单词数组。      |
| `interval`          | `number`   | `3000`                                         | 单词切换间隔（毫秒）。    |
| `animationDuration` | `number`   | `700`                                          | 过渡动画时长（毫秒）。    |
| `class`             | `string`   | ``                                             | 应用于容器的额外 CSS 类。 |
| `textClass`         | `string`   | ``                                             | 应用于文字的额外 CSS 类。 |

#credits

- 感谢 [Whbbit1999](https://github.com/Whbbit1999) 提供该组件。
- 移植自 [Aceternity UI Container Text Flip](https://ui.aceternity.com/components/container-text-flip)。

::

---

### Cn 2.Components Text Animations Encrypted Text (`content/cn/2.components/text-animations/encrypted-text.md`)

---
title: 加密文字
description: 当进入视口时由乱码字符开始并逐步解密为最终内容的文字揭示效果。
category: Text Animation
tags: [css, tailwind, motion-v, typography, animation, text]
---

::ComponentViewer{demoFile="EncryptedTextDemo.vue" config="EncryptedTextConfig" componentId="encrypted-text" :componentFiles='["EncryptedText.vue"]'}

#api

## API

| 属性名           | 类型     | 默认值                                   | 描述                               |
| ---------------- | -------- | ---------------------------------------- | ---------------------------------- |
| `text`           | `string` | **required**                             | 要渲染并揭示的文字内容。           |
| `class`          | `string` | `""`                                     | 应用于外层容器的基础类名。         |
| `revealDelayMs`  | `number` | `50`                                     | 每个字符依次揭示的延迟（毫秒）。   |
| `flipDelayMs`    | `number` | `50`                                     | 未揭示字符重新打乱的延迟（毫秒）。 |
| `charset`        | `string` | `A–Z a–z 0–9 !@#$%^&*()_+-={}[];:,.<>/?` | 用于乱码字符的字符集。             |
| `encryptedClass` | `string` | `""`                                     | 仍处于加密/打乱状态时的字符类名。  |
| `revealedClass`  | `string` | `""`                                     | 字符揭示后应用的类名。             |

#credits

- 移植自 [Aceternity UI Encrypted Text](https://ui.aceternity.com/components/encrypted-text)。
- 动画由 `motion-v` 驱动。

::

---

### Cn 2.Components Text Animations Flip Words (`content/cn/2.components/text-animations/flip-words.md`)

---
title: 翻转单词
description: 循环翻转单词列表的组件。
category: Text Animation
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="FlipWordsDemo.vue" config="FlipWordsConfig" componentId="flip-words" :componentFiles='["FlipWords.vue"]'}

#api

## API

| 属性名     | 类型     | 描述                                               |
| ---------- | -------- | -------------------------------------------------- |
| `words`    | `Array`  | 要展示并动画的单词数组。                           |
| `duration` | `number` | 每个单词显示的时间（毫秒），之后翻转到下一个单词。 |
| `class`    | `string` | 应用于组件的额外 CSS 类。                          |

#credits

- 感谢 [M Atif](https://github.com/atif0075) 移植该组件。
- 移植自 [Aceternity UI's Flip Words](https://ui.aceternity.com/components/flip-words)

::

---

### Cn 2.Components Text Animations Focus (`content/cn/2.components/text-animations/focus.md`)

---
title: 聚焦
description: 通过动态模糊和动画框高亮句子中的单词，支持自动循环或悬停手动聚焦模式。
category: Text Animation
tags: [css, tailwind, codepen]
---

::ComponentViewer{demoFile="FocusDemo.vue" config="FocusConfig" componentId="focus" :componentFiles='["Focus.vue"]'}

#api

## API

| 属性名                   | 类型      | 默认值            | 描述                                      |
| ------------------------ | --------- | ----------------- | ----------------------------------------- |
| `sentence`               | `string`  | `"Inspira Focus"` | 要逐词展示和动画的句子。                  |
| `manualMode`             | `boolean` | `false`           | 若为 `true`，悬停时才高亮；否则自动循环。 |
| `blurAmount`             | `number`  | `5`               | 非聚焦单词的模糊半径（像素）。            |
| `borderColor`            | `string`  | `"green"`         | 动画聚焦边框的颜色。                      |
| `animationDuration`      | `number`  | `0.5`             | 聚焦框动画过渡的持续时间（秒）。          |
| `pauseBetweenAnimations` | `number`  | `1`               | 自动聚焦之间的暂停时长（秒）。            |

#credits

- 灵感来自 [CodePen 的 Focus Text Hover Effect](https://codepen.io/CameronFitzwilliam/pen/JJRjMa)。

::

---

### Cn 2.Components Text Animations Highlight Text (`content/cn/2.components/text-animations/highlight-text.md`)

---
title: 高亮文本
description: 使用带方向的背景扫过动画高亮文本。
category: 文本动画
tags: [css, tailwind, motion-v]
badge: New
---

::ComponentViewer{demoFile="HighlightTextDemo.vue" config="HighlightTextConfig" componentId="highlight-text" :componentFiles='["HighlightText.vue", "index.ts"]'}

#api

## API

| 属性               | 类型                                   | 默认值                                        | 说明                             |
| ------------------ | -------------------------------------- | --------------------------------------------- | -------------------------------- |
| `as`               | `string`                               | `span`                                        | 外层包装元素。                   |
| `triggerType`      | `hover` \| `ref` \| `inView` \| `auto` | `inView`                                      | 启动高亮的触发方式。             |
| `transition`       | `Record<string, unknown>`              | 弹簧过渡                                      | 高亮扫过动画使用的 Motion 过渡。 |
| `useInViewOptions` | `Record<string, unknown>`              | `{ once: true, initial: false, amount: 0.1 }` | 进入视口触发器的选项。           |
| `class`            | `string`                               | `-`                                           | 合并到高亮文本上的类名。         |
| `highlightColor`   | `string`                               | `hsl(25 90% 80%)`                             | 高亮颜色。                       |
| `direction`        | `ltr` \| `rtl` \| `ttb` \| `btt`       | `ltr`                                         | 背景扫过方向。                   |

当使用 `ref` 触发方式时，组件暴露 `animate(direction?)` 和 `reset()` 方法。

#credits

- 灵感来自 [Fancy Components](https://fancycomponents.dev/docs/components/text/text-highlighter)。

::

---

### Cn 2.Components Text Animations Hyper Text (`content/cn/2.components/text-animations/hyper-text.md`)

---
title: 超能文字
description: 悬停时快速变化的文字动画。
category: Text Animation
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="HyperTextDemo.vue" config="HyperTextConfig" componentId="hyper-text" :componentFiles='["HyperText.vue"]'}

#api

## API

| 属性名          | 类型      | 默认值   | 描述                       |
| --------------- | --------- | -------- | -------------------------- |
| `class`         | `string`  | `""`     | 应用于组件的额外 CSS 类。  |
| `text`          | `string`  | Required | 要做动画的文字。           |
| `duration`      | `number`  | `0.8`    | 整个动画的持续时间（秒）。 |
| `animateOnLoad` | `boolean` | `true`   | 是否在加载时自动播放动画。 |

#credits

- 灵感来自 [Magic UI 的 Hyper Text](https://magicui.design/docs/components/hyper-text) 组件。
- 感谢 [Prem](https://github.com/premdasvm) 移植该组件。

::

---

### Cn 2.Components Text Animations Letter Pullup (`content/cn/2.components/text-animations/letter-pullup.md`)

---
title: 字符上提
description: 逐字上提的错落文字动画。
category: Text Animation
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="LetterPullupDemo.vue" config="LetterPullupConfig" componentId="letter-pullup" :componentFiles='["LetterPullup.vue"]'}

#api

## API

| 属性名  | 类型     | 默认值                     | 描述                       |
| ------- | -------- | -------------------------- | -------------------------- |
| `class` | `string` | `-`                        | 应用于组件的类名。         |
| `words` | `string` | `Staggered Letter Pull Up` | 要做动画的文字。           |
| `delay` | `number` | `0.05`                     | 每个字符动画的延迟（秒）。 |

#credits

- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi) 提供该组件。
- 灵感来自 [Magic UI](https://magicui.design/docs/components/letter-pullup)。

::

---

### Cn 2.Components Text Animations Letter Swap (`content/cn/2.components/text-animations/letter-swap.md`)

---
title: 字母切换
description: 使用正向、往返和随机动画模式，在悬停时垂直切换字母。
category: 文字动画
tags: [css, tailwind, motion-v]
badge: New
---

::ComponentViewer{demoFile="LetterSwapDemo.vue" config="LetterSwapConfig" componentId="letter-swap" :componentFiles='["LetterSwap.vue", "index.ts"]' dependencies="motion-v"}

#api

## API

| 属性              | 类型                                      | 默认值                              | 描述                               |
| ----------------- | ----------------------------------------- | ----------------------------------- | ---------------------------------- |
| `label`           | `string`                                  | —                                   | 要显示并进行动画的文本。           |
| `animation`       | `"forward" \| "pingpong"`                 | `"forward"`                         | 正向播放，或在指针离开时反向播放。 |
| `random`          | `boolean`                                 | `false`                             | 以随机顺序为字母设置动画。         |
| `reverse`         | `boolean`                                 | `true`                              | 设置切换的垂直方向。               |
| `transition`      | `Transition`                              | `{ type: "spring", duration: 0.7 }` | 每个字母使用的 Motion 过渡。       |
| `staggerDuration` | `number`                                  | `0.03`                              | 每个字母动画开始之间的延迟。       |
| `staggerFrom`     | `"first" \| "last" \| "center" \| number` | `"first"`                           | 计算交错顺序的起点。               |
| `class`           | `string`                                  | `-`                                 | 合并到根元素的其他 class。         |

#credits

- 灵感来自 [Fancy Components](https://fancycomponents.dev/docs/components/text/letter-swap.md)。
- 原始作品来自 [Daniel Petho](https://github.com/danielpetho/fancy)。

::

---

### Cn 2.Components Text Animations Line Shadow Text (`content/cn/2.components/text-animations/line-shadow-text.md`)

---
title: 线条阴影文字
description: 为文字添加线条阴影效果，使其更具视觉吸引力。
category: Text Animation
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="LineShadowTextDemo.vue" config="LineShadowTextConfig" componentId="line-shadow-text" :componentFiles='["LineShadowText.vue"]'}

#api

## API

| 属性名        | 类型     | 默认值    | 描述                          |
| ------------- | -------- | --------- | ----------------------------- |
| `shadowColor` | `string` | `"black"` | 阴影效果的颜色。              |
| `class`       | `string` | `""`      | 用于自定义样式的额外 CSS 类。 |
| `as`          | `string` | `"span"`  | 渲染文字所用的 HTML 元素。    |

#credits

- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi) 提供该组件。
- 移植自 [Magic UI 的 Line Shadow Text](https://magicui.design/docs/components/line-shadow-text)

::

---

### Cn 2.Components Text Animations Morphing Text (`content/cn/2.components/text-animations/morphing-text.md`)

---
title: 文字变形
description: 动态在一组文本之间切换，呈现平滑的渐变效果。
category: Text Animation
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="MorphingTextDemo.vue" config="MorphingTextConfig" componentId="morphing-text" :componentFiles='["MorphingText.vue"]'}

#api

## API

| 属性名         | 类型       | 默认值 | 描述                 |
| -------------- | ---------- | ------ | -------------------- |
| `texts`        | `string[]` | `[]`   | 需要变换的文本数组。 |
| `class`        | `string`   | `""`   | 容器的额外类名。     |
| `morphTime`    | `number`   | `1.5`  | 动画执行时间。       |
| `coolDownTime` | `number`   | `0.5`  | 动画停留时间。       |

#credits

- 感谢 [Whbbit1999](https://github.com/Whbbit1999) 提供该组件。
- 灵感并移植自 [Magic UI Morphing Text](https://magicui.design/docs/components/morphing-text)。

::

---

### Cn 2.Components Text Animations Number Ticker (`content/cn/2.components/text-animations/number-ticker.md`)

---
title: 数字滚动
description: 动画数字向目标值递增或递减。
category: Text Animation
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="NumberTickerDemo.vue" config="NumberTickerConfig" componentId="number-ticker" :componentFiles='["NumberTicker.vue"]'}

#api

## API

| 属性名          | 类型                | 默认值         | 描述                                                    |
| --------------- | ------------------- | -------------- | ------------------------------------------------------- |
| `value`         | `int`               | `0`            | 需要滚动到的目标值。                                    |
| `direction`     | `up \| down`        | `up`           | 计数方向。                                              |
| `decimalPlaces` | `number`            | `0`            | 显示的小数位数。                                        |
| `delay`         | `number`            | `0`            | 开始计数前的延迟（毫秒）。                              |
| `duration`      | `number`            | `1000`         | 整个动画的持续时间（毫秒）。                            |
| `transition`    | `TransitionPresets` | `easeOutCubic` | 过渡预设名称（https://vueuse.org/core/useTransition）。 |

#credits

- 感谢 [Grzegorz Krol](https://github.com/Grzechu335) 移植该组件。
- 移植自 [Magic UI NumberTicker](https://magicui.design/docs/components/number-ticker)。

::

---

### Cn 2.Components Text Animations Radiant Text (`content/cn/2.components/text-animations/radiant-text.md`)

---
title: 光辉文字
description: 为文字添加耀眼的高光效果。
category: Text Animation
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="RadiantTextDemo.vue" config="RadiantTextConfig" componentId="radiant-text" :componentFiles='["RadiantText.vue"]'}

#api

## API

| 属性名         | 类型     | 默认值 | 描述                 |
| -------------- | -------- | ------ | -------------------- |
| `duration`     | `number` | `10`   | 动画持续时间（秒）。 |
| `radiantWidth` | `number` | `100`  | 高光动画的宽度。     |

#credits

- 感谢 [Magic UI](https://magicui.design/docs/components/animated-shiny-text) 提供该组件。

::

---

### Cn 2.Components Text Animations Screw Text (`content/cn/2.components/text-animations/screw-text.md`)

---
title: 螺旋文字
description: 悬停文字时，让每个字母沿 3D 面进行翻转切换。
category: 文字动画
tags: [css, tailwind, motion-v, 3d]
badge: New
dependencies: motion-v
---

::ComponentViewer{demoFile="ScrewTextDemo.vue" config="ScrewTextConfig" componentId="screw-text" :componentFiles='["ScrewText.vue", "index.ts"]'}

#api

## API

| 属性              | 类型                                      | 默认值    | 说明                         |
| ----------------- | ----------------------------------------- | --------- | ---------------------------- |
| `label`           | `string`                                  | —         | 要拆分并逐字母动画的文字。   |
| `as`              | `string`                                  | `"p"`     | 根文字节点使用的 HTML 元素。 |
| `rotateDirection` | `"top" \| "right" \| "bottom" \| "left"`  | `"right"` | 3D 切换使用的轴和方向。      |
| `staggerDuration` | `number`                                  | `0.05`    | 每个字母动画之间的延迟。     |
| `staggerFrom`     | `"first" \| "last" \| "center" \| number` | `"first"` | 计算交错顺序的起点。         |
| `transition`      | `Transition`                              | 弹簧过渡  | 每个字母使用的 Motion 过渡。 |
| `class`           | `string`                                  | —         | 根元素的额外类名。           |
| `frontFaceClass`  | `string`                                  | —         | 应用于正面字母的类名。       |
| `secondFaceClass` | `string`                                  | —         | 应用于第二面字母的类名。     |

#credits

- 移植自 [Fancy Components Letter 3D Swap](https://fancycomponents.dev/docs/components/text/letter-3d-swap)。
- 原作者：[Daniel Petho](https://github.com/danielpetho/fancy)。

::

---

### Cn 2.Components Text Animations Scroll Swap Text (`content/cn/2.components/text-animations/scroll-swap-text.md`)

---
title: 滚动切换文本
description: 当组件在滚动容器中移动时，让文本垂直切换。
category: 文本动画
tags: [css, tailwind, motion-v]
badge: New
---

::ComponentViewer{demoFile="ScrollSwapTextDemo.vue" config="ScrollSwapTextConfig" componentId="scroll-swap-text" :componentFiles='["ScrollSwapText.vue", "index.ts"]'}

#api

## API

| 属性           | 类型                      | 默认值                            | 说明                         |
| -------------- | ------------------------- | --------------------------------- | ---------------------------- |
| `as`           | `string`                  | `span`                            | 文本包装元素。               |
| `containerRef` | `MaybeComputedElementRef` | —                                 | 用于计算滚动进度的容器。     |
| `offset`       | `[string, string]`        | `["0 0", "0 1"]`                  | 定义动画范围的滚动偏移量。   |
| `class`        | `string`                  | `-`                               | 合并到包装元素上的额外类名。 |
| `springConfig` | `object`                  | `{ stiffness: 200, damping: 30 }` | 用于平滑滚动进度的弹簧设置。 |

组件会渲染两份插槽文本。滚动容器移动时，第一份文本离开，第二份文本进入。

#credits

- 灵感来自 [Fancy Components](https://fancycomponents.dev/docs/components/text/scroll-and-swap)。

::

---

### Cn 2.Components Text Animations Sparkles Text (`content/cn/2.components/text-animations/sparkles-text.md`)

---
title: 闪光文字
description: 为文字持续生成闪光与平滑过渡，非常适合突出显示的星光效果。
category: Text Animation
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="SparklesTextDemo.vue" config="SparklesTextConfig" componentId="sparkles-text" :componentFiles='["SparklesText.vue"]'}

#api

## API

| 属性名          | 类型     | 默认值                                   | 描述                   |
| --------------- | -------- | ---------------------------------------- | ---------------------- |
| `class`         | `string` | `-`                                      | 应用于闪光文字的类名。 |
| `text`          | `string` | ``                                       | 要显示的文字。         |
| `sparklesCount` | `number` | `10`                                     | 文字上出现的闪光数量。 |
| `colors`        | `object` | `{first: '#A07CFE'; second: '#FE8FB5';}` | 闪光的颜色配置。       |

#credits

- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi) 提供该组件。
- 灵感来自 [Magic UI](https://magicui.design/docs/components/sparkles-text)。
- 感谢 [M Atif](https://github.com/atif0075) 更新该组件。

::

---

### Cn 2.Components Text Animations Spinning Text (`content/cn/2.components/text-animations/spinning-text.md`)

---
title: 旋转文字
description: 让文字沿圆周运动的动画组件，可自定义速度、方向、颜色与过渡，打造动态效果。
category: Text Animation
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="SpinningTextDemo.vue" config="SpinningTextConfig" componentId="spinning-text" :componentFiles='["SpinningText.vue"]'}

#api

## API

| 属性名       | 类型                                                    | 默认值  | 描述                         |
| ------------ | ------------------------------------------------------- | ------- | ---------------------------- |
| `duration`   | `number`                                                | `10`    | 完成一圈旋转动画的持续时间。 |
| `reverse`    | `boolean`                                               | `false` | 是否反向旋转。               |
| `radius`     | `number`                                                | `5`     | 文字旋转路径的半径。         |
| `transition` | `motion-v Transition`                                   | ``      | 动画的自定义过渡效果。       |
| `variants`   | `{container: motion-v Variant, item: motion-v Variant}` | ``      | 容器与子项动画的变体。       |
| `class`      | `string`                                                | `""`    | 文字容器的自定义类名。       |

#credits

- 感谢 [Whbbit1999](https://github.com/Whbbit1999) 提供该组件。
- 移植自 [Magic UI Spinning Text](https://magicui.design/docs/components/spinning-text)。

::

---

### Cn 2.Components Text Animations Text Generate Effect (`content/cn/2.components/text-animations/text-generate-effect.md`)

---
title: 文字生成效果
description: 炫酷的文字效果，在页面加载时逐字渐显。
category: Text Animation
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="TextGenerateDemo.vue" config="TextGenerateConfig" componentId="text-generate-effect" :componentFiles='["TextGenerateEffect.vue"]'}

#api

## API

| 属性名     | 类型      | 默认值   | 描述                           |
| ---------- | --------- | -------- | ------------------------------ |
| `words`    | `string`  | Required | 要展示并生成的文字。           |
| `duration` | `number`  | `0.7`    | 文字生成动画的持续时间（秒）。 |
| `delay`    | `number`  | `0`      | 动画开始前的延迟（毫秒）。     |
| `filter`   | `boolean` | `true`   | 文字的模糊效果。               |

#credits

- 感谢 [M Atif](https://github.com/atif0075) 移植该组件。
- 移植自 [Aceternity UI's Text Generate Effect](https://ui.aceternity.com/components/text-generate-effect)。

::

---

### Cn 2.Components Text Animations Text Glitch (`content/cn/2.components/text-animations/text-glitch.md`)

---
title: 文字故障
description: 为文字添加鲜明的故障效果，可自定义速度、阴影颜色，并可选择仅在悬停时触发。
category: Text Animation
tags: [css, tailwind]
---

::ComponentViewer{demoFile="TextGlitchDemo.vue" config="TextGlitchConfig" componentId="text-glitch" :componentFiles='["TextGlitch.vue"]'}

#api

## API

| 属性名          | 类型      | 默认值      | 描述                                 |
| --------------- | --------- | ----------- | ------------------------------------ |
| `text`          | `string`  | `""`        | 展示故障效果的文字内容。             |
| `speed`         | `number`  | `0.5`       | 故障动画的速度（秒）。               |
| `enableShadows` | `boolean` | `true`      | 是否开启彩色阴影以增强故障感。       |
| `enableOnHover` | `boolean` | `false`     | 为 `true` 时仅在悬停时启用故障动画。 |
| `class`         | `string`  | `undefined` | 容器 div 的额外 CSS 类。             |

#credits

- 灵感与实现参考了以下 YouTube 视频：
  - https://www.youtube.com/watch?v=7Xyg8Ja7dyY
  - https://www.youtube.com/watch?v=9CCkp_El1So

::

---

### Cn 2.Components Text Animations Text Highlight (`content/cn/2.components/text-animations/text-highlight.md`)

---
title: 文字高亮
description: 为文字填充背景以突出显示的效果。
category: Text Animation
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="TextHighlightDemo.vue" config="TextHighlightConfig" componentId="text-highlight" :componentFiles='["TextHighlight.vue"]'}

#api

## API

| 属性名           | 类型     | 默认值    | 描述                                   |
| ---------------- | -------- | --------- | -------------------------------------- |
| `delay`          | `number` | `0`       | 动画开始前的延迟（毫秒）。             |
| `duration`       | `number` | `2000`    | 动画持续时间（毫秒）。                 |
| `text-end-color` | `string` | `inherit` | 动画结束时文字颜色，应符合 WCAG 推荐。 |

#credits

- 灵感来自 [Aceternity UI](https://ui.aceternity.com/components/hero-highlight)
- 感谢 [Nathan De Pachtere](https://nathandepachtere.com) 移植该组件。

::

---

### Cn 2.Components Text Animations Text Hover Effect (`content/cn/2.components/text-animations/text-hover-effect.md`)

---
title: 文字悬停效果
description: 在悬停时为文字添加渐变描边与动画，灵感来自 x.ai。
category: Text Animation
tags: [css, tailwind]
---

::ComponentViewer{demoFile="TextHoverEffectDemo.vue" config="TextHoverEffectConfig" componentId="text-hover-effect" :componentFiles='["TextHoverEffect.vue"]'}

#api

## API

| 属性名        | 类型     | 默认值   | 描述                           |
| ------------- | -------- | -------- | ------------------------------ |
| `text`        | `string` | Required | 应用悬停效果的文字。           |
| `duration`    | `number` | `200`    | 蒙版过渡动画的持续时间（秒）。 |
| `strokeWidth` | `number` | `0.75`   | 文字描边宽度。                 |
| `opacity`     | `number` | `null`   | 文字的不透明度。               |

::

---

### Cn 2.Components Text Animations Text Reveal Card (`content/cn/2.components/text-animations/text-reveal-card.md`)

---
title: 文字揭示卡片
description: 鼠标移动时在卡片底部揭示文字的效果。
category: Text Animation
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="TextRevealCardDemo.vue" config="TextRevealCardConfig" componentId="text-reveal-card" :componentFiles='["TextRevealCard.vue", "TextRevealStars.vue"]'}

#api

## API

| 属性名     | 类型     | 描述                       |
| ---------- | -------- | -------------------------- |
| class      | `String` | 卡片的额外类名。           |
| starsCount | `Number` | 控制生成的星星数量。       |
| starsClass | `String` | 应用于漂浮星星的额外类名。 |

| 插槽名     | 描述                         |
| ---------- | ---------------------------- |
| header     | `String`                     |
| text       | 卡片未悬停时显示的默认文字。 |
| revealText | 悬停卡片时显示的文字。       |

#credits

- 感谢 [M Atif](https://github.com/atif0075) 移植该组件。
- 移植自 [Aceternity UI's Text Reveal Card](https://ui.aceternity.com/components/text-reveal-card)。

::

---

### Cn 2.Components Text Animations Text Reveal (`content/cn/2.components/text-animations/text-reveal.md`)

---
title: 文字揭示
description: 使用 GSAP 的 SplitText 实现逐行的文字入场动画。
category: Text Animation
tags: [css, tailwind, gsap]
---

::ComponentViewer{demoFile="TextRevealDemo.vue" config="TextRevealConfig" componentId="text-reveal" :componentFiles='["TextReveal.vue"]' dependencies="gsap"}

#api

## API

| 属性名           | 类型     | 默认值 | 描述                     |
| ---------------- | -------- | ------ | ------------------------ |
| `class`          | `string` | `-`    | 内层文字容器的额外类。   |
| `containerClass` | `string` | `-`    | 外层容器的额外类。       |
| `duration`       | `number` | `0.6`  | 逐行揭示的动画时长。     |
| `delay`          | `number` | `0.2`  | 动画开始前的延迟。       |
| `stagger`        | `number` | `0.1`  | 每行揭示之间的动画间隔。 |

#credits

- 基于 [GSAP](https://gsap.com/) 与 [GSAP SplitText](https://gsap.com/docs/v3/Plugins/SplitText/)。

::

---

### Cn 2.Components Text Animations Text Scroll Reveal (`content/cn/2.components/text-animations/text-scroll-reveal.md`)

---
title: 滚动文字揭示
description: 在滚动时逐词显现的文字组件，可自定义内容与样式。
category: Text Animation
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="TextScrollRevealDemo.vue" config="TextScrollRevealConfig" componentId="text-scroll-reveal" :componentFiles='["TextScrollReveal.vue", "ScrollWord.vue"]'}

#api

## API

| 属性名  | 类型     | 默认值 | 描述                                  |
| ------- | -------- | ------ | ------------------------------------- |
| `text`  | `string` | N/A    | 在滚动时逐词显示的文本内容。          |
| `class` | `string` | `""`   | 应用于组件的额外 CSS 类，便于自定义。 |

#credits

- 移植自 [Magic UI Text Reveal](https://magicui.design/docs/components/text-reveal)。

::

---

### Cn 2.Components Text Animations Typewriter Text (`content/cn/2.components/text-animations/typewriter-text.md`)

---
title: 打字机文字
description: 使用可选的动态光标逐字显示并循环切换文本。
category: 文字动画
tags: [css, tailwind, motion-v, typewriter]
badge: New
dependencies: motion-v
---

::ComponentViewer{demoFile="TypewriterTextDemo.vue" config="TypewriterTextConfig" componentId="typewriter-text" :componentFiles='["TypewriterText.vue", "index.ts"]'}

#api

## API

| 属性                      | 类型                                             | 默认值   | 描述                                 |
| ------------------------- | ------------------------------------------------ | -------- | ------------------------------------ |
| `text`                    | `string \| string[]`                             | —        | 要逐字显示的文本或文本序列。         |
| `as`                      | `string`                                         | `"div"`  | 根文本节点使用的 HTML 元素。         |
| `speed`                   | `number`                                         | `50`     | 字符输入之间的延迟，单位为毫秒。     |
| `initialDelay`            | `number`                                         | `0`      | 开始输入前的延迟，单位为毫秒。       |
| `waitTime`                | `number`                                         | `2000`   | 删除或切换到下一段文本前的停留时间。 |
| `deleteSpeed`             | `number`                                         | `30`     | 字符删除之间的延迟，单位为毫秒。     |
| `loop`                    | `boolean`                                        | `true`   | 最后一段文本后是否从第一段重新开始。 |
| `showCursor`              | `boolean`                                        | `true`   | 是否显示动态光标。                   |
| `hideCursorOnType`        | `boolean`                                        | `false`  | 输入或删除文本时是否隐藏光标。       |
| `cursorChar`              | `string`                                         | `"\|"`   | 作为光标显示的字符。                 |
| `cursorAnimationVariants` | `{ initial: VariantType; animate: VariantType }` | 见默认值 | 光标闪烁使用的 Motion variants。     |
| `cursorClass`             | `string`                                         | `"ml-1"` | 应用于光标的额外 class。             |
| `class`                   | `string`                                         | —        | 合并到根元素的额外 class。           |

#credits

- 移植自 [Fancy Components Typewriter](https://fancycomponents.dev/docs/components/text/typewriter)。

::

---

### Cn 2.Components Text Animations Underline Text (`content/cn/2.components/text-animations/underline-text.md`)

---
title: 下划线文字
description: 在悬停时从文字中心或两侧为文字添加动画下划线。
category: Text Animation
tags: [css, tailwind, motion-v, underline]
badge: New
dependencies: motion-v
---

::ComponentViewer{demoFile="UnderlineTextDemo.vue" config="UnderlineTextConfig" componentId="underline-text" :componentFiles='["UnderlineText.vue", "index.ts"]'}

#api

## API

| 属性名                  | 类型                                                     | 默认值   | 描述                           |
| ----------------------- | -------------------------------------------------------- | -------- | ------------------------------ |
| `as`                    | `string`                                                 | `span`   | 文字包装器使用的 HTML 元素。   |
| `variant`               | `"center" \| "comes-in-goes-out" \| "goes-out-comes-in"` | `center` | 下划线动画样式。               |
| `direction`             | `"left" \| "right"`                                      | `left`   | 两侧动画变体使用的方向。       |
| `transition`            | `Record<string, unknown>`                                | 见默认值 | 下划线使用的 Motion 过渡配置。 |
| `underlineHeightRatio`  | `number`                                                 | `0.1`    | 相对于文字字号的下划线高度。   |
| `underlinePaddingRatio` | `number`                                                 | `0.01`   | 相对于字号的文字与下划线间距。 |
| `class`                 | `string`                                                 | —        | 合并到文字包装器的额外 class。 |

使用默认插槽传入文字内容。组件会使用当前文字颜色生成下划线。

#credits

- 移植自 [Fancy Components Underline Animation](https://fancycomponents.dev/docs/components/text/underline-animation)。

::

---

### Cn 2.Components Text Animations Variable Letter Text (`content/cn/2.components/text-animations/variable-letter-text.md`)

---
title: 可变字母文字
description: 悬停文字时，为每个字母分别应用可变字体轴动画。
category: 文字动画
tags: [css, tailwind, motion-v, variable-font]
badge: New
dependencies: motion-v
---

::ComponentViewer{demoFile="VariableLetterTextDemo.vue" config="VariableLetterTextConfig" componentId="variable-letter-text" :componentFiles='["VariableLetterText.vue", "index.ts"]'}

#api

## API

| 属性                        | 类型                                      | 默认值         | 说明                         |
| --------------------------- | ----------------------------------------- | -------------- | ---------------------------- |
| `label`                     | `string`                                  | —              | 要拆分并分别动画的文字。     |
| `fromFontVariationSettings` | `string`                                  | `"'wght' 400"` | 静止状态使用的字体轴设置。   |
| `toFontVariationSettings`   | `string`                                  | `"'wght' 900"` | 悬停时使用的字体轴设置。     |
| `transition`                | `Transition`                              | 弹簧过渡       | 每个字母使用的 Motion 过渡。 |
| `staggerDuration`           | `number`                                  | `0.03`         | 每个字母动画开始之间的延迟。 |
| `staggerFrom`               | `"first" \| "last" \| "center" \| number` | `"first"`      | 用于计算交错顺序的起点。     |
| `class`                     | `string`                                  | —              | 合并到根元素的额外类名。     |

请使用可变字体，并传入该字体支持的轴。例如，Roboto Flex 支持 `wght` 和 `wdth`。

#credits

- 移植自 [Fancy Components Variable Font Hover By Letter](https://fancycomponents.dev/docs/components/text/variable-font-hover-by-letter)。

::

---

### Cn 2.Components Text Animations Variable Text (`content/cn/2.components/text-animations/variable-text.md`)

---
title: 可变文字
description: 让可变字体轴根据指针距离变化，也可以在悬停时按随机顺序显示每个字母。
category: 文字动画
tags: [css, tailwind, motion-v, variable-font]
badge: New
dependencies: motion-v
---

::ComponentViewer{demoFile="VariableTextDemo.vue" config="VariableTextConfig" componentId="variable-text" :componentFiles='["VariableText.vue", "index.ts"]'}

#api

## API

| 属性                        | 类型                                      | 默认值     | 说明                                           |
| --------------------------- | ----------------------------------------- | ---------- | ---------------------------------------------- |
| `label`                     | `string`                                  | —          | 要拆分并逐字母动画的文本。                     |
| `fromFontVariationSettings` | `string`                                  | —          | 静止状态和离开作用范围时使用的字体轴设置。     |
| `toFontVariationSettings`   | `string`                                  | —          | 指针位于字母中心时使用的字体轴设置。           |
| `containerRef`              | `MaybeComputedElementRef`                 | —          | 用于计算接近模式指针坐标的容器元素。           |
| `radius`                    | `number`                                  | `50`       | 字母响应指针的像素范围。                       |
| `falloff`                   | `"linear" \| "exponential" \| "gaussian"` | `"linear"` | 控制效果随距离衰减的方式。                     |
| `random`                    | `boolean`                                 | `false`    | 悬停时按随机字母顺序动画，而不是跟踪指针距离。 |
| `transition`                | `Transition`                              | 弹簧过渡   | 随机模式使用的 Motion 过渡。                   |
| `staggerDuration`           | `number`                                  | `0.03`     | 随机模式中字母之间的延迟。                     |
| `as`                        | `string`                                  | `"span"`   | 根文字节点使用的 HTML 元素。                   |
| `class`                     | `string`                                  | —          | 合并到根元素的额外类名。                       |

#credits

- 移植自 [Fancy Components Variable Font Cursor Proximity](https://fancycomponents.dev/docs/components/text/variable-font-cursor-proximity)。
- 随机字母行为基于 [Fancy Components Variable Font Hover By Random Letter](https://fancycomponents.dev/docs/components/text/variable-font-hover-by-random-letter)。

::

---

### Cn 2.Components Visualization Bending Gallery (`content/cn/2.components/visualization/bending-gallery.md`)

---
title: 弯曲画廊
description: 带曲面布局的可滚动 3D 画廊，使用 WebGL 与 OGL 渲染动态图片卡片和动画文字。
category: Visualization
tags: [css, tailwind, ogl, webgl]
---

::ComponentViewer{demoFile="BendingGalleryDemo.vue" config="BendingGalleryConfig" componentId="bending-gallery" :componentFiles='["BendingGallery.vue"]' dependencies="ogl"}

#api

## API

| 属性名         | 类型                                | 默认值                | 描述                                 |
| -------------- | ----------------------------------- | --------------------- | ------------------------------------ |
| `items`        | `{ image: string; text: string }[]` | `[]`                  | 包含图片 URL 与文字的对象数组。      |
| `bend`         | `number`                            | `3`                   | 控制画廊弯曲程度，值越大弯曲越明显。 |
| `textColor`    | `string`                            | `"#ffffff"`           | 图片下方文本的颜色。                 |
| `borderRadius` | `number`                            | `0.05`                | 图片卡片的圆角（UV 空间中的值）。    |
| `font`         | `string`                            | `"bold 30px DM Sans"` | 文本使用的字体。                     |

#credits

- 灵感来自 [Codrops 的 Infinite Circular Gallery](https://tympanus.net/Tutorials/InfiniteCircularGallery/)。

::

---

### Cn 2.Components Visualization Carousal 3d (`content/cn/2.components/visualization/carousal-3d.md`)

---
title: 3D 轮播
description: 使用 Three.js 与 Motion-V 的动态交互 3D 轮播组件，支持平滑无限旋转与用户控制。
category: Visualization
tags: [css, tailwind, threejs, motion-v]
---

::ComponentViewer{demoFile="Carousel3dDemo.vue" config="Carousel3dConfig" componentId="carousel-3d" :componentFiles='["Carousel3D.vue"]'}

#api

## API

| 属性名           | 类型        | 默认值 | 描述                          |
| ---------------- | ----------- | ------ | ----------------------------- |
| `items`          | `unknown[]` | `[]`   | 轮播中展示的图片或元素列表。  |
| `class`          | `string`    | `""`   | 用于轮播覆盖层的额外 CSS 类。 |
| `containerClass` | `string`    | `""`   | 轮播容器的 CSS 类。           |
| `width`          | `number`    | `450`  | 单个轮播项的宽度。            |
| `height`         | `number`    | `600`  | 单个轮播项的高度。            |

#credits

- 使用 Three.js 进行 3D 渲染。
- 使用 Motion-V 实现平滑动画。
- 感谢 [@safakdinc](https://github.com/safakdinc) 分享此组件。

::

---

### Cn 2.Components Visualization File Tree (`content/cn/2.components/visualization/file-tree.md`)

---
title: 文件树
description: 用于展示目录中文件与文件夹结构的组件。
category: Visualization
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="FileTreeDemo.vue" config="FileTreeConfig" componentId="file-tree" :componentFiles='["Tree.vue", "Folder.vue", "File.vue", "TreeIndicator.vue", "index.ts"]'}

#api

## API

### `Tree`

`Tree` 组件作为容器，用于展示层级化的文件/文件夹结构。

#### Props

| 属性名                 | 类型                | 默认值                 | 描述                       |
| ---------------------- | ------------------- | ---------------------- | -------------------------- |
| `class`                | `string`            | -                      | 树容器的额外样式类。       |
| `initialSelectedId`    | `string`            | -                      | 初始选中项的 ID。          |
| `indicator`            | `boolean`           | `true`                 | 是否显示树状指示线。       |
| `elements`             | `TreeViewElement[]` | -                      | 要展示的树元素数组。       |
| `initialExpandedItems` | `string[]`          | -                      | 初始展开的文件夹 ID 数组。 |
| `openIcon`             | `string`            | `"lucide:folder-open"` | 展开文件夹时使用的图标。   |
| `closeIcon`            | `string`            | `"lucide:folder"`      | 收起文件夹时使用的图标。   |
| `fileIcon`             | `string`            | `"lucide:file"`        | 文件使用的图标。           |
| `direction`            | `"rtl" \| "ltr"`    | `"ltr"`                | 树的文字方向。             |

### `Folder` 与 `File`

`Folder` 与 `File` 组件分别表示文件夹和文件。文件夹可包含其他 `Folder` 与 `File`。

#### Props

| 属性名         | 类型      | 默认值  | 描述                     |
| -------------- | --------- | ------- | ------------------------ |
| `class`        | `string`  | -       | 用于自定义样式的额外类。 |
| `id`           | `string`  | -       | 元素的唯一标识。         |
| `name`         | `string`  | -       | 文件夹/文件的显示名称。  |
| `isSelectable` | `boolean` | `true`  | 元素是否可被选中。       |
| `isSelect`     | `boolean` | `false` | 元素当前是否被选中。     |

#credits

- 灵感来自 [Magic UI](https://magicui.design/docs/components/file-tree)。
- 感谢 [kalix127](https://github.com/kalix127) 对该组件的移植。

::

---

### Cn 2.Components Visualization Github Globe (`content/cn/2.components/visualization/github-globe.md`)

---
title: Github 地球
description: 可自定义弧线、点与动画的 3D 互动地球可视化，灵感来自 Github。
category: Visualization
tags: [css, tailwind, threejs, aceternity-ui]
---

::ComponentViewer{demoFile="GithubGlobeDemo.vue" config="GithubGlobeConfig" componentId="github-globe" :componentFiles='["GithubGlobe.vue"]' dependencies="three postprocessing three-globe" devDependencies="@types/three"}

#api

#### 下载 GeoJSON 文件

从 [GeoJSON Maps](https://geojson-maps.kyd.au/) 按需选择大陆与精度下载地理数据，将文件保存为与组件同目录的 `globe.json`。

## API

| 属性名        | 类型         | 默认值 | 描述                                                       |
| ------------- | ------------ | ------ | ---------------------------------------------------------- |
| `globeConfig` | `object`     | `{}`   | 地球的配置项，包括颜色、大气、旋转速度与光照等。           |
| `data`        | `Position[]` | `[]`   | 表示地球上弧线与点的坐标数组，包含纬度、经度、颜色等信息。 |
| `class`       | `string`     | `""`   | 用于自定义样式的额外 CSS 类。                              |

### `globeConfig` 属性

| 属性                 | 类型      | 默认值                  | 描述                   |
| -------------------- | --------- | ----------------------- | ---------------------- |
| `pointSize`          | `number`  | `1`                     | 地球上单个点的大小。   |
| `globeColor`         | `string`  | `"#1d072e"`             | 地球表面的颜色。       |
| `showAtmosphere`     | `boolean` | `true`                  | 是否显示大气层。       |
| `atmosphereColor`    | `string`  | `"#ffffff"`             | 大气层颜色。           |
| `atmosphereAltitude` | `number`  | `0.1`                   | 大气层的高度。         |
| `emissive`           | `string`  | `"#000000"`             | 材质的自发光颜色。     |
| `emissiveIntensity`  | `number`  | `0.1`                   | 自发光强度。           |
| `shininess`          | `number`  | `0.9`                   | 材质的高光度。         |
| `polygonColor`       | `string`  | `rgba(255,255,255,0.7)` | 地图多边形边界的颜色。 |
| `arcTime`            | `number`  | `2000`                  | 弧线动画的持续时间。   |
| `arcLength`          | `number`  | `0.9`                   | 弧线长度。             |
| `rings`              | `number`  | `1`                     | 每个点显示的环数量。   |
| `maxRings`           | `number`  | `3`                     | 每个点的最大环数量。   |
| `initialPosition`    | `object`  | `{ lat: 0, lng: 0 }`    | 地球初始经纬度。       |
| `autoRotate`         | `boolean` | `false`                 | 是否自动旋转。         |
| `autoRotateSpeed`    | `number`  | `0.8`                   | 启用自动旋转时的速度。 |

### `data` 结构（Position）

| 字段       | 类型     | 描述                              |
| ---------- | -------- | --------------------------------- |
| `order`    | `number` | 点或弧线的顺序。                  |
| `startLat` | `number` | 弧线起点纬度。                    |
| `startLng` | `number` | 弧线起点经度。                    |
| `endLat`   | `number` | 弧线终点纬度。                    |
| `endLng`   | `number` | 弧线终点经度。                    |
| `arcAlt`   | `number` | 弧线的高度（决定弧线的抬升）。    |
| `color`    | `string` | 弧线或点的颜色，支持 hex 或 RGB。 |

#credits

- 基于 Three.js 与 Three Globe 构建，适用于地理数据可视化与动态效果。
- 移植自 [Aceternity UI](https://ui.aceternity.com/components/github-globe)。

::

---

### Cn 2.Components Visualization Globe (`content/cn/2.components/visualization/globe.md`)

---
title: 地球
description: 可交互的旋转地球组件。
category: Visualization
tags: [css, tailwind, cobe, magic-ui]
---

::ComponentViewer{demoFile="GlobeDemo.vue" config="GlobeConfig" componentId="globe" :componentFiles='["Globe.vue"]' dependencies="cobe vue-use-spring"}

#api

## API

| 属性名      | 类型          | 默认值  | 描述                                                                         |
| ----------- | ------------- | ------- | ---------------------------------------------------------------------------- |
| `class`     | `string`      | `""`    | 用于自定义样式的额外 CSS 类。                                                |
| `config`    | `COBEOptions` | N/A     | 地球的配置对象，遵循 **[COBE](https://cobe.vercel.app/docs/api)** 库的选项。 |
| `mass`      | `number`      | `1`     | 控制旋转惯性的弹簧质量参数。                                                 |
| `tension`   | `number`      | `280`   | 弹簧张力参数，影响响应速度。                                                 |
| `friction`  | `number`      | `100`   | 弹簧摩擦参数，影响阻尼。                                                     |
| `precision` | `number`      | `0.001` | 弹簧计算的精度参数。                                                         |

#credits

- 基于 [cobe](https://github.com/shuding/cobe) 库实现 WebGL 地球可视化。
- 移植自 [Magic UI](https://magicui.design/docs/components/globe)。

::

---

### Cn 2.Components Visualization Icon Cloud (`content/cn/2.components/visualization/icon-cloud.md`)

---
title: 图标云
description: 交互式 3D 标签云组件。
category: Visualization
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="IconCloudDemo.vue" config="IconCloudConfig" componentId="icon-cloud" :componentFiles='["IconCloud.vue", "index.ts"]'}

#api

## API

| 属性名   | 类型     | 默认值 | 描述                          |
| -------- | -------- | ------ | ----------------------------- |
| `class`  | `string` | -      | 自定义组件样式的额外类名。    |
| `images` | `array`  | `[]`   | 要在云中渲染的图片 URL 数组。 |

#credits

- 灵感来自 [MagicUI](https://magicui.design/docs/components/icon-cloud)。
- 感谢 [kalix127](https://github.com/kalix127) 对该组件的移植。

::

---

### Cn 2.Components Visualization Infinite Grid (`content/cn/2.components/visualization/infinite-grid.md`)

---
title: 无限网格
description: 使用 OGL 构建的高性能交互式 3D 无限网格组件，效果类似 phantom.land。
category: Visualization
tags: [css, tailwind, phantom-land, ogl, webgl]
badge: Updated
---

::ComponentViewer{demoFile="InfiniteGridDemo.vue" config="InfiniteGridConfig" componentId="infinite-grid" :componentFiles='["InfiniteGrid.vue", "InfiniteGridClass.ts", "DisposalManager.ts", "EventHandler.ts", "GridManager.ts", "PostProcessShader.ts", "createTexture.ts", "shaders.ts", "types.ts"]' dependencies="ogl gsap"}

#api

## API

| 属性名     | 类型                           | 默认值 | 描述                                         |
| ---------- | ------------------------------ | ------ | -------------------------------------------- |
| `cardData` | `CardData[]`                   | `[]`   | 网格中每个方块的数据。**必填**。             |
| `options`  | `Partial<InfiniteGridOptions>` | `{}`   | 布局、相机与后期处理的可选覆盖项（见下表）。 |

### `InfiniteGridOptions`

| 选项                                    | 类型      | 默认值 | 描述                            |
| --------------------------------------- | --------- | ------ | ------------------------------- |
| `gridCols`                              | `number`  | `4`    | 网格列数。                      |
| `gridRows`                              | `number`  | `4`    | 网格行数。                      |
| `gridGap`                               | `number`  | `0`    | 方块之间的间距。                |
| `tileSize`                              | `number`  | `2.4`  | 方块尺寸（OGL 单位）。          |
| `baseCameraZ`                           | `number`  | `10`   | 相机的初始 Z 轴距离。           |
| `enablePostProcessing`                  | `boolean` | `true` | 是否启用后期处理流程。          |
| `postProcessParams.distortionIntensity` | `number`  | `-0.2` | 枕形/桶形畸变强度（0 表示无）。 |
| `postProcessParams.vignetteOffset`      | `number`  | `0.0`  | 暗角偏移；值越大清晰区域越小。  |
| `postProcessParams.vignetteDarkness`    | `number`  | `0.0`  | 暗角深度；值越大边缘越暗。      |

---

### `CardData`

| 字段          | 类型       | 必填 | 描述                           |
| ------------- | ---------- | ---- | ------------------------------ |
| `title`       | `string`   | ✓    | 主标题文本。                   |
| `badge`       | `string`   | ✓    | 徽章文字（渲染逻辑可自定义）。 |
| `description` | `string`   | –    | 详细正文。                     |
| `tags`        | `string[]` | ✓    | 底部展示的标签。               |
| `date`        | `string`   | ✓    | 显示在右下角的日期。           |
| `image`       | `string`   | –    | 方块背景图的 URL。             |

---

## Emits

| 事件名         | 负载                                | 描述                                                                     |
| -------------- | ----------------------------------- | ------------------------------------------------------------------------ |
| `tileClicked`  | `{ card: CardData, index: number }` | 当点击/轻触方块时触发，包含被点击的 `CardData` 及其从 0 开始的 `index`。 |
| `onTileLoaded` | -                                   | 当方块中的所有图片加载完成时触发。                                       |

#credits

- 灵感来自 [Phantom Land](https://phantom.land)。
- 特别感谢 [Safak Dinc](https://github.com/safakdinc) 提供想法并授权包含原项目，可在 [infinite-grid](https://github.com/safakdinc/infinite-grid) 查看原始仓库。
- 感谢 [kalix127](https://github.com/kalix127) 对该组件的移植。

::

---

### Cn 2.Components Visualization Light Speed (`content/cn/2.components/visualization/light-speed.md`)

---
title: 光速动效
description: 使用 Three.js 构建的高度可定制 3D 高速公路视觉效果，包含道路、车辆、灯光与失真等动画，可模拟沉浸式运动感。
category: Visualization
tags: [css, tailwind, threejs, codrops]
---

::ComponentViewer{demoFile="LightSpeedDemo.vue" config="LightSpeedConfig" componentId="light-speed" :componentFiles='["LightSpeed.vue", "LightSpeedApp.ts", "presets.ts", "shaders.ts"]' dependencies="three postprocessing"}

#api

## API

| 属性名          | 类型                         | 默认值              | 描述                                               |
| --------------- | ---------------------------- | ------------------- | -------------------------------------------------- |
| `effectOptions` | `Partial<LightSpeedOptions>` | 见 `defaultOptions` | 配置对象，用于自定义道路、灯光、失真、速度与颜色。 |

#credits

- 从 [Codrops 文章](https://tympanus.net/codrops/2019/11/13/high-speed-light-trails-in-three-js/) 移植至 Vue。

::

---

### Cn 2.Components Visualization Liquid Glass (`content/cn/2.components/visualization/liquid-glass.md`)

---
title: 液态玻璃效果
description: 使用 SVG 置换滤镜实现的玻璃拟态效果，类似 Apple Liquid Glass。
category: Visualization
tags: [css, tailwind, apple, svg]
---

::ComponentViewer{demoFile="LiquidGlassDemo.vue" config="LiquidGlassConfig" componentId="liquid-glass" :componentFiles='["LiquidGlass.vue"]' }

#api

## API

| 属性名           | 类型                | 默认值         | 描述                                        |
| ---------------- | ------------------- | -------------- | ------------------------------------------- |
| `radius`         | `number`            | `16`           | 玻璃容器的圆角半径（像素）。                |
| `border`         | `number`            | `0.07`         | 相对边框厚度，影响置换滤镜的内边距。        |
| `lightness`      | `number`            | `50`           | 覆盖层颜色的亮度（0-100，HSL 计）。         |
| `blend`          | `string`            | `"difference"` | 用于红蓝置换层的 CSS 混合模式。             |
| `xChannel`       | `"R" \| "G" \| "B"` | `"R"`          | 用于水平置换的通道。                        |
| `yChannel`       | `"R" \| "G" \| "B"` | `"B"`          | 用于垂直置换的通道。                        |
| `alpha`          | `number`            | `0.93`         | 覆盖层的透明度（0-1）。                     |
| `blur`           | `number`            | `11`           | 应用于覆盖层的高斯模糊半径。                |
| `rOffset`        | `number`            | `0`            | 红色置换贴图的额外缩放偏移。                |
| `gOffset`        | `number`            | `10`           | 绿色置换贴图的额外缩放偏移。                |
| `bOffset`        | `number`            | `20`           | 蓝色置换贴图的额外缩放偏移。                |
| `scale`          | `number`            | `-180`         | 置换效果的基础缩放，与各通道偏移叠加。      |
| `frost`          | `number`            | `0.05`         | 控制磨砂玻璃背景叠加强度的透明度系数。      |
| `class`          | `string`            | `""`           | 应用于包裹内容的内层插槽容器的额外 CSS 类。 |
| `containerClass` | `string`            | `""`           | 应用于外层容器 div 的额外 CSS 类。          |

#credits

- 灵感来自 Apple Liquid Glass。

::

::warning
该组件使用 SVG 滤镜实现背景模糊。Safari 不支持，Firefox 支持也非常有限。

建议在目标为 Chromium 内核浏览器时使用此组件，并在 Safari 或 Firefox 上提供备用组件。

例如，Inspira UI 落地页会在 Chromium 浏览器使用 Liquid Glass，在 Safari 与 Mozilla 上回退为磨砂玻璃效果。
::

---

### Cn 2.Components Visualization Liquid Logo (`content/cn/2.components/visualization/liquid-logo.md`)

---
title: 液态 Logo
description: 基于 WebGL 的高级组件，通过自定义着色器为徽标或图像添加动态液态效果。
category: Visualization
tags: [css, tailwind, webgl, paper]
---

::ComponentViewer{demoFile="LiquidLogoDemo.vue" config="LiquidLogoConfig" componentId="liquid-logo" :componentFiles='["LiquidLogo.vue", "parseLogoImage.ts", "shader.ts"]' }

#api

## API

| 属性名         | 类型     | 默认值  | 描述                          |
| -------------- | -------- | ------- | ----------------------------- |
| `class`        | `string` | `""`    | 用于自定义样式的额外 CSS 类。 |
| `imageUrl`     | `string` | `""`    | 应用液态效果的图片 URL。      |
| `patternScale` | `number` | `2`     | 置换图案的缩放。              |
| `refraction`   | `number` | `0.015` | 应用于图像的折射程度。        |
| `edge`         | `number` | `0.4`   | 边缘效果的锐利度。            |
| `patternBlur`  | `number` | `0.005` | 应用于图案的模糊。            |
| `liquid`       | `number` | `0.07`  | 液态动画的强度。              |
| `speed`        | `number` | `0.3`   | 液态效果的动画速度。          |

#credits

- 灵感来自 Apple Fluid Motion 设计。
- 从 [Paper Design Concept](https://github.com/paper-design/liquid-logo) 移植并改进。

::

---

### Cn 2.Components Visualization Logo Cloud (`content/cn/2.components/visualization/logo-cloud.md`)

---
title: 动态 Logo 云
description: 动态展示公司 Logo 的云图，可用于展示合作或客户徽标。
category: Visualization
tags: [css, tailwind]
---

::ComponentViewer{demoFile="IconLogoCloudDemo.vue" config="IconLogoCloudConfig" componentId="logo-cloud" :componentFiles='["AnimatedLogoCloud.vue", "IconLogoCloud.vue", "StaticLogoCloud.vue", "index.ts"]'}

#api

## API

| 属性名  | 类型     | 默认值                      | 描述                                     |
| ------- | -------- | --------------------------- | ---------------------------------------- |
| `class` | `string` | `-`                         | 将每个项目加入列表前的延迟时间（毫秒）。 |
| `title` | `string` | `Trusted by Companies like` | 动态 Logo 云的标题。                     |
| `logos` | `[]`     | `[{name: "", path: ""}]`    | Logo 数组，包含名称与路径字段。          |

#credits

- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi) 提供该组件。

::

---

### Cn 2.Components Visualization Logo Origami (`content/cn/2.components/visualization/logo-origami.md`)

---
title: 折纸 Logo
description: 带折纸效果的翻转 Logo 动画。
category: Visualization
tags: [css, tailwind, hover-dev]
---

::ComponentViewer{demoFile="LogoOrigamiDemo.vue" config="LogoOrigamiConfig" componentId="logo-origami" :componentFiles='["LogoOrigami.vue", "LogoOrigamiItem.vue"]'}

#api

## API

| 属性名     | 类型     | 默认值 | 描述                           |
| ---------- | -------- | ------ | ------------------------------ |
| `class`    | `string` | `""`   | 用于自定义样式的额外 CSS 类。  |
| `duration` | `number` | `1.5`  | 翻转动画的持续时间（秒）。     |
| `delay`    | `number` | `2.5`  | 两次翻转动画之间的延迟（秒）。 |

#credits

- 灵感来自 [hover.dev](https://www.hover.dev/components/other#logo-origami) 的折纸翻转动画。

::

---

### Cn 2.Components Visualization Orbit (`content/cn/2.components/visualization/orbit.md`)

---
title: 轨道动画
description: 让内容沿圆轨道运动的组件，可自定义持续时间、延迟与半径，并可选择显示轨道路径。
category: Visualization
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="OrbitDemo.vue" config="OrbitConfig" componentId="orbit" :componentFiles='["Orbit.vue", "index.ts"]'}

#api

## API

| 属性名      | 类型                  | 默认值   | 描述                                       |
| ----------- | --------------------- | -------- | ------------------------------------------ |
| `direction` | `normal` \| `reverse` | `normal` | 轨道运动方向，可使用常量 ORBIT_DIRECTION。 |
| `duration`  | `?number`             | `20`     | 轨道动画持续时间（秒）。                   |
| `delay`     | `?number`             | `10`     | 动画开始前的延迟时间（秒）。               |
| `radius`    | `?number`             | `50`     | 轨道半径（像素）。                         |
| `path`      | `?boolean`            | `false`  | 若为 `true`，显示轨道圆路径。              |

#credits

- 灵感来自 [Magic UI](https://magicui.design/docs/components/orbiting-circles)。
- 感谢 [Nathan De Pachtere](https://nathandepachtere.com/) 更新此组件。

::

---

### Cn 2.Components Visualization Spline (`content/cn/2.components/visualization/spline.md`)

---
title: Spline
description: Spline 3D 工具的 Vue 包装组件，提供事件与自动缩放。
category: Visualization
tags: [css, tailwind, spline]
badge: Updated
---

::ComponentViewer{demoFile="SplineDemo.vue" config="SplineConfig" componentId="spline" :componentFiles='["Spline.vue", "ParentSize.vue"]' dependencies="@splinetool/runtime"}

#api

## API

| 属性名           | 类型       | 默认值      | 描述                                     |
| ---------------- | ---------- | ----------- | ---------------------------------------- |
| `scene`          | `string`   | —           | Spline 场景文件的 URL 或路径。**必填**。 |
| `onLoad`         | `Function` | `undefined` | Spline 场景成功加载时触发的回调。        |
| `renderOnDemand` | `boolean`  | `true`      | 是否启用 Spline 的按需渲染优化。         |
| `style`          | `object`   | `{}`        | 应用于画布容器的自定义 CSS 样式。        |

**Emits**

| 事件名               | 负载    | 描述                                       |
| -------------------- | ------- | ------------------------------------------ |
| `error`              | `Error` | 加载 Spline 场景出错时触发。               |
| `spline-mouse-down`  | `any`   | Spline 场景内捕获到 mouseDown 事件时触发。 |
| `spline-mouse-up`    | `any`   | 捕获到 mouseUp 事件时触发。                |
| `spline-mouse-hover` | `any`   | 触发 mouseHover 事件时发出。               |
| `spline-key-down`    | `any`   | 在 Spline 场景中捕获到 keyDown 时触发。    |
| `spline-key-up`      | `any`   | 捕获到 keyUp 时触发。                      |
| `spline-start`       | `any`   | Spline 场景开始时触发。                    |
| `spline-look-at`     | `any`   | 发生 lookAt 事件时触发。                   |
| `spline-follow`      | `any`   | 发生 follow 事件时触发。                   |
| `spline-scroll`      | `any`   | 发生滚动交互时触发。                       |

#credits

- 底层使用 Spline 的 runtime。
- 灵感来自多种基于 Spline 的 3D Web 体验。

::

---

### Cn 2.Components Visualization World Map (`content/cn/2.components/visualization/world-map.md`)

---
title: 世界地图
description: 展示带有动画弧线和脉冲点效果的可自定义世界地图。
category: Visualization
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="WorldMapDemo.vue" config="WorldMapConfig" componentId="world-map" :componentFiles='["WorldMap.vue"]' dependencies="dotted-map"}

#api

## API

| 属性名       | 类型                                                                                                                | 默认值      | 描述                                               |
| ------------ | ------------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------- |
| `dots`       | `Array<{ start: { lat: number; lng: number; label?: string }, end: { lat: number; lng: number; label?: string } }>` | `[]`        | 点对象数组，每个包含起点与终点坐标（纬度、经度）。 |
| `class`      | `string`                                                                                                            | `""`        | 用于自定义样式的额外 CSS 类。                      |
| `lineColor`  | `string`                                                                                                            | `"#0EA5E9"` | 弧线与点边框的颜色。                               |
| `mapColor`   | `string`                                                                                                            | —           | 点状地图的主色。(**必填**)                         |
| `mapBgColor` | `string`                                                                                                            | —           | 地图背景色。(**必填**)                             |

#credits

- 移植自 [Aceternity UI 的 World Map](https://ui.aceternity.com/components/world-map)。

::

---

### En 2.Components Backgrounds Aurora Background (`content/en/2.components/backgrounds/aurora-background.md`)

---
title: Aurora Background
description: A subtle Aurora or Southern Lights background for your website.
category: Background
tags: [css, tailwind, background, aceternity-ui]
---

::ComponentViewer{demoFile="AuroraBackgroundDemo.vue" config="AuroraBackgroundConfig" componentId="aurora-background" :componentFiles='["AuroraBackground.vue"]'}

#instructions

Add following entry to inline theme in your `main.css` file.

```css
@theme inline {
  --animate-aurora: aurora 60s linear infinite;
  @keyframes aurora {
    from {
      background-position:
        50% 50%,
        50% 50%;
    }
    to {
      background-position:
        350% 50%,
        350% 50%;
    }
  }
}
```

#api

## API

| Prop Name        | Type      | Default | Description                                                               |
| ---------------- | --------- | ------- | ------------------------------------------------------------------------- |
| `class`          | `string`  | `-`     | Additional CSS classes to apply to the component for styling.             |
| `radialGradient` | `boolean` | `true`  | Determines whether a radial gradient effect is applied to the background. |

#credits

- Credits to [Aceternity UI](https://ui.aceternity.com/components/aurora-background).
- Credits to [SivaReddy Uppathi](https://github.com/sivareddyuppathi) for porting this component.

::

---

### En 2.Components Backgrounds Black Hole Background (`content/en/2.components/backgrounds/black-hole-background.md`)

---
title: Black Hole Background
description: A mesmerizing, canvas-driven background effect that simulates a warped “black-hole” tunnel with animated discs, radial lines, and particles.
category: Background
tags: [css, tailwind, background, motion-v, canvas]
---

::ComponentViewer{demoFile="BlackHoleBackgroundDemo.vue" config="BlackHoleBackgroundConfig" componentId="bg-black-hole" :componentFiles='["BlackHoleBackground.vue"]'}

#api

## API

| Prop Name          | Type                       | Default         | Description                                                   |
| ------------------ | -------------------------- | --------------- | ------------------------------------------------------------- |
| `strokeColor`      | `string`                   | `"#737373"`     | Stroke colour for the concentric discs and radial lines.      |
| `numberOfLines`    | `number`                   | `50`            | Total radial lines emanating from the centre.                 |
| `numberOfDiscs`    | `number`                   | `50`            | Total concentric ellipses that form the tunnel.               |
| `particleRGBColor` | `[number, number, number]` | `[255,255,255]` | RGB colour used for the tiny particles flowing into the hole. |
| `class`            | `string`                   | `""`            | Extra utility classes merged onto the root wrapper.           |

#credits

- Custom generative art logic inspired by tunnel / warp animations.
- Utilises **Motion-V** for gradient drift and Vue 3 Composition API for lifecycle control.
- Developed with accessibility in mind—background effect remains purely decorative via `aria-hidden` canvas.

::

---

### En 2.Components Backgrounds Bubbles Bg (`content/en/2.components/backgrounds/bubbles-bg.md`)

---
title: Bubbles Background
description: An animated background with floating bubbles.
category: Background
tags: [css, tailwind, background, threejs]
---

::ComponentViewer{demoFile="BubblesBgDemo.vue" config="BubblesBgConfig" componentId="bg-bubbles" :componentFiles='["BubblesBg.vue"]' dependencies="three" devDependencies="@types/three"}

#api

## API

| Prop Name | Type     | Default | Description                                                     |
| --------- | -------- | ------- | --------------------------------------------------------------- |
| `blur`    | `number` | `0`     | Amount of blur to apply to the background, specified in pixels. |

#credits

- Built with the [Three.js](https://threejs.org/) library for 3D rendering and animations.
- Inspired from [Tresjs Experiment](https://lab.tresjs.org/experiments/overlay).

::

---

### En 2.Components Backgrounds Cosmic Portal (`content/en/2.components/backgrounds/cosmic-portal.md`)

---
title: Cosmic Portal
description: A breathtaking, animated 3D portal built with Three.js that features glowing rings, floating crystals, space distortion, and interdimensional streams.
category: Background
tags: [css, tailwind, background, threejs, postprocessing]
---

::ComponentViewer{demoFile="CosmicPortalDemo.vue" config="CosmicPortalConfig" componentId="cosmic-portal" :componentFiles='["CosmicPortal.vue"]' dependencies="three postprocessing" devDependencies="@types/three"}

#api

## API

| Prop Name          | Type     | Default   | Description                                                 |
| ------------------ | -------- | --------- | ----------------------------------------------------------- |
| `portalComplexity` | `number` | `4`       | Controls the complexity of the portal effects and geometry. |
| `crystalCount`     | `number` | `12`      | Number of floating crystals in the scene.                   |
| `primaryColor`     | `string` | `#9b59b6` | Main color for portal and background glow.                  |
| `secondaryColor`   | `string` | `#3498db` | Secondary color for blending and glow.                      |
| `accentColor`      | `string` | `#e74c3c` | Color used for portal energy and highlight.                 |
| `vortexColor`      | `string` | `#2ecc71` | Color used for swirling vortex and dimensional streams.     |
| `rotationSpeed`    | `number` | `0.3`     | Speed at which objects rotate.                              |
| `bloomStrength`    | `number` | `1.2`     | Intensity of bloom postprocessing.                          |
| `bloomRadius`      | `number` | `0.7`     | Radius of the bloom effect.                                 |
| `bloomThreshold`   | `number` | `0.2`     | Threshold for bloom visibility.                             |
| `dimensionShift`   | `number` | `4`       | Level of dimension distortion for shader animation.         |

#credits

- Inspired and ported from [Dimensional Portal by Techartist](https://x.com/techartist_).

::

---

### En 2.Components Backgrounds Falling Stars (`content/en/2.components/backgrounds/falling-stars.md`)

---
title: Falling Stars Background
description: A stunning animated starfield background with glowing and sharp trail effects.
category: Background
tags: [css, tailwind, background, canvas]
---

::ComponentViewer{demoFile="FallingStarsBgDemo.vue" config="FallingStarsBgConfig" componentId="bg-falling-stars" :componentFiles='["FallingStarsBg.vue"]'}

#api

## API

| Prop Name | Type     | Default  | Description                                 |
| --------- | -------- | -------- | ------------------------------------------- |
| `color`   | `string` | `"#FFF"` | Color of the stars in the starfield.        |
| `count`   | `number` | `200`    | Number of stars displayed in the animation. |

#credits

- Inspired by 3D starfield simulations and trail effects in modern canvas animations.
- Credit to [Prodromos Pantos](https://github.com/prpanto) for porting the original component to Vue & Nuxt.

::

---

### En 2.Components Backgrounds Flickering Grid (`content/en/2.components/backgrounds/flickering-grid.md`)

---
title: Flickering Grid
description: A flickering grid background made with Canvas, fully customizable using Tailwind CSS.
category: Background
tags: [css, tailwind, background, canvas, magic-ui]
---

::ComponentViewer{demoFile="FlickeringGridDemo.vue" config="FlickeringGridConfig" componentId="flickering-grid" :componentFiles='["FlickeringGrid.vue"]'}

#api

## API

| Prop Name       | Type     | Default        | Description                            |
| --------------- | -------- | -------------- | -------------------------------------- |
| `squareSize`    | `number` | `4`            | Size of each square in the grid.       |
| `gridGap`       | `number` | `6`            | Gap between squares in the grid.       |
| `flickerChance` | `number` | `0.3`          | Probability of a square flickering.    |
| `color`         | `string` | `rgb(0, 0, 0)` | Color of the squares.                  |
| `width`         | `number` | `-`            | Width of the canvas.                   |
| `height`        | `number` | `-`            | Height of the canvas.                  |
| `class`         | `string` | `-`            | Additional CSS classes for the canvas. |
| `maxOpacity`    | `number` | `0.2`          | Maximum opacity of the squares.        |

#credits

- Credits to [magicui flickering-grid](https://magicui.design/docs/components/flickering-grid) for this component.

::

---

### En 2.Components Backgrounds Interactive Grid Pattern (`content/en/2.components/backgrounds/interactive-grid-pattern.md`)

---
title: Interactive Grid Pattern
description: A interactive background grid pattern made with SVGs, fully customizable.
category: Background
tags: [css, tailwind, background, svg, magic-ui]
---

::ComponentViewer{demoFile="InteractiveGridPatternDemo.vue" config="InteractiveGridPatternConfig" componentId="interactive-grid-pattern" :componentFiles='["InteractiveGridPattern.vue"]' }

#api

## API

| Prop Name          | Type               | Default    | Description                                   |
| ------------------ | ------------------ | ---------- | --------------------------------------------- |
| `className`        | `string`           | -          | Additional classes for styling the component. |
| `squaresClassName` | `string`           | -          | Additional classes for styling the squares.   |
| `width`            | `number`           | `40`       | Width of the square in pixels.                |
| `height`           | `number`           | `40`       | Height of the square in pixels.               |
| `squares`          | `[number, number]` | `[24, 24]` | Number of squares in the grid pattern.        |

#credits

- Inspired by [MagicUI](https://magicui.design/docs/components/interactive-grid-pattern).
- Credits to [kalix127](https://github.com/kalix127) for porting this component.

::

---

### En 2.Components Backgrounds Lamp Effect (`content/en/2.components/backgrounds/lamp-effect.md`)

---
title: Lamp Effect
description: A captivating lamp lighting effect with conic gradients, spotlights, and glowing lines for an immersive visual experience.
category: Background
tags: [css, tailwind, background, aceternity-ui]
---

::ComponentViewer{demoFile="LampEffectDemo.vue" config="LampEffectConfig" componentId="lamp-effect" :componentFiles='["LampEffect.vue"]'}

#api

## API

| Prop Name  | Type     | Default | Description                                    |
| ---------- | -------- | ------- | ---------------------------------------------- |
| `delay`    | `number` | `0.5`   | Delay before the animation starts, in seconds. |
| `duration` | `number` | `0.8`   | Duration of the animation, in seconds.         |
| `class`    | `string` | `""`    | Additional CSS classes for custom styling.     |

#credits

- Ported from [Aceternity UI](https://ui.aceternity.com/components/lamp-effect)

::

---

### En 2.Components Backgrounds Liquid Background (`content/en/2.components/backgrounds/liquid-background.md`)

---
title: Liquid Background
description: A reactive and dynamic background effect using OGL for WebGL-based visuals.
category: Background
tags: [css, tailwind, background, ogl, webgl]
---

::ComponentViewer{demoFile="LiquidBackgroundDemo.vue" config="LiquidBackgroundConfig" componentId="liquid-background" :componentFiles='["LiquidBackground.vue"]' dependencies="ogl"}

#api

## API

This component does not require external props to function, as it dynamically renders the liquid background effect on mount.

#credits

- Built with the [OGL](https://github.com/oframe/ogl) library for 3D rendering.
- Inspired by generative art patterns.
- Uses Vue's Composition API for lifecycle and state management.

::

---

### En 2.Components Backgrounds Neural Background (`content/en/2.components/backgrounds/neural-background.md`)

---
title: Neural Background
description: A dynamic, shader-powered animated background with fluid neural-like visuals using OGL and GLSL.
category: Background
tags: [css, tailwind, background, ogl, webgl, cursify]
---

::ComponentViewer{demoFile="NeuralBgDemo.vue" config="NeuralBgConfig" componentId="bg-neural" :componentFiles='["NeuralBg.vue"]'}

#api

## API

| Prop Name    | Type     | Default | Description                                             |
| ------------ | -------- | ------- | ------------------------------------------------------- |
| `hue`        | `number` | `200`   | Base hue for background colors (in degrees, 0–360).     |
| `saturation` | `number` | `0.8`   | Saturation of the background color (0–1).               |
| `chroma`     | `number` | `0.6`   | Chroma/lightness factor of the HSL color (0-1).         |
| `class`      | `string` | `—`     | Optional additional CSS classes for the canvas element. |

> 💡 This component defaults to a full-screen fixed background with `pointer-events-none`. You can override styles via the `class` prop if needed.

#credits

- Built using [OGL](https://github.com/oframe/ogl) — a minimal WebGL framework.
- Math and pattern logic based on recursive trigonometric layering.
- Ported from [Neural Glow Cursor by Cursify](https://cursify.vercel.app/components/neural-glow).

::

---

### En 2.Components Backgrounds Particle Whirlpool Bg (`content/en/2.components/backgrounds/particle-whirlpool-bg.md`)

---
title: Particle Whirlpool
description: An animated background with swirling particles.
category: Background
tags: [css, tailwind, background, threejs, postprocessing]
---

::ComponentViewer{demoFile="ParticleWhirlpoolBgDemo.vue" config="ParticleWhirlpoolBgConfig" componentId="bg-particle-whirlpool" :componentFiles='["ParticleWhirlpoolBg.vue"]' dependencies="three postprocessing" devDependencies="@types/three"}

#api

## API

| Prop Name       | Type     | Default | Description                                                     |
| --------------- | -------- | ------- | --------------------------------------------------------------- |
| `class`         | `string` | `""`    | Additional CSS classes for custom styling.                      |
| `blur`          | `number` | `0`     | Amount of blur to apply to the background, specified in pixels. |
| `particleCount` | `number` | `2000`  | Number of particles in the whirlpool animation.                 |

#credits

- Built with the [Three.js](https://threejs.org/) library for 3D rendering and animations.
- Inspired by [TroisJs](https://troisjs.github.io/examples/demos/3.html)

::

---

### En 2.Components Backgrounds Particles Bg (`content/en/2.components/backgrounds/particles-bg.md`)

---
title: Particles Background
description: Particles can add a dynamic and engaging element to your website's visuals. They help create a feeling of depth, motion, and interaction, making the site more visually appealing.
category: Background
tags: [css, tailwind, background, magic-ui, canvas]
---

::ComponentViewer{demoFile="ParticlesBgDemo.vue" config="ParticlesBgConfig" componentId="particles-bg" :componentFiles='["ParticlesBg.vue"]'}

#api

## API

| Prop Name   | Type     | Default | Description                                                                                                 |
| ----------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `color`     | `string` | `#FFF`  | Hexadecimal color code used for particles. Supports 3 or 6 character hex codes.                             |
| `quantity`  | `number` | `100`   | The number of particles to generate and display on the canvas.                                              |
| `staticity` | `number` | `50`    | Determines how much the particles move based on the mouse's proximity. Higher values reduce movement.       |
| `ease`      | `number` | `50`    | Controls the easing effect of particle movement; lower values make particles follow the mouse more closely. |

#credits

- Credits to [Magic UI](https://magicui.design/docs/components/particles) for this fantastic component.
- Credit to [Prodromos Pantos](https://github.com/prpanto) for porting the original component to Vue & Nuxt.

::

---

### En 2.Components Backgrounds Pattern Background (`content/en/2.components/backgrounds/pattern-background.md`)

---
title: Pattern Background
description: Simple animated pattern background to make your sections stand out.
category: Background
tags: [css, tailwind, background, magic-ui]
---

::ComponentViewer{demoFile="PatternBackgroundDemo.vue" config="PatternBackgroundConfig" componentId="pattern-background" :componentFiles='["PatternBackground.vue", "index.ts"]' dependencies="class-variance-authority"}

#api

## API

| Prop Name   | Type                                                                                                   | Default   | Description                                                                                                                                                    |
| ----------- | ------------------------------------------------------------------------------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `animate`   | `boolean`                                                                                              | `false`   | Set `true` if you want to animate the background.                                                                                                              |
| `direction` | `top` \| `bottom` \| `left` \| `right` \| `top-left` \| `top-right` \| `bottom-left` \| `bottom-right` | `top`     | Direction of the animation movement. You can use the const `PATTERN_BACKGROUND_DIRECTION.`                                                                     |
| `direction` | `grid` \| `dot`                                                                                        | `grid`    | Type of pattern. You can use the const `PATTERN_BACKGROUND_VARIANT.`                                                                                           |
| `size`      | `xs` \| `sm` \| `md` \| `lg`                                                                           | `md`      | Size of the background pattern.                                                                                                                                |
| `mask`      | `ellipse` \| `ellipse-top`                                                                             | `ellipse` | Add a mask over the background pattern. You can use the const `PATTERN_BACKGROUND_MASK.`                                                                       |
| `speed`     | `number`                                                                                               | `10000`   | Duration of the animation in `ms`, the bigger it is, the slower the animation. (`20000` slower than `5000`). You can use the const `PATTERN_BACKGROUND_SPEED.` |

#credits

- Inspired by [Magic UI's Dot Pattern](https://magicui.design/docs/components/dot-pattern) component.
- Inspired by [Magic UI's Grid Pattern](https://magicui.design/docs/components/grid-pattern) component.
- Inspired by [Magic UI's Animated Grid Pattern](https://magicui.design/docs/components/animated-grid-pattern) component.
- Credits to [Nathan De Pachtere](https://nathandepachtere.com/) for porting this component.

::

---

### En 2.Components Backgrounds Ribbon Background (`content/en/2.components/backgrounds/ribbon-background.md`)

---
title: Ribbon Background
description: A layered animated ribbon background with configurable colors, rotation, and transparency.
category: Background
tags: [css, tailwind, background, shader-toy, ogl, webgl]
badge: New
---

::ComponentViewer{demoFile="RibbonBackgroundDemo.vue" config="RibbonBackgroundConfig" componentId="ribbon-background" :componentFiles='["RibbonBackground.vue"]'}

#api

## API

| Prop Name         | Type       | Default                                                   | Description                                                 |
| ----------------- | ---------- | --------------------------------------------------------- | ----------------------------------------------------------- |
| `colors`          | `string[]` | `['#355070', '#6d597a', '#b56576', '#e56b6f', '#eaac8b']` | Five CSS hex colors used by the layered ribbons.            |
| `backgroundColor` | `string`   | `'#282828'`                                               | CSS hex color rendered behind the ribbons.                  |
| `transparent`     | `boolean`  | `false`                                                   | Renders empty background pixels with an alpha value of `0`. |
| `enableShadows`   | `boolean`  | `true`                                                    | Enables shadows between overlapping ribbon layers.          |
| `angle`           | `number`   | `0`                                                       | Rotates the complete ribbon field in degrees.               |
| `offsetX`         | `number`   | `0`                                                       | Moves the ribbon field horizontally in viewport units.      |
| `offsetY`         | `number`   | `0`                                                       | Moves the ribbon field vertically in viewport units.        |
| `speed`           | `number`   | `1`                                                       | Multiplies the animation speed.                             |
| `class`           | `string`   | `—`                                                       | Additional classes applied to the full-size outer element.  |

The component fills its nearest positioned parent. Give the parent an explicit height and `position: relative`.

#credits

- Rendered with the Inspira UI Shader Toy Viewer and [OGL](https://github.com/oframe/ogl).

::

---

### En 2.Components Backgrounds Ripple (`content/en/2.components/backgrounds/ripple.md`)

---
title: Ripple
description: An animated ripple effect typically used behind elements to emphasize them.
category: Background
tags: [css, tailwind, background, magic-ui]
---

::ComponentViewer{demoFile="RippleDemo.vue" config="RippleConfig" componentId="ripple" :componentFiles='["Ripple.vue", "RippleCircle.vue", "RippleContainer.vue"]'}

#api

## API

| Prop Name                     | Type     | Default     | Description                                                            |
| ----------------------------- | -------- | ----------- | ---------------------------------------------------------------------- |
| `baseCircleSize`              | `number` | `210`       | The size of the main circle in pixels.                                 |
| `baseCircleOpacity`           | `number` | `0.24`      | The opacity of the main circle.                                        |
| `spaceBetweenCircle`          | `number` | `70`        | The space between each ripple circle in pixels.                        |
| `circleOpacityDowngradeRatio` | `number` | `0.03`      | The rate at which opacity decreases for each successive ripple circle. |
| `circleClass`                 | `string` | `undefined` | CSS class name(s) for additional styling of circles.                   |
| `waveSpeed`                   | `number` | `80`        | The animation speed for the wave effect, measured in ms.               |
| `numberOfCircles`             | `number` | `7`         | The number of ripple circles to render.                                |

#credits

- Credits to [Magic UI](https://magicui.design/docs/components/ripple).
- Credits to [SivaReddy Uppathi](https://github.com/sivareddyuppathi) for porting this component.
- Credits to [Nathan De Pachtere](https://nathandepachtere.com/) for updating this component.

::

---

### En 2.Components Backgrounds Silk Background (`content/en/2.components/backgrounds/silk-background.md`)

---
title: Silk Background
description: A soft, flowing shader-powered background inspired by silk fabric motion and texture, rendered using ShaderToy.
category: Background
tags: [css, tailwind, background, shader-toy, ogl, webgl]
---

::ComponentViewer{demoFile="SilkBackgroundDemo.vue" config="SilkBackgroundConfig" componentId="bg-silk" :componentFiles='["SilkBackground.vue"]'}

#api

## API

| Prop Name    | Type     | Default | Description                                                                 |
| ------------ | -------- | ------- | --------------------------------------------------------------------------- |
| `hue`        | `number` | `300`   | Base hue for the silk texture (in degrees, 0–360).                          |
| `saturation` | `number` | `0.5`   | Saturation of the color (0–1).                                              |
| `brightness` | `number` | `1`     | Brightness multiplier for the output color (0–2 recommended).               |
| `speed`      | `number` | `1`     | Controls the animation speed multiplier (e.g., `2` = double speed).         |
| `class`      | `string` | `—`     | Optional additional CSS classes for the container div (e.g., z-index, etc). |

> 💡 This component uses a full-screen absolute container by default. You can override positioning or stacking via the `class` prop.

#credits

- Adapted from [this ShaderToy shader](https://www.shadertoy.com/view/X3yXRd) by Giorgi Azmaipharashvili (MIT License).
- Inspired by silk textures and fluid motion patterns found in organic materials.

::

---

### En 2.Components Backgrounds Singularity Background (`content/en/2.components/backgrounds/singularity-background.md`)

---
title: Singularity Background
description: A shader-based background.
category: Background
tags: [css, tailwind, background, shader-toy, webgl, ogl]
---

::ComponentViewer{demoFile="SingularityBackgroundDemo.vue" config="SingularityBackgroundConfig" componentId="bg-singularity" :componentFiles='["SingularityBackground.vue"]'}

#api

## API

| Prop Name          | Type     | Default | Description                                                                 |
| ------------------ | -------- | ------- | --------------------------------------------------------------------------- |
| `hue`              | `number` | `0`     | Base hue for the fractal texture (0–360 degrees).                           |
| `saturation`       | `number` | `1`     | Saturation of the color (0–1).                                              |
| `brightness`       | `number` | `1`     | Brightness multiplier for the output color (0–2 recommended).               |
| `speed`            | `number` | `1`     | Speed multiplier for animation.                                             |
| `mouseSensitivity` | `number` | `0.5`   | Controls the responsiveness to mouse movement. (0–5)                        |
| `damping`          | `number` | `1`     | Damping factor to control the smoothness of texture distortions. (0–1)      |
| `class`            | `string` | `—`     | Optional additional CSS classes for the container div (e.g., z-index, etc). |

> 💡 This component is designed to be used in full-screen or large section backgrounds. It is optimized for modern GPUs but may be demanding on lower-end devices.

#credits

- Adapted from [this ShaderToy shader](https://www.shadertoy.com/view/3csSWB).

::

---

### En 2.Components Backgrounds Snowfall Bg (`content/en/2.components/backgrounds/snowfall-bg.md`)

---
title: Snowfall Background
description: A beautifully animated snowfall effect applied as a background.
category: Background
tags: [css, tailwind, background, canvas]
---

::ComponentViewer{demoFile="SnowfallBgDemo.vue" config="SnowfallBgConfig" componentId="snowfall-bg" :componentFiles='["SnowfallBg.vue"]'}

#api

## API

| Prop Name   | Type     | Default | Description                                               |
| ----------- | -------- | ------- | --------------------------------------------------------- |
| `color`     | `string` | `#FFF`  | Color of the snowflakes in hexadecimal format.            |
| `quantity`  | `number` | `100`   | Number of snowflakes to display.                          |
| `speed`     | `number` | `1`     | Speed at which snowflakes fall.                           |
| `maxRadius` | `number` | `3`     | Maximum radius of snowflakes.                             |
| `minRadius` | `number` | `1`     | Minimum radius of snowflakes.                             |
| `class`     | `string` | `null`  | Additional CSS classes to apply to the container element. |

#credits

- Inspired by natural snowfall effects.

::

---

### En 2.Components Backgrounds Sparkles (`content/en/2.components/backgrounds/sparkles.md`)

---
title: Sparkles
description: A configurable sparkles component that can be used as a background or as a standalone component.
category: Background
tags: [css, tailwind, background, canvas]
---

::ComponentViewer{demoFile="SparklesDemo.vue" config="SparklesConfig" componentId="sparkles" :componentFiles='["Sparkles.vue"]'}

#api

## API

| Prop Name         | Type     | Default     | Description                                                                            |
| ----------------- | -------- | ----------- | -------------------------------------------------------------------------------------- |
| `background`      | `string` | `'#0d47a1'` | Background color of the container. Use 'transparent' to see through to parent element. |
| `particleColor`   | `string` | `'#ffffff'` | Color of the particles. Accepts any valid CSS color value.                             |
| `minSize`         | `number` | `1`         | Minimum size of particles in pixels.                                                   |
| `maxSize`         | `number` | `3`         | Maximum size of particles in pixels.                                                   |
| `speed`           | `number` | `4`         | Movement speed multiplier. Higher values create faster movement.                       |
| `particleDensity` | `number` | `120`       | Number of particles to render. Higher values create denser particle fields.            |

#credits

- Credits to [M Atif](https://github.com/atif0075) for porting this component.
- Ported from [Aceternity UI's Sparkles](https://ui.aceternity.com/components/sparkles).

::

---

### En 2.Components Backgrounds Stars Background (`content/en/2.components/backgrounds/stars-background.md`)

---
title: Stars Background
description: A parallax-animated starfield background using layered motion and randomized star positions.
category: Background
tags: [css, tailwind, background, animate-ui, motion-v]
---

::ComponentViewer{demoFile="StarsBackgroundDemo.vue" config="StarsBackgroundConfig" componentId="bg-stars" :componentFiles='["StarsBackground.vue"]'}

#api

## API

| Prop Name    | Type            | Default                          | Description                                                             |
| ------------ | --------------- | -------------------------------- | ----------------------------------------------------------------------- |
| `factor`     | `number`        | `0.05`                           | Multiplier for mouse parallax movement.                                 |
| `speed`      | `number`        | `50`                             | Base speed (in seconds) for vertical looping animation of star layers.  |
| `transition` | `SpringOptions` | `{ stiffness: 50, damping: 20 }` | Spring physics config for smooth motion response to cursor movement.    |
| `starColor`  | `string`        | `"#fff"`                         | Color of the stars. Accepts any valid CSS color value.                  |
| `class`      | `string`        | `—`                              | Optional additional classes for container div. Useful for z-index, etc. |

> 💡 This component wraps a slot for children, so you can place other UI elements over the background.

#credits

- Ported from [Animate UI](https://animate-ui.com/docs/backgrounds/stars)

::

---

### En 2.Components Backgrounds Stractium Background (`content/en/2.components/backgrounds/stractium-background.md`)

---
title: Stractium Background
description: A shader-based background inspired by intricate fractal patterns and organic textures, created using raymarching and GLSL. This effect is designed to simulate complex, evolving visual textures.
category: Background
tags: [css, tailwind, background, shader-toy, webgl, ogl]
---

::ComponentViewer{demoFile="StractiumBackgroundDemo.vue" config="StractiumBackgroundConfig" componentId="bg-stractium" :componentFiles='["StractiumBackground.vue"]'}

#api

## API

| Prop Name          | Type     | Default | Description                                                                 |
| ------------------ | -------- | ------- | --------------------------------------------------------------------------- |
| `hue`              | `number` | `0`     | Base hue for the fractal texture (0–360 degrees).                           |
| `saturation`       | `number` | `1`     | Saturation of the color (0–1).                                              |
| `brightness`       | `number` | `1`     | Brightness multiplier for the output color (0–2 recommended).               |
| `speed`            | `number` | `1`     | Speed multiplier for texture animation.                                     |
| `mouseSensitivity` | `number` | `0.5`   | Controls the responsiveness of the texture to mouse movement. (0–1)         |
| `damping`          | `number` | `1`     | Damping factor to control the smoothness of texture distortions. (0–1)      |
| `class`            | `string` | `—`     | Optional additional CSS classes for the container div (e.g., z-index, etc). |

> 💡 This component is designed to be used in full-screen or large section backgrounds. It is optimized for modern GPUs but may be demanding on lower-end devices.

#credits

- Based on a ShaderToy fragment shader by the original creator of the fractal patterns (MIT License).
- Embedded in a Vue component and adapted for dynamic input via props.
- Inspired by fractal patterns, natural textures, and advanced raymarching techniques.

::

---

### En 2.Components Backgrounds Tetris (`content/en/2.components/backgrounds/tetris.md`)

---
title: Tetris
description: Tetris background component, you can even click on a block to eliminate it.
category: Background
tags: [css, tailwind, background]
---

::ComponentViewer{demoFile="TetrisDemo.vue" config="TetrisConfig" componentId="tetris" :componentFiles='["Tetris.vue"]' dependencies="theme-colors"}

#api

## API

| Prop Name      | Type     | Default | Description                                    |
| -------------- | -------- | ------- | ---------------------------------------------- |
| `class`        | `string` | `""`    | Additional class names to style the component. |
| `base`         | `number` | `10`    | How many blocks do you have in a row.          |
| `square-color` | `string` | `""`    | Square color.                                  |

#credits

- Credits to [Whbbit1999](https://github.com/Whbbit1999) for this component.
- Inspired and ported from [Nuxt UI Home](https://ui2.nuxt.com/).

::

---

### En 2.Components Backgrounds Thunderstorm Background (`content/en/2.components/backgrounds/thunderstorm-background.md`)

---
title: Thunderstorm Background
description: A shader-based background inspired by thunderstorm in clouds.
category: Background
tags: [css, tailwind, background, shader-toy, webgl, ogl]
---

::ComponentViewer{demoFile="ThunderstormBackgroundDemo.vue" config="ThunderstormBackgroundConfig" componentId="bg-thunderstorm" :componentFiles='["ThunderstormBackground.vue"]'}

#api

## API

| Prop Name          | Type     | Default | Description                                                                 |
| ------------------ | -------- | ------- | --------------------------------------------------------------------------- |
| `hue`              | `number` | `0`     | Base hue for the fractal texture (0–360 degrees).                           |
| `saturation`       | `number` | `1`     | Saturation of the color (0–1).                                              |
| `brightness`       | `number` | `1`     | Brightness multiplier for the output color (0–2 recommended).               |
| `speed`            | `number` | `1`     | Speed multiplier for animation.                                             |
| `mouseSensitivity` | `number` | `0.5`   | Controls the responsiveness to mouse movement. (0–5)                        |
| `damping`          | `number` | `1`     | Damping factor to control the smoothness of texture distortions. (0–1)      |
| `class`            | `string` | `—`     | Optional additional CSS classes for the container div (e.g., z-index, etc). |

> 💡 This component is designed to be used in full-screen or large section backgrounds. It is optimized for modern GPUs but may be demanding on lower-end devices.

#credits

- Adapted from [this ShaderToy shader](https://www.shadertoy.com/view/W3d3z7).

::

---

### En 2.Components Backgrounds Video Text (`content/en/2.components/backgrounds/video-text.md`)

---
title: Video Text
description: A text component with a video background.
category: Background
tags: [css, tailwind, background, magic-ui]
---

::ComponentViewer{demoFile="VideoTextDemo.vue" config="VideoTextConfig" componentId="video-text" :componentFiles='["VideoText.vue"]'}

#api

## API

| Prop Name          | Type                             | Default        | Description                           |
| ------------------ | -------------------------------- | -------------- | ------------------------------------- |
| `src`              | `string`                         | `Required`     | The video source URL.                 |
| `class`            | `string`                         | `""`           | Additional classes for the container. |
| `autoPlay`         | `boolean`                        | `true`         | Whether to autoplay the video.        |
| `muted`            | `boolean`                        | `true`         | Whether to mute the video.            |
| `loop`             | `boolean`                        | `true`         | Whether to loop the video.            |
| `preload`          | `"auto" \| "metadata" \| "none"` | `"auto"`       | Whether to preload the video.         |
| `fontSize`         | `string \| number`               | `"120"`        | Font size for the text mask.          |
| `fontWeight`       | `string \| number`               | `"bold"`       | Font weight for the text mask.        |
| `textAnchor`       | `string`                         | `"middle"`     | Text anchor for the text mask.        |
| `dominantBaseline` | `string`                         | `"middle"`     | Dominant baseline for the text mask.  |
| `fontFamily`       | `string`                         | `"sans-serif"` | Font family for the text mask.        |

#credits

- Credits to [SivaReddy Uppathi](https://github.com/sivareddyuppathi) for this component.
- Ported from [Magic UI's Video Text](https://magicui.design/docs/components/video-text).

::

---

### En 2.Components Backgrounds Vortex (`content/en/2.components/backgrounds/vortex.md`)

---
title: Vortex Background
description: A wavy, swirly, vortex background ideal for CTAs and backgrounds.
category: Background
tags: [css, tailwind, background, aceternity-ui, motion-v, simplex-noise]
---

::ComponentViewer{demoFile="VortexDemo.vue" config="VortexConfig" componentId="vortex" :componentFiles='["Vortex.vue"]' dependencies="simplex-noise"}

#api

## API

| Prop Name         | Type     | Default     | Description                                          |
| ----------------- | -------- | ----------- | ---------------------------------------------------- |
| `class`           | `string` |             | Optional className for styling the children wrapper. |
| `containerClass`  | `string` |             | Optional className for styling the container.        |
| `particleCount`   | `number` | `700`       | Number of particles to be generated.                 |
| `rangeY`          | `number` | `100`       | Vertical range for particle movement.                |
| `baseHue`         | `number` | `220`       | Base hue for particle color.                         |
| `baseSpeed`       | `number` | `0.0`       | Base speed for particle movement.                    |
| `rangeSpeed`      | `number` | `1.5`       | Range of speed variation for particles.              |
| `baseRadius`      | `number` | `1`         | Base radius of particles.                            |
| `rangeRadius`     | `number` | `2`         | Range of radius variation for particles.             |
| `backgroundColor` | `string` | `"#000000"` | Background color of the canvas.                      |

#credits

- Credits to [Aceternity UI](https://ui.aceternity.com/components/vortex).
- Credits to [SivaReddy Uppathi](https://github.com/sivareddyuppathi) for porting this component.

::

---

### En 2.Components Backgrounds Warp Background (`content/en/2.components/backgrounds/warp-background.md`)

---
title: Warp Background
description: A container component that applies a warp animation effect to its children
category: Background
tags: [css, tailwind, background, magic-ui]
---

::ComponentViewer{demoFile="WarpBackgroundDemo.vue" config="WarpBackgroundConfig" componentId="warp-background" :componentFiles='["WarpBackground.vue", "Beam.vue"]'}

#api

## API

| Prop Name      | Type     | Default                | Description                               |
| -------------- | -------- | ---------------------- | ----------------------------------------- |
| `perspective`  | `number` | `100`                  | The perspective of the warp animation     |
| `beamsPerSide` | `number` | `3`                    | The number of beams per side              |
| `beamSize`     | `number` | `5`                    | The size of the beams                     |
| `beamDelayMax` | `number` | `3`                    | The maximum delay of the beams in seconds |
| `beamDelayMin` | `number` | `0`                    | The minimum delay of the beams in seconds |
| `beamDuration` | `number` | `3`                    | The duration of the beams                 |
| `gridColor`    | `string` | `"hsl(var(--border))"` | The color of the grid lines               |

#credits

- Credits to [Whbbit1999](https://github.com/Whbbit1999) for this component.
- Inspired and ported from [Magic UI WarpBackground](https://magicui.design/docs/components/warp-background).

::

---

### En 2.Components Backgrounds Wavy Background (`content/en/2.components/backgrounds/wavy-background.md`)

---
title: Wavy Background
description: A cool background effect with waves that move.
category: Background
tags: [css, tailwind, background, simplex-noise, aceternity-ui]
---

::ComponentViewer{demoFile="WavyBackgroundDemo.vue" config="WavyBackgroundConfig" componentId="wavy-background" :componentFiles='["WavyBackground.vue"]' dependencies="simplex-noise"}

#api

## API

| Prop Name        | Type               | Default                                                   | Description                                                |
| ---------------- | ------------------ | --------------------------------------------------------- | ---------------------------------------------------------- |
| `class`          | `string`           | `-`                                                       | The content to be displayed on top of the wavy background. |
| `containerClass` | `string`           | `-`                                                       | The CSS class to apply to the content container.           |
| `colors`         | `string[]`         | `["#38bdf8", "#818cf8", "#c084fc", "#e879f9", "#22d3ee"]` | The colors of the waves.                                   |
| `waveWidth`      | `number`           | `50`                                                      | The width of the waves.                                    |
| `backgroundFill` | `string`           | `"black"`                                                 | The background color.                                      |
| `blur`           | `number`           | `10`                                                      | The blur effect applied to the waves.                      |
| `speed`          | `"slow" \| "fast"` | `"fast"`                                                  | Range of speed variation for particles.                    |
| `waveOpacity`    | `number`           | `0.5`                                                     | Base radius of particles.                                  |
| `[key: string]`  | `any`              | `-`                                                       | Range of radius variation for particles.                   |

#credits

- Credits to [Aceternity UI](https://ui.aceternity.com/components/wavy-background).
- Credits to [SivaReddy Uppathi](https://github.com/sivareddyuppathi) for porting this component.

::

---

### En 2.Components Buttons Gradient Button (`content/en/2.components/buttons/gradient-button.md`)

---
title: Gradient Button
description: A stylish animated button with a rotating conic gradient border and customizable properties for a vibrant look.
category: Button
tags: [css, tailwind, button]
---

::ComponentViewer{demoFile="GradientButtonDemo.vue" config="GradientButtonConfig" componentId="gradient-button" :componentFiles='["GradientButton.vue"]'}

#api

## API

| Prop Name      | Type       | Default              | Description                                                  |
| -------------- | ---------- | -------------------- | ------------------------------------------------------------ |
| `borderWidth`  | `number`   | `2`                  | Width of the gradient border in pixels.                      |
| `colors`       | `string[]` | Rainbow Colors Array | Array of colors used in the conic gradient border.           |
| `duration`     | `number`   | `2500`               | Duration of the gradient rotation animation in milliseconds. |
| `borderRadius` | `number`   | `8`                  | Border radius for rounded corners in pixels.                 |
| `blur`         | `number`   | `4`                  | Blur intensity of the gradient border effect in pixels.      |
| `class`        | `string`   | `""`                 | Additional CSS classes for custom styling.                   |
| `bgColor`      | `string`   | `"#000"`             | Background color of the button content.                      |

::

---

### En 2.Components Buttons Interactive Hover Button (`content/en/2.components/buttons/interactive-hover-button.md`)

---
title: Interactive Hover Button
description: A visually engaging button component that responds to hover with dynamic transitions, adapting smoothly between light and dark modes for enhanced user interactivity.
category: Button
tags: [css, tailwind, button, magic-ui]
---

::ComponentViewer{demoFile="InteractiveHoverButtonDemo.vue" config="InteractiveHoverButtonConfig" componentId="interactive-hover-button" :componentFiles='["InteractiveHoverButton.vue"]'}

#api

## API

| Prop Name | Type     | Default  | Description                                    |
| --------- | -------- | -------- | ---------------------------------------------- |
| `text`    | `string` | `Button` | The text to be displayed inside the button.    |
| `class`   | `string` | `""`     | Additional class names to style the component. |

#credits

- Credits to [Whbbit1999](https://github.com/Whbbit1999) for this component.
- Inspired and ported from [Magic UI Interactive Hover Button](https://magicui.design/docs/components/interactive-hover-button).

::

---

### En 2.Components Buttons Rainbow Button (`content/en/2.components/buttons/rainbow-button.md`)

---
title: Rainbow Button
description: A rainbow effect on button.
category: Button
tags: [css, tailwind, button, magic-ui]
---

::ComponentViewer{demoFile="RainbowButtonDemo.vue" config="RainbowButtonConfig" componentId="rainbow-button" :componentFiles='["RainbowButton.vue"]'}

#api

## API

| Prop Name | Type     | Default    | Description                                    |
| --------- | -------- | ---------- | ---------------------------------------------- |
| `class`   | `string` | `""`       | Additional CSS classes to apply to the button. |
| `is`      | `string` | `"button"` | The HTML tag to render for the component.      |
| `speed`   | `number` | `2`        | Duration of the animation in seconds.          |

#credits

- Credits to [Grzegorz Krol](https://github.com/Grzechu335) for porting this component.
- Credits to [Magic UI](https://magicui.design/docs/components/rainbow-button).

::

---

### En 2.Components Buttons Ripple Button (`content/en/2.components/buttons/ripple-button.md`)

---
title: Ripple Button
description: A stylish ripple button component with customizable colors and animation duration.
category: Button
tags: [css, tailwind, button, magic-ui]
---

::ComponentViewer{demoFile="RippleButtonDemo.vue" config="RippleButtonConfig" componentId="ripple-button" :componentFiles='["RippleButton.vue"]'}

#api

## API

| Prop Name     | Type     | Default     | Description                                       |
| ------------- | -------- | ----------- | ------------------------------------------------- |
| `class`       | `string` | -           | Additional CSS classes for custom styling.        |
| `rippleColor` | `string` | `"#ADD8E6"` | Color of the ripple effect.                       |
| `duration`    | `number` | `600`       | Duration of the ripple animation in milliseconds. |

## Emits

| Event Name | Type    | Description |
| ---------- | ------- | ----------- |
| `click`    | `event` | Click event |

#credits

- Inspired by [Magic UI's Ripple Button](https://magicui.design/docs/components/ripple-button) component.
- Credits to [kalix127](https://github.com/kalix127) for porting this component.

::

---

### En 2.Components Buttons Shimmer Button (`content/en/2.components/buttons/shimmer-button.md`)

---
title: Shimmer Button
description: A button with a shimmering animated effect.
category: Button
tags: [css, tailwind, button, magic-ui]
---

::ComponentViewer{demoFile="ShimmerButtonDemo.vue" config="ShimmerButtonConfig" componentId="shimmer-button" :componentFiles='["ShimmerButton.vue"]'}

#api

## API

| Prop Name         | Type     | Default              | Description                                             |
| ----------------- | -------- | -------------------- | ------------------------------------------------------- |
| `class`           | `string` | `""`                 | Additional CSS classes to apply to the button.          |
| `shimmerColor`    | `string` | `"#ffffff"`          | Color of the shimmer effect.                            |
| `shimmerSize`     | `string` | `"0.05em"`           | Size of the shimmer effect.                             |
| `borderRadius`    | `string` | `"100px"`            | Border radius of the button.                            |
| `shimmerDuration` | `string` | `"3s"`               | Duration of the shimmer animation.                      |
| `background`      | `string` | `"rgba(0, 0, 0, 1)"` | Background color of the button. Can be rgb or hex code. |

#credits

- Ported from [Magic UI Shimmer Button](https://magicui.design/docs/components/shimmer-button).

::

---

### En 2.Components Cards 3d Card (`content/en/2.components/cards/3d-card.md`)

---
title: 3D Card Effect
description: A card perspective effect, hover over the card to elevate card elements.
category: Card
tags: [css, tailwind, card, aceternity-ui]
---

::ComponentViewer{demoFile="CardDemo.vue" config="Card3dConfig" componentId="card-3d" :componentFiles='["CardContainer.vue", "CardBody.vue", "CardItem.vue", "useMouseState.ts"]'}

#api

## API

### `CardContainer`

The `CardContainer` component serves as a wrapper for the 3D card effect. It manages mouse events to create a 3D perspective.

#### Props

| Prop Name        | Type   | Default | Description                                                 |
| ---------------- | ------ | ------- | ----------------------------------------------------------- |
| `class`          | string | `null`  | Additional classes for styling the inner container element. |
| `containerClass` | string | `null`  | Additional classes for styling the outer container element. |

---

### `CardBody`

The `CardBody` component is a flexible container with preserved 3D styling. It is intended to be used within a `CardContainer` to hold content with a 3D transformation effect.

#### Props

| Prop Name | Type   | Default | Description                            |
| --------- | ------ | ------- | -------------------------------------- |
| `class`   | string | `null`  | Additional classes for custom styling. |

---

### `CardItem`

The `CardItem` component represents individual items within the 3D card. It supports various transformations (translation and rotation) to create dynamic 3D effects.

#### Props

| Prop Name    | Type   | Default | Description                                                     |
| ------------ | ------ | ------- | --------------------------------------------------------------- |
| `as`         | string | `"div"` | The HTML tag or component to use for the item.                  |
| `class`      | string | `null`  | Additional classes for styling the item.                        |
| `translateX` | string | `0`     | X-axis translation in pixels.                                   |
| `translateY` | string | `0`     | Y-axis translation in pixels.                                   |
| `translateZ` | string | `0`     | Z-axis translation in pixels, used to control the depth effect. |
| `rotateX`    | string | `0`     | X-axis rotation in degrees.                                     |
| `rotateY`    | string | `0`     | Y-axis rotation in degrees.                                     |
| `rotateZ`    | string | `0`     | Z-axis rotation in degrees.                                     |

---

> 💡 **_Important Note:_**
>
> If you are using `CardItem` inside a `div`, add `style="transform-style: preserve-3d;"` to the div to make `translate-z` prop to work.

#credits

- Ported from Aceternity UI 3D Card Component.

::

---

### En 2.Components Cards Apple Card Carousel (`content/en/2.components/cards/apple-card-carousel.md`)

---
title: Apple Card Carousel
description: A sleek, Apple‑style card carousel with blur‑loading images, modal expansion, and smooth scrolling controls.
category: Card
tags: [css, tailwind, card, aceternity-ui]
---

::ComponentViewer{demoFile="AppleCardCarouselDemo.vue" config="AppleCardCarouselConfig" componentId="apple-card-carousel" :componentFiles='["AppleCardCarousel.vue", "AppleCarouselItem.vue", "AppleCard.vue", "AppleBlurImage.vue", "AppleCarouselContext.ts"]'}

#api

The **Apple Carousel** suite is composed of four inter‑related components:

| Component           | Purpose                                                                  |
| ------------------- | ------------------------------------------------------------------------ |
| `AppleCardCarousel` | The horizontal scroll container with left / right controls.              |
| `AppleCarouselItem` | A wrapper that adds enter‑animation and spacing to each card.            |
| `AppleCard`         | A richly styled, clickable card that can expand into a fullscreen modal. |
| `AppleBlurImage`    | An `<img>` replacement that starts blurred until the image loads.        |

Together they reproduce the interactive “App Store / Apple TV” browsing experience.

---

## `AppleCardCarousel`

| Prop            | Type     | Default | Description                                        |
| --------------- | -------- | ------- | -------------------------------------------------- |
| `initialScroll` | `number` | `0`     | Horizontal scroll offset applied on mount (in px). |

### Slots

The default slot should contain one or more **`AppleCarouselItem`** components.

### Emits

_No custom events._

---

## `AppleCarouselItem`

| Prop    | Type     | Required | Description                                             |
| ------- | -------- | -------- | ------------------------------------------------------- |
| `index` | `number` | ✓        | Zero‑based index; used to stagger the appear animation. |

### Slots

Default slot — place an **`AppleCard`** here.

---

## `AppleCard`

| Prop     | Type                                               | Required | Default | Description                           |
| -------- | -------------------------------------------------- | -------- | ------- | ------------------------------------- |
| `card`   | `{ src: string; title: string; category: string }` | ✓        | —       | Data object for the card.             |
| `index`  | `number`                                           | ✓        | —       | Position within the carousel.         |
| `layout` | `boolean`                                          | ✕        | `false` | Enables shared‑layout FLIP animation. |

### Slots

When the card is **expanded** (modal open) the default slot renders inside the modal body; you can inject extended content such as text, images, or videos.

### Emits

_No custom events (relies on injected `CarouselKey` context)._

---

## `AppleBlurImage`

| Prop     | Type               | Default                          | Description                                                    |
| -------- | ------------------ | -------------------------------- | -------------------------------------------------------------- |
| `src`    | `string`           | **—**                            | Image source URL. _Required._                                  |
| `alt`    | `string`           | "Background of a beautiful view" | Alt text.                                                      |
| `width`  | `number \| string` | _img natural_                    | Width attribute; omitted when using `fill`.                    |
| `height` | `number \| string` | _img natural_                    | Height attribute; omitted when using `fill`.                   |
| `fill`   | `boolean`          | `false`                          | If `true`, sets `width:100%; height:100%` via utility classes. |
| `class`  | `string`           | `""`                             | Additional classes merged via `cn()`.                          |

When the image fires the native `load` event it gracefully transitions from `blur-sm` to no‑blur.

---

#credits

- Ported from [Aceternity UI Apple Card Carousel](https://ui.aceternity.com/components/apple-cards-carousel).

::

---

### En 2.Components Cards Card Spotlight (`content/en/2.components/cards/card-spotlight.md`)

---
title: Card Spotlight
description: A card component with a dynamic spotlight effect that follows the mouse cursor, enhancing visual interactivity.
category: Card
tags: [css, tailwind, card, magic-ui]
---

::ComponentViewer{demoFile="CardSpotlightDemo.vue" config="CardSpotlightConfig" componentId="card-spotlight" :componentFiles='["CardSpotlight.vue"]'}

#api

## API

| Prop Name         | Type     | Default     | Description                                                 |
| ----------------- | -------- | ----------- | ----------------------------------------------------------- |
| `gradientSize`    | `number` | `200`       | Radius in pixels of the spotlight effect.                   |
| `gradientColor`   | `string` | `'#262626'` | The color of the spotlight gradient.                        |
| `gradientOpacity` | `number` | `0.8`       | The opacity level of the spotlight gradient effect.         |
| `slotClass`       | `string` | `undefined` | Class to apply to the parent container containing the slot. |

#credits

- Inspired by Magic Card component from [Magic UI](https://magicui.design/docs/components/magic-card).

::

---

### En 2.Components Cards Card Stack (`content/en/2.components/cards/card-stack.md`)

---
title: Card Stack
description: Layer cards as they scale into a focused stack while the user scrolls.
category: Card
tags: [css, tailwind, motion-v, scroll]
badge: New
---

::ComponentViewer{demoFile="CardStackDemo.vue" config="CardStackConfig" componentId="card-stack" :componentFiles='["CardStack.vue", "CardStackItem.vue", "CardStackContext.ts", "index.ts"]'}

#api

## API

### CardStack

| Prop Name         | Type               | Default                                  | Description                                                   |
| ----------------- | ------------------ | ---------------------------------------- | ------------------------------------------------------------- |
| `totalCards`      | `number`           | —                                        | Total cards used to calculate the stack scale.                |
| `scaleMultiplier` | `number`           | `0.03`                                   | Amount each card scales as it moves through the scroll range. |
| `scrollOptions`   | `UseScrollOptions` | `{ offset: ["start start", "end end"] }` | Motion scroll options, including an optional container.       |
| `class`           | `string`           | `-`                                      | Additional classes applied to the stack container.            |

### CardStackItem

| Prop Name     | Type     | Default          | Description                                       |
| ------------- | -------- | ---------------- | ------------------------------------------------- |
| `index`       | `number` | —                | Zero-based card index used for scale calculation. |
| `topPosition` | `string` | `5 + index * 3%` | Sticky top offset for the card.                   |
| `class`       | `string` | `-`              | Additional classes applied to the card wrapper.   |

## Usage

Use `CardStack` as the parent and place one `CardStackItem` around each card. Give each item a height so the sticky scroll range has room to progress.

```vue
<script setup lang="ts">
import { CardStack, CardStackItem } from "@/components/inspira/ui/card-stack";

const cards = ["First", "Second", "Third"];
</script>

<template>
  <CardStack :total-cards="cards.length">
    <CardStackItem
      v-for="(card, index) in cards"
      :key="card"
      :index="index"
      class="h-dvh"
    >
      <div class="h-[80%]">{{ card }}</div>
    </CardStackItem>
  </CardStack>
</template>
```

#credits

- Ported from [Fancy Components](https://fancycomponents.dev/docs/components/blocks/stacking-cards).

::

---

### En 2.Components Cards Cube Carousel (`content/en/2.components/cards/cube-carousel.md`)

---
title: Cube Carousel
description: A draggable four-face 3D carousel for cycling through images and videos.
category: Card
tags: [css, tailwind, motion-v, carousel, 3d]
badge: New
---

::ComponentViewer{demoFile="CubeCarouselDemo.vue" config="CubeCarouselConfig" componentId="cube-carousel" :componentFiles='["CubeCarousel.vue", "index.ts"]'}

#api

## API

### `CubeCarousel`

| Prop Name          | Type                                     | Default                                           | Description                                                   |
| ------------------ | ---------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------- |
| `items`            | `CubeCarouselItem[]`                     | —                                                 | Four or more image or video items to place on the cube faces. |
| `width`            | `number`                                 | —                                                 | Width of each face in pixels.                                 |
| `height`           | `number`                                 | —                                                 | Height of each face in pixels.                                |
| `class`            | `string`                                 | —                                                 | Additional classes for the carousel root.                     |
| `debug`            | `boolean`                                | `false`                                           | Shows face colors and item IDs for inspecting the cube.       |
| `perspective`      | `number`                                 | `600`                                             | CSS perspective distance in pixels.                           |
| `direction`        | `"top" \| "bottom" \| "left" \| "right"` | `"left"`                                          | Rotation axis and direction.                                  |
| `transition`       | `Record<string, unknown>`                | `{ duration: 1.25, ease: [...] }`                 | Motion transition used for button and keyboard rotations.     |
| `snapTransition`   | `Record<string, unknown>`                | `{ type: "spring", damping: 30, stiffness: 200 }` | Transition used when drag snaps to a face.                    |
| `dragSpring`       | `CubeCarouselSpringConfig`               | `{ stiffness: 200, damping: 30 }`                 | Spring used while following pointer drag.                     |
| `autoPlay`         | `boolean`                                | `false`                                           | Automatically advances through the items.                     |
| `autoPlayInterval` | `number`                                 | `3000`                                            | Delay between autoplay rotations in milliseconds.             |
| `onIndexChange`    | `(index: number) => void`                | —                                                 | Called after a rotation finishes.                             |
| `enableDrag`       | `boolean`                                | `true`                                            | Enables pointer and touch drag interaction.                   |
| `dragSensitivity`  | `number`                                 | `0.5`                                             | Rotation amount produced by pointer movement.                 |

### `CubeCarouselItem`

| Property | Type                 | Required | Description                       |
| -------- | -------------------- | -------- | --------------------------------- |
| `id`     | `string`             | Yes      | Stable identifier for the item.   |
| `type`   | `"image" \| "video"` | Yes      | Selects the media renderer.       |
| `src`    | `string`             | Yes      | Image or video source URL.        |
| `alt`    | `string`             | No       | Alternative text for image items. |
| `poster` | `string`             | No       | Poster image URL for video items. |

## Interaction

Drag along the carousel axis to rotate it. Release to snap to the nearest quarter-turn. When the carousel is focused, use the arrow keys matching its axis. The exposed `next`, `prev`, and `getCurrentItemIndex` methods can also control it from a parent component.

```vue
<script setup lang="ts">
import { ref } from "vue";
import CubeCarousel, {
  type CubeCarouselRef,
} from "@/components/inspira/ui/cube-carousel/CubeCarousel.vue";

const carousel = ref<CubeCarouselRef | null>(null);
</script>

<template>
  <CubeCarousel
    ref="carousel"
    :items="items"
    :width="400"
    :height="300"
    direction="right"
  />
  <button @click="carousel?.prev()">Previous</button>
  <button @click="carousel?.next()">Next</button>
</template>
```

#credits

- Ported from [Fancy Components Box Carousel](https://fancycomponents.dev/docs/components/carousel/box-carousel).
- Demo artwork by [Daniel Petho](https://www.cosmos.so/danielpetho/box-carousel-demo).
- Inspired by [Framer University](https://framer.university/resources/3d-box-carousel-in-framer).

::

---

### En 2.Components Cards Direction Aware Hover (`content/en/2.components/cards/direction-aware-hover.md`)

---
title: Direction Aware Hover Card
description: A direction aware hover card, that displays an image with dynamic hover effects and customizable content overlay.
category: Card
tags: [css, tailwind, card, aceternity-ui]
---

::ComponentViewer{demoFile="DirectionAwareHoverDemo.vue" config="DirectionAwareHoverConfig" componentId="direction-aware-hover" :componentFiles='["DirectionAwareHover.vue"]'}

#api

## API

| Prop Name       | Type     | Default     | Description                                     |
| --------------- | -------- | ----------- | ----------------------------------------------- |
| `imageUrl`      | `string` | Required    | The URL of the image to be displayed.           |
| `class`         | `string` | `undefined` | Additional CSS classes for the card container.  |
| `imageClass`    | `string` | `undefined` | Additional CSS classes for the image element.   |
| `childrenClass` | `string` | `undefined` | Additional CSS classes for the content overlay. |

#credits

- Credits to [M Atif](https://github.com/atif0075) for porting this component.
- Ported from [Aceternity UI's Direction Aware Hover](https://ui.aceternity.com/components/direction-aware-hover)

::

---

### En 2.Components Cards Fey Cards (`content/en/2.components/cards/fey-cards.md`)

---
title: Fey Cards
description: An animated hover card stack with layered image swapping and a cinematic heading reveal.
category: Card
tags: [css, tailwind, card, aceternity-ui]
---

::ComponentViewer{demoFile="FeyCardsDemo.vue" config="FeyCardsConfig" componentId="fey-cards" :componentFiles='["FeyCards.vue"]'}

#api

## API

| Prop Name         | Type           | Default                                                | Description                                                        |
| ----------------- | -------------- | ------------------------------------------------------ | ------------------------------------------------------------------ |
| `imgSrc`          | `string[]`     | `[]`                                                   | Array of image sources used for the stacked cards.                 |
| `mainImg`         | `string`       | `-`                                                    | Main image shown behind the card stack.                            |
| `idleImg`         | `string`       | `-`                                                    | Idle image shown before the hovered swap effect.                   |
| `cardSpacing`     | `number`       | `32`                                                   | Horizontal spacing between stacked cards.                          |
| `spring`          | `SpringConfig` | `{ type: "spring", visualDuration: 0.5, bounce: 0.2 }` | Motion spring configuration for the entrance and shift animations. |
| `shiftDistance`   | `number`       | `60`                                                   | Distance cards move horizontally when a hover state is active.     |
| `swapDuration`    | `number`       | `0.5`                                                  | Duration of the image swap transition in seconds.                  |
| `entranceStagger` | `number`       | `0.2`                                                  | Delay between the entrance animations of each card.                |
| `class`           | `string`       | `-`                                                    | Additional Tailwind classes applied to the wrapper.                |

#credits

- Inspired by [Aceternity UI](https://ui.aceternity.com/labs/fey-card).

::

---

### En 2.Components Cards Flip Card (`content/en/2.components/cards/flip-card.md`)

---
title: Flip Card
description: A dynamic flip card with smooth 180-degree flipping animations along both the X and Y axes, providing an engaging and interactive visual effect.
category: Card
tags: [css, tailwind, card]
---

::ComponentViewer{demoFile="FlipCardDemo.vue" config="FlipCardConfig" componentId="flip-card" :componentFiles='["FlipCard.vue"]'}

#api

## API

| Prop Name | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `class`   | `string` | `-`     | The class to be applied to the component.  |
| `rotate`  | `x \| y` | `y`     | You can pass the rotate value as you want. |

| Slot Name | Description                 |
| --------- | --------------------------- |
| `default` | Component to show as front. |
| `back`    | Component to show as back.  |

#credits

- Credits to [SivaReddy Uppathi](https://github.com/sivareddyuppathi) for this component.

::

---

### En 2.Components Cards Floating Card (`content/en/2.components/cards/floating-card.md`)

---
title: Floating Card
description: A perspective, 3D, Tilt card as seen on Perplexity Comet's website.
category: Card
tags: [css, tailwind, card, motion, 3D, aceternity-ui]
---

::ComponentViewer{demoFile="FloatingCardDemo.vue" config="FloatingCardConfig" componentId="floating-card" :componentFiles='["FloatingCard.vue"]'}

#api

## API

| Prop Name        | Type     | Default | Description                                             |
| ---------------- | -------- | ------- | ------------------------------------------------------- |
| `rotateDepth`    | `number` | `17.5`  | Maximum X/Y rotation applied while the card is hovered. |
| `translateDepth` | `number` | `20`    | Maximum X/Y translation applied while tracking cursor.  |
| `class`          | `string` | `-`     | Additional Tailwind classes applied to the wrapper.     |

#credits

- Inspired by [Aceternity UI](https://ui.aceternity.com/components/comet-card).

::

---

### En 2.Components Cards Glare Card (`content/en/2.components/cards/glare-card.md`)

---
title: Glare Card
description: A glare effect that happens on hover, as seen on Linear's website.
category: Card
tags: [css, tailwind, card, aceternity-ui]
---

::ComponentViewer{demoFile="GlareCardDemo.vue" config="GlareCardConfig" componentId="glare-card" :componentFiles='["GlareCard.vue"]'}

#api

## API

| Prop Name | Type     | Default | Description                                               |
| --------- | -------- | ------- | --------------------------------------------------------- |
| `class`   | `string` | `-`     | Additional Tailwind CSS class names to apply to the card. |

#credits

- Credits to [SivaReddy Uppathi](https://github.com/sivareddyuppathi) for this component.
- Inspired from [Aceternity UI](https://ui.aceternity.com/components/glare-card).

::

---

### En 2.Components Cursors Fluid Cursor (`content/en/2.components/cursors/fluid-cursor.md`)

---
title: Fluid Cursor
description: A GPU-accelerated animated cursor trail that simulates fluid motion.
category: Cursor
tags: [css, tailwind, cursor, webgl, cursify]
---

::ComponentViewer{demoFile="FluidCursorDemo.vue" config="FluidCursorConfig" componentId="fluid-cursor" :componentFiles='["FluidCursor.vue"]'}

#api

## API

| Prop Name             | Type      | Default                  | Description                                                                        |
| --------------------- | --------- | ------------------------ | ---------------------------------------------------------------------------------- |
| `simResolution`       | `number`  | `128`                    | Resolution for the simulation grid affecting fluid detail and performance.         |
| `dyeResolution`       | `number`  | `1440`                   | Resolution for the fluid dye (color) texture.                                      |
| `captureResolution`   | `number`  | `512`                    | Resolution for capturing input events.                                             |
| `densityDissipation`  | `number`  | `3.5`                    | Rate at which color density dissipates over time.                                  |
| `velocityDissipation` | `number`  | `2`                      | Rate at which velocity dissipates over time, affecting fluid momentum persistence. |
| `pressure`            | `number`  | `0.1`                    | Pressure factor used in fluid physics calculations.                                |
| `pressureIterations`  | `number`  | `20`                     | Number of iterations for pressure solver accuracy.                                 |
| `curl`                | `number`  | `3`                      | Intensity of curl/vorticity effect to enhance swirling motions.                    |
| `splatRadius`         | `number`  | `0.2`                    | Radius of the pointer's splat effect in the fluid.                                 |
| `splatForce`          | `number`  | `6000`                   | Force applied by the pointer to the fluid on interaction.                          |
| `shading`             | `boolean` | `true`                   | Enable or disable shading effects for depth and light on fluid colors.             |
| `colorUpdateSpeed`    | `number`  | `10`                     | Speed at which pointer colors update dynamically.                                  |
| `backColor`           | `object`  | `{ r: 0.5, g: 0, b: 0 }` | Background color of the fluid in RGB format.                                       |
| `transparent`         | `boolean` | `true`                   | Whether the canvas background is transparent.                                      |
| `class`               | `string`  | `undefined`              | Additional CSS classes for the outer container div.                                |

#credits

- Inspired from [Fluid Cursor by Cursify](https://cursify.vercel.app/components/fluid-cursor)
- Utilizes WebGL 1/2 context and custom GLSL shaders for fluid physics and rendering.

::

---

### En 2.Components Cursors Image Trail Cursor (`content/en/2.components/cursors/image-trail-cursor.md`)

---
title: Image Trail Cursor
description: An interactive cursor effect that creates a dynamic trail of images following mouse movement with multiple animation variants.
category: Cursor
tags: [css, tailwind, cursor, codrops, gsap]
---

::ComponentViewer{demoFile="ImageTrailCursorDemo.vue" config="ImageTrailCursorConfig" componentId="image-trail-cursor" :componentFiles='["ImageTrailCursor.vue", "trail-variants.ts"]' dependencies="gsap"}

#api

## API

| Prop Name | Type          | Default   | Description                                            |
| --------- | ------------- | --------- | ------------------------------------------------------ |
| `images`  | `string[]`    | `[]`      | Array of image URLs to display in the trailing effect. |
| `variant` | `VariantType` | `"type1"` | Animation variant type (`"type1"` through `"type7"`).  |

> 💡 This component creates a full-width, full-height container with high z-index for cursor tracking. Each image is 190px wide with a 1.1 aspect ratio and rounded corners.

#credits

- Inspired by modern cursor trail effects and image hover interactions.
- Built with Vue 3 Composition API for optimal reactivity and performance.
- Ported from [Codrops Article](https://tympanus.net/codrops/2023/10/18/ideas-for-image-motion-trail-animations/)

::

---

### En 2.Components Cursors Sleek Line Cursor (`content/en/2.components/cursors/sleek-line-cursor.md`)

---
title: Sleek Line Cursor
description: A reactive animated cursor trail with smooth wave-like motion, using spring physics and dynamic color waves.
category: Cursor
tags: [css, tailwind, cursor, webgl, cursify]
---

::ComponentViewer{demoFile="SleekLineCursorDemo.vue" config="SleekLineCursorConfig" componentId="sleek-line-cursor" :componentFiles='["SleekLineCursor.vue"]'}

## API

| Prop Name   | Type                 | Default     | Description                                                               |
| ----------- | -------------------- | ----------- | ------------------------------------------------------------------------- |
| `class`     | `string \| string[]` | `undefined` | Additional CSS classes for the canvas container element.                  |
| `trails`    | `number`             | `20`        | Number of trailing lines rendered behind the cursor.                      |
| `size`      | `number`             | `50`        | Number of spring-connected nodes per trail.                               |
| `friction`  | `number`             | `0.5`       | Global friction applied to velocity.                                      |
| `dampening` | `number`             | `0.25`      | Velocity damping applied between connected nodes.                         |
| `tension`   | `number`             | `0.98`      | Reduces spring intensity across the tail, giving a fluid tapering motion. |

> 💡 This component uses `pointer-events-none` and is fixed fullscreen by default. You can extend or override its styling via the `class` prop.

#credits

- Ported from [Canvas Cursor by Cursify](https://cursify.vercel.app/components/canvas-cursor).

::

---

### En 2.Components Cursors Smooth Cursor (`content/en/2.components/cursors/smooth-cursor.md`)

---
title: Smooth Cursor
description: A customizable, physics-based smooth cursor animation component for Vue applications.
category: Cursor
tags: [css, tailwind, cursor, magic-ui]
---

::ComponentViewer{demoFile="SmoothCursorDemo.vue" config="SmoothCursorConfig" componentId="smooth-cursor" :componentFiles='["SmoothCursor.vue"]'}

#api

## API

| Prop Name      | Type           | Default         | Description                                             |
| -------------- | -------------- | --------------- | ------------------------------------------------------- |
| `cursor`       | `Component`    | `DefaultCursor` | Custom cursor component to replace the default cursor   |
| `springConfig` | `SpringConfig` | `See below`     | Configuration object for the spring animation behavior. |

### SpringConfig Type

```ts
interface springConfig {
  damping: number;
  stiffness: number;
  mass: number;
  restDelta: number;
}
```

#credits

- Credits to [Whbbit1999](https://github.com/Whbbit1999) for this component.
- Ported from [Magic UI Smooth Cursor](https://magicui.design/docs/components/smooth-cursor).

::

---

### En 2.Components Cursors Tailed Cursor (`content/en/2.components/cursors/tailed-cursor.md`)

---
title: Tailed Cursor
description: A smooth, colorful ribbon cursor trail rendered with WebGL using OGL, featuring dynamic shaders and customizable animation effects.
category: Cursor
tags: [css, tailwind, cursor, webgl, codrops]
---

::ComponentViewer{demoFile="TailedCursorDemo.vue" config="TailedCursorConfig" componentId="tailed-cursor" :componentFiles='["TailedCursor.vue"]' dependencies="ogl"}

#api

## API

| Prop Name            | Type       | Default                                        | Description                                                  |
| -------------------- | ---------- | ---------------------------------------------- | ------------------------------------------------------------ |
| `colors`             | `string[]` | `["#ff9346", "#7cff67", "#ffee51", "#00d8ff"]` | Array of colors for each tail ribbon.                        |
| `baseSpring`         | `number`   | `0.03`                                         | Spring strength for tail movement responsiveness.            |
| `baseFriction`       | `number`   | `0.9`                                          | Friction factor slowing down the tail movement.              |
| `baseThickness`      | `number`   | `30`                                           | Base thickness of the tail ribbons.                          |
| `offsetFactor`       | `number`   | `0.05`                                         | Horizontal offset factor between each ribbon line.           |
| `maxAge`             | `number`   | `500`                                          | Maximum age for tail segments controlling their fade timing. |
| `pointCount`         | `number`   | `50`                                           | Number of points composing each ribbon tail.                 |
| `speedMultiplier`    | `number`   | `0.6`                                          | Speed multiplier controlling the animation speed.            |
| `enableFade`         | `boolean`  | `false`                                        | Enables fading effect on tail edges.                         |
| `enableShaderEffect` | `boolean`  | `false`                                        | Enables dynamic shader wave effect on ribbons.               |
| `effectAmplitude`    | `number`   | `2`                                            | Amplitude of the shader wave effect when enabled.            |
| `backgroundColor`    | `number[]` | `[0, 0, 0, 0]`                                 | RGBA background clear color for the WebGL canvas.            |

#credits

- Built with [OGL](https://github.com/oframe/ogl), a lightweight WebGL framework.
- Inspired from [Codrops Article](https://tympanus.net/codrops/2019/09/24/crafting-stylised-mouse-trails-with-ogl/)

::

---

### En 2.Components Device Mocks Iphone Mockup (`content/en/2.components/device-mocks/iphone-mockup.md`)

---
title: iPhone Mockup
description: An SVG mockup of an iPhone.
category: Device Mockup
tags: [css, tailwind, device-mockup, magic-ui]
---

::ComponentViewer{demoFile="iPhone15ProMockupDemo.vue" config="iPhone15ProMockupConfig" componentId="iphone-mockup" :componentFiles='["iPhone15ProMockup.vue"]'}

#api

## API

| Prop Name | Type     | Default | Description                                    |
| --------- | -------- | ------- | ---------------------------------------------- |
| `width`   | `number` | `433`   | Width of the mockup SVG in pixels.             |
| `height`  | `number` | `882`   | Height of the mockup SVG in pixels.            |
| `src`     | `string` | `null`  | URL of the image to display inside the mockup. |

#credits

- Ported from [Magic UI](https://magicui.design/docs/components/iphone-15-pro).

::

---

### En 2.Components Device Mocks Safari Mockup (`content/en/2.components/device-mocks/safari-mockup.md`)

---
title: Safari Mockup
description: An SVG mockup of the Safari browser.
category: Device Mockup
tags: [css, tailwind, device-mockup, magic-ui]
---

::ComponentViewer{demoFile="SafariMockupDemo.vue" config="SafariMockupConfig" componentId="safari-mockup" :componentFiles='["SafariMockup.vue"]'}

#api

## API

| Prop Name | Type     | Default | Description                                    |
| --------- | -------- | ------- | ---------------------------------------------- |
| `url`     | `string` | `null`  | URL displayed in the mockup's address bar.     |
| `src`     | `string` | `null`  | URL of the image to display inside the mockup. |
| `width`   | `number` | `1203`  | Width of the mockup SVG in pixels.             |
| `height`  | `number` | `753`   | Height of the mockup SVG in pixels.            |

#credits

- Ported from [Magic UI](https://magicui.design/docs/components/safari).

::

---

### En 2.Components Html In Canvas Html Ascii (`content/en/2.components/html-in-canvas/html-ascii.md`)

---
title: HTML ASCII
description: Rebuild live HTML with luminance-matched bitmap glyphs.
category: HTML in Canvas
tags: [webgl, shader, canvas, ascii, typography]
badge: New
dependencies: []
---

::ComponentViewer{demoFile="HtmlAsciiDemo.vue" config="HtmlAsciiConfig" componentId="html-ascii" :componentFiles='["HtmlAscii.vue"]'}

Press the surface to switch the glyph output to monochrome.

#api

## API

| Prop         | Type      | Default | Description                                          |
| ------------ | --------- | ------- | ---------------------------------------------------- |
| `cellSize`   | `number`  | `8`     | Glyph cell size in pixels. Values below `5` use `5`. |
| `frameRate`  | `number`  | `60`    | Maximum render frequency.                            |
| `pixelRatio` | `number`  | `1`     | Render scale, clamped between `0.25` and `2`.        |
| `paused`     | `boolean` | `false` | Pauses the render loop.                              |
| `autoPause`  | `boolean` | `true`  | Pauses while off-screen or the document is hidden.   |
| `class`      | `string`  | —       | Additional classes merged onto the surface element.  |

### Slots

| Slot      | Description                               |
| --------- | ----------------------------------------- |
| `default` | HTML content rendered through the effect. |

#credits

- Bitmap character technique adapted from [movAX13h](https://www.shadertoy.com/user/movAX13h).

::

---

### En 2.Components Html In Canvas Html Blaze (`content/en/2.components/html-in-canvas/html-blaze.md`)

---
title: HTML Blaze
description: Distort live HTML with rising heat, smoke, sparks, and flame light.
category: HTML in Canvas
tags: [webgl, shader, canvas, fire, animation]
badge: New
dependencies: []
---

::ComponentViewer{demoFile="HtmlBlazeDemo.vue" config="HtmlBlazeConfig" componentId="html-blaze" :componentFiles='["HtmlBlaze.vue"]'}

#api

## API

| Prop         | Type      | Default | Description                                         |
| ------------ | --------- | ------- | --------------------------------------------------- |
| `strength`   | `number`  | `0.03`  | Amount of heat displacement.                        |
| `scale`      | `number`  | `6`     | Scale of the flame noise field.                     |
| `speed`      | `number`  | `1`     | Animation speed of the fire.                        |
| `frameRate`  | `number`  | `60`    | Maximum render frequency.                           |
| `pixelRatio` | `number`  | `1`     | Render scale, clamped between `0.25` and `2`.       |
| `paused`     | `boolean` | `false` | Pauses the render loop.                             |
| `autoPause`  | `boolean` | `true`  | Pauses while off-screen or the document is hidden.  |
| `class`      | `string`  | —       | Additional classes merged onto the surface element. |

### Slots

| Slot      | Description                               |
| --------- | ----------------------------------------- |
| `default` | HTML content rendered through the effect. |

#credits

- Uses the MIT-licensed Simplex Noise implementation by [Ashima Arts](https://github.com/ashima/webgl-noise).

::

---

### En 2.Components Html In Canvas Html Chromatic (`content/en/2.components/html-in-canvas/html-chromatic.md`)

---
title: HTML Chromatic
description: Split the color channels of live HTML based on pointer position.
category: HTML in Canvas
tags: [webgl, shader, canvas, chromatic, interactive]
badge: New
dependencies: []
---

::ComponentViewer{demoFile="HtmlChromaticDemo.vue" config="HtmlChromaticConfig" componentId="html-chromatic" :componentFiles='["HtmlChromatic.vue"]'}

#api

## API

| Prop           | Type      | Default | Description                                         |
| -------------- | --------- | ------- | --------------------------------------------------- |
| `strength`     | `number`  | `0.03`  | Maximum red and blue channel separation.            |
| `mouseDamping` | `number`  | `0.9`   | Smoothing applied to pointer movement.              |
| `frameRate`    | `number`  | `60`    | Maximum render frequency.                           |
| `pixelRatio`   | `number`  | `1`     | Render scale, clamped between `0.25` and `2`.       |
| `paused`       | `boolean` | `false` | Pauses the render loop.                             |
| `autoPause`    | `boolean` | `true`  | Pauses while off-screen or the document is hidden.  |
| `class`        | `string`  | —       | Additional classes merged onto the surface element. |

### Slots

| Slot      | Description                               |
| --------- | ----------------------------------------- |
| `default` | HTML content rendered through the effect. |

::

---

### En 2.Components Html In Canvas Html Cloth (`content/en/2.components/html-in-canvas/html-cloth.md`)

---
title: HTML Cloth
description: Fold live HTML through a continuously moving fabric-like vector field.
category: HTML in Canvas
tags: [webgl, shader, canvas, cloth, animation]
badge: New
dependencies: []
---

::ComponentViewer{demoFile="HtmlClothDemo.vue" config="HtmlClothConfig" componentId="html-cloth" :componentFiles='["HtmlCloth.vue"]'}

#api

## API

| Prop         | Type      | Default | Description                                         |
| ------------ | --------- | ------- | --------------------------------------------------- |
| `strength`   | `number`  | `0.03`  | Amount of vector-field displacement.                |
| `scale`      | `number`  | `6`     | Scale of the cloth field.                           |
| `speed`      | `number`  | `1`     | Animation speed of the field.                       |
| `frameRate`  | `number`  | `60`    | Maximum render frequency.                           |
| `pixelRatio` | `number`  | `1`     | Render scale, clamped between `0.25` and `2`.       |
| `paused`     | `boolean` | `false` | Pauses the render loop.                             |
| `autoPause`  | `boolean` | `true`  | Pauses while off-screen or the document is hidden.  |
| `class`      | `string`  | —       | Additional classes merged onto the surface element. |

### Slots

| Slot      | Description                               |
| --------- | ----------------------------------------- |
| `default` | HTML content rendered through the effect. |

#credits

- Vector field based on the work of [MartinRGB](https://www.shadertoy.com/view/DttSRB).

::

---

### En 2.Components Html In Canvas Html Drag (`content/en/2.components/html-in-canvas/html-drag.md`)

---
title: HTML Drag
description: Bend live HTML with scroll velocity and pressed pointer movement.
category: HTML in Canvas
tags: [webgl, shader, canvas, scroll, interactive]
badge: New
dependencies: []
---

::ComponentViewer{demoFile="HtmlDragDemo.vue" config="HtmlDragConfig" componentId="html-drag" :componentFiles='["HtmlDrag.vue"]'}

Scroll over the surface to bend its segmented WebGL plane. Enable `mouseEnabled` to add press-and-drag deformation; leave it disabled to keep the HTML selectable.

#api

## API

| Prop           | Type      | Default | Description                                                   |
| -------------- | --------- | ------- | ------------------------------------------------------------- |
| `strength`     | `number`  | `1.25`  | Amount of vertical surface bending.                           |
| `mouseDamping` | `number`  | `0.9`   | Smoothing applied to pointer movement.                        |
| `mouseEnabled` | `boolean` | `false` | Enables press-and-drag deformation and blocks text selection. |
| `frameRate`    | `number`  | `60`    | Maximum render frequency.                                     |
| `pixelRatio`   | `number`  | `1`     | Render scale, clamped between `0.25` and `2`.                 |
| `paused`       | `boolean` | `false` | Pauses the render loop.                                       |
| `autoPause`    | `boolean` | `true`  | Pauses while off-screen or the document is hidden.            |
| `class`        | `string`  | —       | Additional classes merged onto the surface element.           |

### Slots

| Slot      | Description                               |
| --------- | ----------------------------------------- |
| `default` | HTML content rendered through the effect. |

::

---

### En 2.Components Html In Canvas Html In Canvas (`content/en/2.components/html-in-canvas/html-in-canvas.md`)

---
title: HTML in Canvas
description: Apply a ShaderToy-style fragment shader to live HTML content through the experimental HTML-in-Canvas API.
category: HTML in Canvas
tags: [webgl, shader, canvas, interactive]
badge: New
dependencies: []
---

::ComponentViewer{demoFile="HtmlInCanvasDemo.vue" config="HtmlInCanvasConfig" componentId="html-in-canvas" :componentFiles='["HtmlInCanvas.vue", "HtmlInCanvasRenderer.ts", "captureElement.ts", "index.ts"]'}

HTML in Canvas is an experimental browser API. When it is unavailable, the component captures a styled DOM snapshot and passes it through the same WebGL shader. The original DOM remains available for interaction and accessibility.

Your fragment shader must define `mainImage(out vec4 fragColor, in vec2 fragCoord)`. The captured HTML is available through `iChannel0`.

Use `HtmlLiquid`, `HtmlChromatic`, `HtmlAscii`, `HtmlCloth`, `HtmlBlaze`, or `HtmlDrag` when you want a focused, typed effect. Each component delegates rendering and fallback behavior to this shared renderer.

Pass `vertexShaderCode` when the effect also needs vertex-stage logic. It must define `main()` without a `#version` directive. The segmented surface exposes built-in `vec2 position` and `vec2 textureCoord` attributes, and the same uniforms are available to both shader stages.

#api

## API

| Prop               | Type             | Default | Description                                                        |
| ------------------ | ---------------- | ------- | ------------------------------------------------------------------ |
| `shaderCode`       | `string`         | —       | Fragment shader body containing a `mainImage` function.            |
| `vertexShaderCode` | `string`         | —       | Optional vertex shader body containing a `main` function.          |
| `uniforms`         | `ShaderUniforms` | `{}`    | Custom numeric, boolean, vector, or matrix uniforms.               |
| `frameRate`        | `number`         | `60`    | Maximum render frequency.                                          |
| `pixelRatio`       | `number`         | `1`     | Render scale, clamped between `0.25` and `2`.                      |
| `speed`            | `number`         | `1`     | Multiplier applied to `iTime`.                                     |
| `mouseDamping`     | `number`         | `0.85`  | Smoothing applied to pointer movement.                             |
| `paused`           | `boolean`        | `false` | Pause the render loop.                                             |
| `autoPause`        | `boolean`        | `true`  | Pause while the component is off-screen or the document is hidden. |
| `interactive`      | `boolean`        | `true`  | Track pointer input for `iMouse`.                                  |
| `class`            | `string`         | —       | Additional classes merged onto the root element.                   |

### Shader inputs

`iResolution`, `iTime`, `iTimeDelta`, `iFrameRate`, `iFrame`, `iMouse`, `iDate`, `iHasContent`, `iChannel0`, and `iChannelResolution` follow ShaderToy conventions. `iPointerVelocity`, `iPointerEnergy`, and `iPointerAge` provide a damped pointer impulse for effects that should settle after movement. `iPointerInside` transitions between `0` and `1` as the pointer leaves or enters the surface. `iScrollVelocity` provides damped vertical wheel input for vertex deformation. `iHasContent` is `1` when the HTML texture is available.

### Events

| Event     | Payload   | Description                                         |
| --------- | --------- | --------------------------------------------------- |
| `ready`   | —         | Emitted after the first HTML texture is rendered.   |
| `error`   | `string`  | Emitted when shader compilation or rendering fails. |
| `support` | `boolean` | Reports native HTML-in-Canvas availability.         |

### Slots

| Slot      | Description                                  |
| --------- | -------------------------------------------- |
| `default` | HTML content captured as the shader texture. |

#credits

- Built against the [WICG HTML-in-Canvas proposal](https://github.com/WICG/html-in-canvas).

::

---

### En 2.Components Html In Canvas Html Liquid (`content/en/2.components/html-in-canvas/html-liquid.md`)

---
title: HTML Liquid
description: Refract live HTML through a flowing liquid surface that reacts to pointer movement.
category: HTML in Canvas
tags: [webgl, shader, canvas, liquid, interactive]
badge: New
dependencies: []
---

::ComponentViewer{demoFile="HtmlLiquidDemo.vue" config="HtmlLiquidConfig" componentId="html-liquid" :componentFiles='["HtmlLiquid.vue"]'}

#api

## API

| Prop           | Type      | Default | Description                                         |
| -------------- | --------- | ------- | --------------------------------------------------- |
| `strength`     | `number`  | `0.03`  | Amount of texture displacement.                     |
| `frequency`    | `number`  | `18`    | Density of the flowing surface and pointer ripples. |
| `speed`        | `number`  | `3`     | Motion speed of the liquid field.                   |
| `mouseDamping` | `number`  | `0.9`   | Smoothing applied to pointer movement.              |
| `frameRate`    | `number`  | `60`    | Maximum render frequency.                           |
| `pixelRatio`   | `number`  | `1`     | Render scale, clamped between `0.25` and `2`.       |
| `paused`       | `boolean` | `false` | Pauses the render loop.                             |
| `autoPause`    | `boolean` | `true`  | Pauses while off-screen or the document is hidden.  |
| `class`        | `string`  | —       | Additional classes merged onto the surface element. |

### Slots

| Slot      | Description                               |
| --------- | ----------------------------------------- |
| `default` | HTML content rendered through the effect. |

::

---

### En 2.Components Input And Forms Balance Slider (`content/en/2.components/input-and-forms/balance-slider.md`)

---
title: Balance Slider
description: A dynamic balance slider with adjustable colors, limits, and interactive tooltip.
category: Forms & Input
tags: [css, tailwind, input]
---

::ComponentViewer{demoFile="BalanceSliderDemo.vue" config="BalanceSliderConfig" componentId="balance-slider" :componentFiles='["BalanceSlider.vue"]'}

#api

## API

| Prop Name        | Type     | Default     | Description                                         |
| ---------------- | -------- | ----------- | --------------------------------------------------- |
| `initialValue`   | `number` | `50`        | Initial position of the slider (0-100).             |
| `leftColor`      | `string` | `"#e68a00"` | Background color for the left side of the slider.   |
| `rightColor`     | `string` | `"#ffffff"` | Background color for the right side of the slider.  |
| `minShiftLimit`  | `number` | `40`        | Minimum limit where shifting animation activates.   |
| `maxShiftLimit`  | `number` | `68`        | Maximum limit where shifting animation deactivates. |
| `leftContent`    | `string` | `"LEFT"`    | Text displayed in the tooltip for the left side.    |
| `rightContent`   | `string` | `"RIGHT"`   | Text displayed in the tooltip for the right side.   |
| `indicatorColor` | `string` | `"#FFFFFF"` | Color of the central indicator on the slider.       |

#credits

- Inspired and ported from code shared in [Jhey's CSS only version of Balance Slider](https://x.com/jh3yy/status/1748809599598399792?s=46)
- Original concept by [Malay Vasa](https://x.com/MalayVasa/status/1748726374079381930).

::

---

### En 2.Components Input And Forms Color Picker (`content/en/2.components/input-and-forms/color-picker.md`)

---
title: Color Picker
description: A comprehensive color picker component with support for multiple color formats, accessibility features, and custom swatches.
category: Forms & Input
tags: [css, tailwind, input, color-picker, uplusion23]
---

::ComponentViewer{demoFile="ColorPickerDemo.vue" config="ColorPickerConfig" componentId="color-picker" :componentFiles='["ColorPicker.vue", "ObjectColorInput.vue", "ContrastRatio.vue", "index.ts"]' dependencies="@uiw/color-convert"}

#api

## API

### ColorPicker Props

| Prop Name             | Type                                            | Default     | Description                                       |
| --------------------- | ----------------------------------------------- | ----------- | ------------------------------------------------- |
| `value`               | `string \| HsvaColor \| HslaColor \| RgbaColor` | `undefined` | The current color value in any supported format   |
| `type`                | `'hsl' \| 'hsla' \| 'rgb' \| 'rgba' \| 'hex'`   | `'hsl'`     | Default color format to display in inputs         |
| `swatches`            | `HexColor[]`                                    | `[]`        | Array of predefined color swatches                |
| `hideContrastRatio`   | `boolean`                                       | `false`     | Hide the accessibility contrast ratio section     |
| `hideDefaultSwatches` | `boolean`                                       | `false`     | Hide the default color swatches                   |
| `class`               | `string`                                        | `""`        | Additional CSS classes for the popover content    |
| `open`                | `boolean`                                       | `false`     | Control the open/closed state of the color picker |

### ColorPicker Events

| Event Name     | Type                                | Description                                 |
| -------------- | ----------------------------------- | ------------------------------------------- |
| `value-change` | `(value: ColorPickerValue) => void` | Emitted when the selected color changes     |
| `update:open`  | `(value: boolean) => void`          | Emitted when the popover open state changes |

### ColorPickerValue Type

```typescript
interface ColorPickerValue {
  hex: string; // Hex color string (e.g., "#ff0000")
  hsl: HslaColor; // HSL color object with h, s, l, a properties
  hsla: HslaColor; // HSLA color object with h, s, l, a properties
  rgb: RgbaColor; // RGB color object with r, g, b, a properties
  rgba: RgbaColor; // RGBA color object with r, g, b, a properties
}
```

#credits

- Credits to [kalix127](https://github.com/kalix127) for porting this component.
- Inspired by [@uplusion23](https://21st.dev/uplusion23/color-picker/color-picker-with-swatches-and-onchange).

::

---

### En 2.Components Input And Forms File Upload (`content/en/2.components/input-and-forms/file-upload.md`)

---
title: File Upload
description: A modern file upload component with a 3D card effect, drag-and-drop functionality, and a responsive grid background pattern.
category: Forms & Input
tags: [css, tailwind, input, aceternity-ui]
---

::ComponentViewer{demoFile="FileUploadDemo.vue" config="FileUploadConfig" componentId="file-upload" :componentFiles='["FileUpload.vue", "FileUploadGrid.vue"]'}

#api

## API

### `FileUpload`

The `FileUpload` component serves as a wrapper for the file upload effect. It manages mouse events to create a 3D perspective.

#### Props

| Prop Name | Type   | Default | Description                                           |
| --------- | ------ | ------- | ----------------------------------------------------- |
| `class`   | String | -       | Additional classes for styling the container element. |

#### Emits

| Event Name | Type                      | Description                                                |
| ---------- | ------------------------- | ---------------------------------------------------------- |
| `onChange` | `(files: File[]) => void` | Callback function triggered when files are added/uploaded. |

### `FileUploadGrid`

The `FileUploadGrid` component provides the background grid pattern for the file upload area. It is intended to be used within a `FileUpload` component to create the visual grid effect behind the upload interface.

#### Props

| Prop Name | Type   | Default | Description                            |
| --------- | ------ | ------- | -------------------------------------- |
| `class`   | String | -       | Additional classes for custom styling. |

#credits

- Credits to [kalix127](https://github.com/kalix127) for porting this component.
- Inspired by [Aceternity UI](https://ui.aceternity.com/components/file-upload).

::

---

### En 2.Components Input And Forms Halo Search (`content/en/2.components/input-and-forms/halo-search.md`)

---
title: Halo Search
description: A futuristic search input component featuring multiple glowing rings and subtle animated halos for a vibrant, immersive UI experience.
category: Forms & Input
tags: [css, tailwind, input, ui-verse]
---

::ComponentViewer{demoFile="HaloSearchDemo.vue" config="HaloSearchConfig" componentId="halo-search" :componentFiles='["HaloSearch.vue"]'}

#api

## API

| Prop Name | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `class`   | `string` | `""`    | Additional CSS classes for root container. |

#credits

- Design inspired by futuristic UI concepts and ambient lighting effects popular in modern web and app design.
- Inspired from UiVerse Search input challenge.

::

---

### En 2.Components Input And Forms Input (`content/en/2.components/input-and-forms/input.md`)

---
title: Input
description: A versatile and visually dynamic input field with radial hover effects, styled for modern web applications.
category: Forms & Input
tags: [css, tailwind, input, aceternity-ui]
---

::ComponentViewer{demoFile="InputDemo.vue" config="InputConfig" componentId="input" :componentFiles='["IInput.vue"]'}

#api

## API

| Prop Name        | Type                | Default | Description                                                 |
| ---------------- | ------------------- | ------- | ----------------------------------------------------------- |
| `defaultValue`   | `string  \| number` | `""`    | Default value of the input field.                           |
| `class`          | `string`            | `""`    | Additional CSS classes for custom styling.                  |
| `containerClass` | `string`            | `""`    | Additional CSS classes for custom styling of the container. |

#credits

- Built on ShadCN Vue's Input component foundation, with extended functionality for modern UI/UX needs.
- Ported from [Aceternity UI's Signup Form Input Component](https://ui.aceternity.com/components/signup-form)

::

---

### En 2.Components Input And Forms Placeholders And Vanish Input (`content/en/2.components/input-and-forms/placeholders-and-vanish-input.md`)

---
title: Placeholders And Vanish Input
description: Sliding in placeholders and vanish effect of input on submit
category: Forms & Input
tags: [css, tailwind, input, aceternity-ui]
---

::ComponentViewer{demoFile="VanishingInputDemo.vue" config="VanishingInputConfig" componentId="vanishing-input" :componentFiles='["VanishingInput.vue"]'}

#api

## API

| Prop Name      | Type            | Default                                               | Description                                                                     |
| -------------- | --------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------- |
| `placeholders` | `Array<string>` | `["Placeholder 1", "Placeholder 2", "Placeholder 3"]` | An array of placeholder texts that cycle through as prompts in the input field. |

This component listens to the following events emitted by the `VanishingInput` component:

| Event Name | Parameters | Description                             |
| ---------- | ---------- | --------------------------------------- |
| `change`   | `Event`    | Triggered when the input value changes. |
| `submit`   | `string`   | Triggered when the input is submitted.  |

#credits

- Credits to [M Atif](https://github.com/atif0075) for porting this component.
- Ported from [Aceternity UI's Placeholders And Vanish Input](https://ui.aceternity.com/components/placeholders-and-vanish-input).

::

---

### En 2.Components Miscellaneous Animate Grid (`content/en/2.components/miscellaneous/animate-grid.md`)

---
title: Animate Grid
description: Skew Animation grid with box shadow.
category: Miscellaneous
tags: [css, tailwind, input]
---

::ComponentViewer{demoFile="AnimateGridDemo.vue" config="AnimateGridConfig" componentId="animate-grid" :componentFiles='["AnimateGrid.vue"]'}

#instructions

#### Add SVG file

Add at least one SVG file to the same folder as your component and update the import in your component to use it

#api

## API

| Prop Name            | Type     | Default             | Description                                         |
| -------------------- | -------- | ------------------- | --------------------------------------------------- |
| `textGlowStartColor` | `string` | `"#38ef7d80"`       | Color of the box shadow start.                      |
| `textGlowEndColor`   | `string` | `"#38ef7d"`         | Color of the box shadow end.                        |
| `perspective`        | `number` | `600`               | You can pass perspective to transform CSS property. |
| `rotateX`            | `number` | `-1`                | You can pass rotateX to transform CSS property.     |
| `rotateY`            | `number` | `-15`               | You can pass rotateY to transform CSS property.     |
| `cards`              | `[]`     | `"[{logo: 'src'}]"` | Cards to display in grid.                           |
| `class`              | `string` | `""`                | Additional tailwind CSS classes for custom styling. |

#credits

- Thanks to [SivaReddy Uppathi](https://github.com/sivareddyuppathi) for providing this component.

::

---

### En 2.Components Miscellaneous Animated Circular Progressbar (`content/en/2.components/miscellaneous/animated-circular-progressbar.md`)

---
title: Animated Circular Progress Bar
description: Animated Circular Progress Bar is a component that displays a circular gauge with a percentage value.
category: Miscellaneous
tags: [css, tailwind, input, magic-ui]
---

::ComponentViewer{demoFile="AnimatedCircularProgressBarDemo.vue" config="AnimatedCircularProgressBarConfig" componentId="animated-circular-progressbar" :componentFiles='["AnimatedCircularProgressBar.vue"]'}

#api

## API

| Prop Name             | Type      | Default              | Description                                 |
| --------------------- | --------- | -------------------- | ------------------------------------------- |
| `class`               | `string`  | `-`                  | The class to be applied to the component.   |
| `max`                 | `number`  | `100`                | The maximum value of the gauge.             |
| `min`                 | `number`  | `0`                  | The minimum value of the gauge.             |
| `value`               | `number`  | `0`                  | The current value of the gauge.             |
| `gaugePrimaryColor`   | `string`  | `rgb(79 70 229)`     | The primary color of the gauge.             |
| `gaugeSecondaryColor` | `string`  | `rgba(0, 0, 0, 0.1)` | The secondary color of the gauge.           |
| `circleStrokeWidth`   | `number`  | `10`                 | The width of the circle progress bar.       |
| `showPercentage`      | `boolean` | `true`               | Show the value inside the circle            |
| `duration`            | `number`  | `1`                  | The duration of the animation (in seconds). |

#credits

- Credits to [Magic UI](https://magicui.design/docs/components/animated-circular-progress-bar).
- Credits to [SivaReddy Uppathi](https://github.com/sivareddyuppathi) for porting this component.

::

---

### En 2.Components Miscellaneous Animated List (`content/en/2.components/miscellaneous/animated-list.md`)

---
title: Animated List
description: A sequentially animated list that introduces each item with a timed delay, perfect for displaying notifications or events on your landing page.
category: Miscellaneous
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="AnimatedListDemo.vue" config="AnimatedListConfig" componentId="animated-list" :componentFiles='["AnimatedList.vue", "Notification.vue"]'}

#api

## API

| Prop Name | Type     | Default | Description                                                    |
| --------- | -------- | ------- | -------------------------------------------------------------- |
| `delay`   | `number` | `1`     | The delay in milliseconds before adding each item to the list. |

#credits

- Inspired by [Magic UI](https://magicui.design/docs/components/animated-list).

::

---

### En 2.Components Miscellaneous Animated Modal (`content/en/2.components/miscellaneous/animated-modal.md`)

---
title: Animated Modal
description: A modal dialog with a 3D entrance animation and blurred backdrop.
category: Miscellaneous
tags: [css, tailwind, modal, motion, aceternity-ui]
---

::ComponentViewer{demoFile="AnimatedModalDemo.vue" config="AnimatedModalConfig" componentId="animated-modal" :componentFiles='["AnimatedModal.vue", "AnimatedModalBody.vue", "AnimatedModalContent.vue", "AnimatedModalFooter.vue", "AnimatedModalTrigger.vue", "AnimatedModalContext.ts", "useAnimatedModal.ts", "index.ts"]' dependencies="motion-v @vueuse/core"}

#api

## API

### `<AnimatedModal />`

#### Props

| Prop Name     | Type      | Default | Description                     |
| ------------- | --------- | ------- | ------------------------------- |
| `open`        | `boolean` | `-`     | Controlled open state.          |
| `defaultOpen` | `boolean` | `false` | Uncontrolled initial state.     |
| `closeOnEsc`  | `boolean` | `true`  | Close modal when pressing `Esc` |

#### Events

| Event Name    | Payload   | Description                          |
| ------------- | --------- | ------------------------------------ |
| `update:open` | `boolean` | Fired when open state changes.       |
| `open`        | -         | Fired when `openModal()` is called.  |
| `close`       | -         | Fired when `closeModal()` is called. |

#### Slots

| Slot Name | Slot Props                                  |
| --------- | ------------------------------------------- |
| `default` | `open`, `openModal`, `closeModal`, `toggle` |

#### Composable

- `useAnimatedModal()` — access modal state/methods from any nested child component (must be used within `<AnimatedModal />`).

### `<AnimatedModalBody />`

#### Props

| Prop Name        | Type                    | Default  | Description                               |
| ---------------- | ----------------------- | -------- | ----------------------------------------- |
| `class`          | `string`                | `""`     | Extra classes for the modal panel.        |
| `overlayClass`   | `string`                | `""`     | Extra classes for the overlay.            |
| `contentClass`   | `string`                | `""`     | Extra classes for the content wrapper.    |
| `showClose`      | `boolean`               | `true`   | Show close button.                        |
| `closeOnOutside` | `boolean`               | `true`   | Close when clicking outside the dialog.   |
| `lockScroll`     | `boolean`               | `true`   | Lock page scroll while the modal is open. |
| `zIndex`         | `number`                | `10000`  | Z-index for the modal layer.              |
| `teleportTo`     | `string \| HTMLElement` | `"body"` | Teleport target for the modal layer.      |

#credits

- Ported from [Aceternity UI's Animated Modal](https://ui.aceternity.com/components/animated-modal).
- Animations powered by [motion-v](https://motion.dev/).

::

---

### En 2.Components Miscellaneous Animated Tabs (`content/en/2.components/miscellaneous/animated-tabs.md`)

---
title: Animated Tabs
description: A tabs component with a shared-layout active pill and a stacked content transition.
category: Miscellaneous
tags: [css, tailwind, tabs, aceternity-ui, motion-v]
---

::ComponentViewer{demoFile="AnimatedTabsDemo.vue" config="AnimatedTabsConfig" componentId="animated-tabs" :componentFiles='["AnimatedTabs.vue", "AnimatedTabsFadeInDiv.vue", "types.ts", "index.ts"]' dependencies="motion-v"}

#api

## API

### `<AnimatedTabs />`

Tip: give the wrapper a fixed height (e.g. `h-[20rem] md:h-[40rem]`) so the stacked content can be positioned absolutely.

#### Props

| Prop Name            | Type            | Default | Description                                   |
| -------------------- | --------------- | ------- | --------------------------------------------- |
| `tabs`               | `AnimatedTab[]` | `-`     | Tabs metadata list.                           |
| `modelValue`         | `string`        | `-`     | Controlled active tab value.                  |
| `containerClassName` | `string`        | `""`    | Extra classes for the tablist container.      |
| `tabClassName`       | `string`        | `""`    | Extra classes for each tab button.            |
| `activeTabClassName` | `string`        | `""`    | Extra classes for the active pill background. |
| `contentClassName`   | `string`        | `""`    | Extra classes for each stacked content card.  |

#### Events

| Event Name          | Payload  | Description                                      |
| ------------------- | -------- | ------------------------------------------------ |
| `update:modelValue` | `string` | Fired when active tab changes (controlled mode). |

#### Slots

| Slot Name | Slot Props                  | Description                           |
| --------- | --------------------------- | ------------------------------------- |
| `content` | `tab`, `active`, `hovering` | Render the tab content (recommended). |

#### Types

##### `AnimatedTab`

| Field            | Type                  | Required | Description                                                      |
| ---------------- | --------------------- | -------- | ---------------------------------------------------------------- |
| `title`          | `string`              | yes      | Tab label (used by the default UI).                              |
| `value`          | `string`              | yes      | Unique tab id used for active state.                             |
| `panelClassName` | `string`              | no       | Optional panel background classes (used by demos / consumers).   |
| `content`        | `Component`           | no       | Fallback content component when `#content` slot is not provided. |
| `contentProps`   | `Record<string, any>` | no       | Props passed to the `content` component.                         |

#credits

- Ported from [Aceternity UI Tabs](https://ui.aceternity.com/components/tabs).
- Animations powered by [motion-v](https://motion.dev/docs/vue).

::

---

### En 2.Components Miscellaneous Animated Tooltip (`content/en/2.components/miscellaneous/animated-tooltip.md`)

---
title: Animated Tooltip
description: A cool tooltip that reveals on hover, follows mouse pointer
category: Miscellaneous
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="AnimatedTooltipDemo.vue" config="AnimatedTooltipConfig" componentId="animated-tooltip" :componentFiles='["AnimatedTooltip.vue"]'}

#api

## API

| Prop Name | Type                                                                    | Default | Description                                                                                                                                 |
| --------- | ----------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `items`   | `Array<{id: number, name: string, designation: string, image: string}>` | `[]`    | An array of objects, each representing an item. Each object in the array should have the following properties: id, name, designation, image |

#credits

- Credits to [M Atif](https://github.com/atif0075) for this component.
- Inspired from [Aceternity UI's Animated Tooltip](https://ui.aceternity.com/components/animated-tooltip).

::

---

### En 2.Components Miscellaneous Bento Grid (`content/en/2.components/miscellaneous/bento-grid.md`)

---
title: Bento Grid
description: A cool grid layout with different child component.
category: Miscellaneous
tags: [css, tailwind, bento, aceternity-ui]
---

::ComponentViewer{demoFile="BentoGridDemo.vue" config="BentoGridConfig" componentId="bento-grid" :componentFiles='["BentoGrid.vue", "BentoGridCard.vue", "BentoGridItem.vue"]'}

#api

## API

#### `BentoGridItem`

| Slot Name     | Description                       |
| ------------- | --------------------------------- |
| `title`       | Component to show as title.       |
| `description` | Component to show as description. |
| `icon`        | Component to show as icon.        |
| `header`      | Component to show as header.      |

#### `BentoGridCard`

| Slot Name    | Description                      |
| ------------ | -------------------------------- |
| `background` | Component to show in background. |

| Props Name    | Type      | Description                          |
| ------------- | --------- | ------------------------------------ |
| `name`        | `string`  | Name or title to show on card.       |
| `icon`        | `?string` | Icon component to show on card.      |
| `description` | `string`  | Description content to show on card. |
| `href`        | `string`  | Link to the url for CTA.             |
| `cta`         | `string`  | Text to show on CTA.                 |

#credits

- Credits to [Aceternity UI](https://ui.aceternity.com/components/bento-grid) and [Magic UI](https://magicui.design/docs/components/bento-grid) for this fantastic component.

::

---

### En 2.Components Miscellaneous Book (`content/en/2.components/miscellaneous/book.md`)

---
title: Book
description: A 3D book component featuring customizable sizes and color gradients.
category: Miscellaneous
tags: [css, tailwind, x-ui]
---

::ComponentViewer{demoFile="BookDemo.vue" config="BookConfig" componentId="book" :componentFiles='["Book.vue", "BookHeader.vue", "BookTitle.vue", "BookDescription.vue", "index.ts"]'}

#api

## API

#### `Book`

| Prop Name    | Type    | Default | Description                                   |
| ------------ | ------- | ------- | --------------------------------------------- |
| `class`      | String  | -       | Additional classes for styling the component. |
| `duration`   | Number  | 1000    | Animation duration in milliseconds.           |
| `color`      | String  | "zinc"  | Color theme for the book gradient.            |
| `isStatic`   | Boolean | false   | Disables hover animations when true.          |
| `size`       | String  | "md"    | Size variant of the book.                     |
| `radius`     | String  | "md"    | Border radius variant of the book.            |
| `shadowSize` | String  | "lg"    | Shadow size variant of the book.              |

#### `BookHeader`

| Prop Name | Type   | Default | Description                            |
| --------- | ------ | ------- | -------------------------------------- |
| `class`   | String | -       | Additional classes for custom styling. |

#### `BookTitle`

| Prop Name | Type   | Default | Description                            |
| --------- | ------ | ------- | -------------------------------------- |
| `class`   | String | -       | Additional classes for custom styling. |

#### `BookDescription`

| Prop Name | Type   | Default | Description                            |
| --------- | ------ | ------- | -------------------------------------- |
| `class`   | String | -       | Additional classes for custom styling. |

#credits

- Credits to [x/UI](https://ui.3x.gl/docs/book) for inspiring this component.
- Credits to [kalix127](https://github.com/kalix127) for porting this component.

::

---

### En 2.Components Miscellaneous Circular Gallery (`content/en/2.components/miscellaneous/circular-gallery.md`)

---
title: Circular Gallery
description: Arrange slot content around a circle with continuous motion and hover pause.
category: Miscellaneous
tags: [css, tailwind, gallery]
badge: New
---

::ComponentViewer{demoFile="CircularGalleryDemo.vue" config="CircularGalleryConfig" componentId="circular-gallery" :componentFiles='["CircularGallery.vue", "index.ts"]'}

#api

## API

| Prop Name      | Type                  | Default  | Description                                       |
| -------------- | --------------------- | -------- | ------------------------------------------------- |
| `radius`       | `number`              | `100`    | Distance in pixels from the center to each child. |
| `duration`     | `number`              | `10`     | Time in seconds for one full rotation.            |
| `easing`       | `string`              | `linear` | CSS timing function used for the rotation.        |
| `direction`    | `normal` \| `reverse` | `normal` | Rotation direction.                               |
| `class`        | `string`              | —        | Additional classes for the component root.        |
| `pauseOnHover` | `boolean`             | `false`  | Pauses the rotation while a child is hovered.     |

## Usage

Pass the elements to arrange around the circle through the default slot:

```vue
<CircularGallery :radius="140" :duration="12" pause-on-hover>
  <img src="/images/one.jpg" alt="One" class="size-24 object-cover" />
  <img src="/images/two.jpg" alt="Two" class="size-24 object-cover" />
  <img src="/images/three.jpg" alt="Three" class="size-24 object-cover" />
</CircularGallery>
```

#credits

- Ported from [Fancy Components Circling Elements](https://fancycomponents.dev/docs/components/blocks/circling-elements).

::

---

### En 2.Components Miscellaneous Compare (`content/en/2.components/miscellaneous/compare.md`)

---
title: Compare
description: Slide to compare any two pieces of content - images, designs, code, or custom elements
category: Miscellaneous
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="CompareDemo.vue" config="CompareConfig" componentId="compare" :componentFiles='["Compare.vue", "StarField.vue"]'}

#api

## API

### Props

| Prop Name                 | Type                | Default          | Description                               |
| ------------------------- | ------------------- | ---------------- | ----------------------------------------- |
| `firstImage`              | `string`            | `""`             | URL of the first image                    |
| `secondImage`             | `string`            | `""`             | URL of the second image                   |
| `firstImageAlt`           | `string`            | `"First image"`  | Alt text for first image                  |
| `secondImageAlt`          | `string`            | `"Second image"` | Alt text for second image                 |
| `class`                   | `string`            | `""`             | Additional classes for the component      |
| `firstContentClass`       | `string`            | `""`             | Classes applied to first content wrapper  |
| `secondContentClass`      | `string`            | `""`             | Classes applied to second content wrapper |
| `initialSliderPercentage` | `number`            | `50`             | Initial position of slider (0-100)        |
| `slideMode`               | `"hover" \| "drag"` | `"hover"`        | Interaction mode for the slider           |
| `showHandlebar`           | `boolean`           | `true`           | Show/hide the handle bar                  |
| `autoplay`                | `boolean`           | `false`          | Enable/disable autoplay                   |
| `autoplayDuration`        | `number`            | `5000`           | Duration of autoplay cycle in ms          |

### Events

| Event Name          | Payload  | Description                                  |
| ------------------- | -------- | -------------------------------------------- |
| `update:percentage` | `number` | Emitted when slider position changes (0-100) |
| `drag:start`        | -        | Emitted when dragging starts                 |
| `drag:end`          | -        | Emitted when dragging ends                   |
| `hover:enter`       | -        | Emitted when mouse enters component          |
| `hover:leave`       | -        | Emitted when mouse leaves component          |

### Slots

| Slot Name        | Default Content                                   | Description                                                                                                                       |
| ---------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `first-content`  | `<img>` element if `firstImage` prop is provided  | Content shown on the left/first side of the comparison. Has full access to component width/height.                                |
| `second-content` | `<img>` element if `secondImage` prop is provided | Content shown on the right/second side of the comparison. Has full access to component width/height.                              |
| `handle`         | Default slider handle with dots icon              | Custom handle for the slider. Automatically positioned at the dividing line. Should handle positioning with absolute positioning. |

#credits

- Credits to [M Atif](https://github.com/atif0075) for this component.
- Inspired from [Aceternity UI's Compare](https://ui.aceternity.com/components/compare).

::

---

### En 2.Components Miscellaneous Container Scroll (`content/en/2.components/miscellaneous/container-scroll.md`)

---
title: Container Scroll
description: A container scrolling effect that transforms the content inside based on scroll progress. Features smooth transitions with scaling and rotating effects on scroll.
category: Miscellaneous
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="ContainerScrollDemo.vue" config="ContainerScrollConfig" componentId="container-scroll" :componentFiles='["ContainerScroll.vue", "ContainerScrollTitle.vue", "ContainerScrollCard.vue"]'}

#api

## API

### `ContainerScroll`

The `ContainerScroll` component creates a 3D scroll effect. As the user scrolls, the content inside the container is transformed with scale, rotation, and translation effects.

| Prop Name    | Type   | Default | Description                                                                   |
| ------------ | ------ | ------- | ----------------------------------------------------------------------------- |
| `rotate`     | Number | `0`     | Controls the rotation of the inner content based on the scroll progress.      |
| `scale`      | Number | `1`     | Controls the scaling transformation applied to the content during the scroll. |
| `translateY` | Number | `0`     | Controls the vertical translation of the title during the scroll.             |

### `ContainerScrollTitle`

The `ContainerScrollTitle` component handles the title's transformation as the user scrolls, applying a vertical translation effect.

| Prop Name   | Type   | Default | Description                                     |
| ----------- | ------ | ------- | ----------------------------------------------- |
| `translate` | Number | `0`     | Controls the vertical translation of the title. |

### `ContainerScrollCard`

The `ContainerScrollCard` component applies scale and rotation effects to the card content as the user scrolls through the page.

| Prop Name | Type   | Default | Description                                      |
| --------- | ------ | ------- | ------------------------------------------------ |
| `rotate`  | Number | `0`     | Controls the rotation effect of the card.        |
| `scale`   | Number | `1`     | Controls the scaling effect applied to the card. |

## CSS Variables

To customize the scroll animations and responsiveness, you can set the following CSS variables:

- **`--scale-start`**: Initial scale value for the card.
- **`--scale-end`**: Final scale value for the card as the scroll progresses.
- **`--rotate-start`**: Initial rotation value for the card.
- **`--rotate-end`**: Final rotation value for the card as the scroll progresses.

#credits

- Inspired by [Aceternity UI Container Scroll Animation](https://ui.aceternity.com/components/container-scroll-animation).

::

---

### En 2.Components Miscellaneous Dock (`content/en/2.components/miscellaneous/dock.md`)

---
title: Dock
description: A macOS-style dock with magnifying icons as you hover over them.
category: Miscellaneous
tags: [css, tailwind]
---

::ComponentViewer{demoFile="DockDemo.vue" config="DockConfig" componentId="dock" :componentFiles='["Dock.vue", "DockIcon.vue", "DockSeparator.vue", "index.ts", "types.ts", "injectionKeys.ts"]'}

#api

## API

### `Dock`

| Prop Name       | Type     | Description                                                           |
| --------------- | -------- | --------------------------------------------------------------------- |
| `class`         | `string` | Additional classes to apply to the dock container.                    |
| `magnification` | `number` | Magnification factor for the dock icons on hover (default: 60).       |
| `distance`      | `number` | Distance from the icon center where magnification applies.            |
| `direction`     | `string` | Alignment of icons (`top`, `middle`, `bottom`) (default: middle).     |
| `orientation`   | `string` | Orientation of Dock (`vertical`, `horizontal`) (default: horizontal). |

| Slot Name | Description                                          |
| --------- | ---------------------------------------------------- |
| `default` | Dock Dock or other child components to be displayed. |

### `DockIcon`

| Slot Name | Description                                             |
| --------- | ------------------------------------------------------- |
| `default` | Component or icon to be displayed inside the dock icon. |

#credits

- Credits to macOS Dock for the design inspiration and the fantastic hover magnification effect.

::

---

### En 2.Components Miscellaneous Expandable Gallery (`content/en/2.components/miscellaneous/expandable-gallery.md`)

---
title: Expandable Gallery
description: A responsive image gallery with an interactive hover effect that expands images dynamically.
category: Miscellaneous
tags: [css, tailwind, gallery]
---

::ComponentViewer{demoFile="ExpandableGalleryDemo.vue" config="ExpandableGalleryConfig" componentId="expandable-gallery" :componentFiles='["ExpandableGallery.vue"]'}

#api

## API

| Prop Name | Type       | Default | Description                                    |
| --------- | ---------- | ------- | ---------------------------------------------- |
| `images`  | `string[]` | `[]`    | Array of image URLs to display in the gallery. |

#credits

- Inspired from [Expandable Gallery Component by David Mráz](https://x.com/davidm_ml/status/1872319793124282653)

::

---

### En 2.Components Miscellaneous Float (`content/en/2.components/miscellaneous/float.md`)

---
title: Float
description: Add continuous organic movement across three-dimensional position and rotation axes.
category: Miscellaneous
tags: [css, tailwind, motion-v, 3d, animation]
badge: New
dependencies: motion-v
---

::ComponentViewer{demoFile="FloatDemo.vue" config="FloatConfig" componentId="float" :componentFiles='["Float.vue", "index.ts"]'}

#api

## API

| Prop            | Type                       | Default         | Description                                          |
| --------------- | -------------------------- | --------------- | ---------------------------------------------------- |
| `speed`         | `number`                   | `0.5`           | Amount of time progression per animation frame.      |
| `amplitude`     | `[number, number, number]` | `[10, 30, 30]`  | Position movement on the X, Y, and Z axes in pixels. |
| `rotationRange` | `[number, number, number]` | `[15, 15, 7.5]` | Rotation range on the X, Y, and Z axes in degrees.   |
| `timeOffset`    | `number`                   | `0`             | Phase offset for desynchronising multiple floaters.  |
| `class`         | `string`                   | —               | Additional classes merged onto the animated wrapper. |

Place the content to animate in the default slot. The wrapper preserves 3D transforms and updates its position on every animation frame.

#credits

- Ported from [Fancy Components Float](https://fancycomponents.dev/docs/components/blocks/float).

::

---

### En 2.Components Miscellaneous Images Slider (`content/en/2.components/miscellaneous/images-slider.md`)

---
title: Images Slider
description: A full page slider with images that can be navigated with the keyboard.
category: Miscellaneous
tags: [css, tailwind, images, aceternity-ui]
---

::ComponentViewer{demoFile="ImagesSliderDemo.vue" config="ImagesSliderConfig" componentId="images-slider" :componentFiles='["ImagesSlider.vue"]'}

#api

## API

| Prop Name          | Type                       | Default                                           | Description                                                                    |
| ------------------ | -------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------ |
| `images`           | `string[]`                 | `[]`                                              | An array of image URLs to show in the slider.                                  |
| `hideOverlay`      | `boolean`                  | `false`                                           | Don't create an overlay for the image slider. Slot won't be rendered.          |
| `overlayClass`     | `string`                   | `''`                                              | A class string to be applied to the overlay container.                         |
| `imageClass`       | `string`                   | `'bg-cover bg-center bg-no-repeat'`               | Class string to apply to each of the images.                                   |
| `enterFromClass`   | `string`                   | `'scale-0 origin-center'`                         | Class string applied to the 'enter-from-class' prop on the image transition.   |
| `enterActiveClass` | `string`                   | `'transition-transform duration-300 ease-in-out'` | Class string applied to the 'enter-active-class' prop on the image transition. |
| `leaveActiveClass` | `string`                   | `'transition-transform duration-300 ease-in-out'` | Class string applied to the 'leave-active-class' prop on the image transition. |
| `autoplay`         | `boolean\|number`          | `false`                                           | Autoplay interval in ms, or `false` to disable.                                |
| `direction`        | `'vertical'\|'horizontal'` | `'vertical'`                                      | The axis on which the slider should operate.                                   |
| `perspective`      | `string`                   | `'1000px'`                                        | The perspective to apply to the slider container.                              |
| `modelValue`       | `number`                   | `0`                                               | Two-way binding for the current slide image index.                             |

#credits

- Component by [Craig Riley](https://github.com/craigrileyuk) for porting this component.
- Credits to [Aceternity UI](https://ui.aceternity.com/components/images-slider) for inspiring this component.

::

---

### En 2.Components Miscellaneous Lens (`content/en/2.components/miscellaneous/lens.md`)

---
title: Lens
description: A lens component to zoom into images, videos, or practically anything.
category: Miscellaneous
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="LensDemo.vue" config="LensConfig" componentId="lens" :componentFiles='["Lens.vue", "Rays.vue", "Beams.vue"]'}

#api

## API

| Prop Name    | Type                       | Default              | Description                                                                  |
| ------------ | -------------------------- | -------------------- | ---------------------------------------------------------------------------- |
| `zoomFactor` | `number`                   | `1.5`                | The magnification factor for the lens.                                       |
| `lensSize`   | `number`                   | `170`                | The diameter of the lens in pixels.                                          |
| `position`   | `{ x: number, y: number }` | `{ x: 200, y: 150 }` | The static position of the lens (when isStatic is true).                     |
| `isStatic`   | `boolean`                  | `false`              | If true, the lens stays in a fixed position; if false, it follows the mouse. |
| `hovering`   | `boolean`                  | `"false"`            | External control for the hover state.                                        |

#credits

- Credits to [Aceternity UI](https://ui.aceternity.com/components/lens).
- Credits to [SivaReddy Uppathi](https://github.com/sivareddyuppathi) for porting this component.

::

---

### En 2.Components Miscellaneous Link Preview (`content/en/2.components/miscellaneous/link-preview.md`)

---
title: Link Preview
description: Dynamic link previews for your anchor tags
category: Miscellaneous
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="LinkPreviewDemo.vue" config="LinkPreviewConfig" componentId="link-preview" :componentFiles='["LinkPreview.vue"]' dependencies="qss"}

#api

## API

| Prop Name   | Type      | Default | Description                                                                                 |
| ----------- | --------- | ------- | ------------------------------------------------------------------------------------------- |
| `class`     | `string`  | `""`    | Custom class applied to the main element.                                                   |
| `linkClass` | `string`  | `""`    | Custom class applied to the link element.                                                   |
| `width`     | `number`  | `200`   | Width of the preview image.                                                                 |
| `height`    | `number`  | `125`   | Height of the preview image.                                                                |
| `isStatic`  | `boolean` | `false` | Determines if the preview image is static or a URL preview (set to `true` for static mode). |
| `imageSrc`  | `string`  | `""`    | The source of the image to display (required if `isStatic` is `true`).                      |
| `url`       | `string`  | `""`    | URL for the link and for generating the preview image (required if `isStatic` is `false`).  |

#credits

- Credits to [M Atif](https://github.com/atif0075) for porting this component.
- Ported from [Aceternity UI's Link Preview](https://ui.aceternity.com/components/link-preview).

::

---

### En 2.Components Miscellaneous Marquee (`content/en/2.components/miscellaneous/marquee.md`)

---
title: Marquee
description: A customizable scrolling component that loops its content horizontally or vertically, with configurable direction, hover pause, and repeat options.
category: Miscellaneous
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="MarqueeDemo.vue" config="MarqueeConfig" componentId="marquee" :componentFiles='["Marquee.vue", "ReviewCard.vue"]'}

#api

## API

| Prop Name      | Type      | Default | Description                                                               |
| -------------- | --------- | ------- | ------------------------------------------------------------------------- |
| `class`        | `string`  | `''`    | Custom CSS classes to apply to the outermost container of the marquee.    |
| `reverse`      | `boolean` | `false` | Sets the scrolling direction to reverse (right to left or bottom to top). |
| `pauseOnHover` | `boolean` | `false` | Pauses the marquee animation when hovered.                                |
| `vertical`     | `boolean` | `false` | Sets the scrolling direction to vertical instead of horizontal.           |
| `repeat`       | `number`  | `4`     | Number of times the content inside the marquee should be repeated.        |

## CSS Variables

You can customize the speed and gap between the items by setting the following CSS variables:

- **`--duration`**: Controls the speed of the marquee animation.
- **`--gap`**: Sets the space between repeated items in the marquee.

#credits

- Inspired by [Magic UI](https://magicui.design/docs/components/marquee).

::

---

### En 2.Components Miscellaneous Media Text (`content/en/2.components/miscellaneous/media-text.md`)

---
title: Media Text
description: Reveal an image or video between two text fragments on hover, in view, or by ref.
category: Miscellaneous
tags: [media, image, video, motion-v]
badge: New
dependencies: []
---

::ComponentViewer{demoFile="MediaTextDemo.vue" config="MediaTextConfig" componentId="media-text" :componentFiles='["MediaText.vue", "index.ts"]'}

#api

## API

| Prop Name             | Type                           | Default                       | Description                                     |
| --------------------- | ------------------------------ | ----------------------------- | ----------------------------------------------- |
| `firstText`           | `string`                       | —                             | Text rendered before the media.                 |
| `secondText`          | `string`                       | —                             | Text rendered after the media.                  |
| `mediaUrl`            | `string`                       | —                             | Image or video URL.                             |
| `mediaType`           | `"image" \| "video"`           | —                             | Media element to render.                        |
| `mediaContainerClass` | `string`                       | —                             | Classes applied to the animated media wrapper.  |
| `fallbackUrl`         | `string`                       | —                             | Poster URL used by videos.                      |
| `as`                  | `string`                       | `p`                           | Element used for the text fragments.            |
| `autoPlay`            | `boolean`                      | `true`                        | Autoplay the video when `mediaType` is `video`. |
| `loop`                | `boolean`                      | `true`                        | Loop the video when `mediaType` is `video`.     |
| `muted`               | `boolean`                      | `true`                        | Mute the video when `mediaType` is `video`.     |
| `playsInline`         | `boolean`                      | `true`                        | Keep video playback inline on mobile devices.   |
| `alt`                 | `string`                       | Generated                     | Alternative text for an image.                  |
| `triggerType`         | `"hover" \| "ref" \| "inView"` | `hover`                       | Trigger used to reveal the media.               |
| `useInViewOptions`    | `UseInViewOptions`             | `{ once: true, amount: 0.5 }` | Options passed to the in-view trigger.          |
| `animationVariants`   | `object`                       | Width spring reveal           | Motion variants for the media wrapper.          |
| `class`               | `string`                       | —                             | Classes merged onto the root element.           |
| `leftTextClass`       | `string`                       | —                             | Classes applied to the first text fragment.     |
| `rightTextClass`      | `string`                       | —                             | Classes applied to the second text fragment.    |

The component exposes `animate()` and `reset()` for the `ref` trigger.

#credits

- Ported from [Fancy Components Media Between Text](https://fancycomponents.dev/docs/components/blocks/media-between-text).

::

---

### En 2.Components Miscellaneous Morphing Tabs (`content/en/2.components/miscellaneous/morphing-tabs.md`)

---
title: Morphing Tabs
description: This is a morphing tabs interaction, recreated by Preet's work and featuring the gooey effect component.
category: Miscellaneous
tags: [css, tailwind]
---

::ComponentViewer{demoFile="MorphingTabsDemo.vue" config="MorphingTabsConfig" componentId="morphing-tabs" :componentFiles='["MorphingTabs.vue"]'}

#api

## API

| Prop Name          | Type       | Default | Description                                    |
| ------------------ | ---------- | ------- | ---------------------------------------------- |
| `class`            | `string`   | `""`    | Additional class names to style the component. |
| `tabs`             | `string[]` | `[]`    | Tabs.                                          |
| `activeTab`        | `string`   | `""`    | Current active Tab.                            |
| `margin`           | `number`   | `20`    | Active tab margin left and right.              |
| `blurStdDeviation` | `number`   | `6`     | Svg blur stdDeviation, tab rounded use it.     |

#credits

- Credits to [Whbbit1999](https://github.com/Whbbit1999) for this component.
- Inspired and ported from [@Preet "Exclusion tabs"](https://x.com/wickedmishra/status/1823026659894940124).

::

---

### En 2.Components Miscellaneous Multi Step Loader (`content/en/2.components/miscellaneous/multi-step-loader.md`)

---
title: Multi Step Loader
description: A step loader for screens that works with async conditions too.
category: Miscellaneous
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="MultiStepLoaderDemo.vue" config="MultiStepLoaderConfig" componentId="multi-step-loader" :componentFiles='["MultiStepLoader.vue"]'}

#api

## API

| Prop Name         | Type      | Default | Description                                                                  |
| ----------------- | --------- | ------- | ---------------------------------------------------------------------------- |
| `loading`         | `boolean` | `false` | Controls the visibility of the loader. When `true`, the loader is displayed. |
| `steps`           | `Step[]`  | `[]`    | Array of step objects defining the loading sequence.                         |
| `defaultDuration` | `number`  | `1500`  | The duration of each step in milliseconds.                                   |
| `preventClose`    | `boolean` | `false` | If `true`, the close button will not be shown.                               |

| Event Name     | Payload Type | Description                                                          |
| -------------- | ------------ | -------------------------------------------------------------------- |
| `state-change` | `number`     | Emitted when the current step changes, providing the new step index. |
| `complete`     | `void`       | Emitted when all steps have been completed.                          |
| `close`        | `void`       | Emitted when the loader is closed by button.                         |

#credits

- Credits to [M Atif](https://github.com/atif0075) for this component.
- Inspired from [Aceternity UI's Multi Step Loader](https://ui.aceternity.com/components/multi-step-loader).

::

---

### En 2.Components Miscellaneous Parallax Float (`content/en/2.components/miscellaneous/parallax-float.md`)

---
title: Parallax Float
description: Add cursor-driven depth to layered content with independent floating elements.
category: Miscellaneous
tags: [motion, parallax, images]
badge: New
dependencies: motion-v
---

::ComponentViewer{demoFile="ParallaxFloatDemo.vue" config="ParallaxFloatConfig" componentId="parallax-float" :componentFiles='["ParallaxFloat.vue", "ParallaxFloatElement.vue", "ParallaxFloatContext.ts", "index.ts"]'}

#api

## API

### ParallaxFloat

| Prop Name      | Type     | Default | Description                                      |
| -------------- | -------- | ------- | ------------------------------------------------ |
| `sensitivity`  | `number` | `1`     | Multiplier applied to each element's depth.      |
| `easingFactor` | `number` | `0.05`  | Per-frame interpolation toward the target point. |
| `class`        | `string` | —       | Additional classes for the container.            |

### ParallaxFloatElement

| Prop Name | Type     | Default | Description                                   |
| --------- | -------- | ------- | --------------------------------------------- |
| `depth`   | `number` | `1`     | Relative movement depth for the element.      |
| `class`   | `string` | —       | Positioning and styling classes for the item. |

## Usage

Use `ParallaxFloat` as the container and place each independently moving layer inside `ParallaxFloatElement`:

```vue
<ParallaxFloat :sensitivity="-1">
  <ParallaxFloatElement :depth="2" class="top-1/4 left-1/3">
    <img src="/images/portrait.jpg" alt="Portrait" class="size-32 object-cover" />
  </ParallaxFloatElement>
</ParallaxFloat>
```

#credits

- Ported from [Fancy Components Parallax Floating](https://fancycomponents.dev/docs/components/image/parallax-floating).

::

---

### En 2.Components Miscellaneous Path Marquee (`content/en/2.components/miscellaneous/path-marquee.md`)

---
title: Path Marquee
description: Move repeated content along an SVG path with hover slowdown and drag control.
category: Miscellaneous
tags: [svg, motion-v, marquee, drag]
badge: New
dependencies: []
---

::ComponentViewer{demoFile="PathMarqueeDemo.vue" config="PathMarqueeConfig" componentId="path-marquee" :componentFiles='["PathMarquee.vue", "index.ts"]'}

#api

## API

| Prop                       | Type                        | Default                           | Description                                           |
| -------------------------- | --------------------------- | --------------------------------- | ----------------------------------------------------- |
| `path`                     | `string`                    | —                                 | SVG path data used to position each item.             |
| `pathId`                   | `string`                    | Generated                         | ID assigned to the SVG path.                          |
| `showPath`                 | `boolean`                   | `false`                           | Render the path stroke.                               |
| `width`                    | `string \| number`          | `"100%"`                          | SVG width.                                            |
| `height`                   | `string \| number`          | `"100%"`                          | SVG height.                                           |
| `viewBox`                  | `string`                    | `"0 0 100 100"`                   | SVG coordinate system.                                |
| `preserveAspectRatio`      | `string`                    | `"xMidYMid meet"`                 | SVG aspect-ratio behavior.                            |
| `baseVelocity`             | `number`                    | `5`                               | Automatic movement speed.                             |
| `direction`                | `"normal" \| "reverse"`     | `"normal"`                        | Initial movement direction.                           |
| `easing`                   | `(value: number) => number` | —                                 | Optional easing function for path progress.           |
| `slowdownOnHover`          | `boolean`                   | `false`                           | Slow movement while an item is hovered.               |
| `slowDownFactor`           | `number`                    | `0.3`                             | Speed multiplier while hovering.                      |
| `slowDownSpringConfig`     | `object`                    | `{ damping: 50, stiffness: 400 }` | Spring used for hover speed changes.                  |
| `useScrollVelocity`        | `boolean`                   | `false`                           | Add scroll velocity to the movement speed.            |
| `scrollAwareDirection`     | `boolean`                   | `false`                           | Change direction from the latest scroll direction.    |
| `scrollSpringConfig`       | `object`                    | `{ damping: 50, stiffness: 400 }` | Spring used for scroll velocity.                      |
| `repeat`                   | `number`                    | `3`                               | Number of times to repeat slot content.               |
| `draggable`                | `boolean`                   | `false`                           | Allow pointer dragging along the path.                |
| `dragSensitivity`          | `number`                    | `0.2`                             | Multiplier applied to pointer drag velocity.          |
| `dragVelocityDecay`        | `number`                    | `0.96`                            | Decay applied to released drag momentum.              |
| `dragAwareDirection`       | `boolean`                   | `false`                           | Follow the latest drag direction automatically.       |
| `grabCursor`               | `boolean`                   | `false`                           | Use grab and grabbing cursors when draggable.         |
| `enableRollingZIndex`      | `boolean`                   | `true`                            | Layer items based on their current path position.     |
| `zIndexBase`               | `number`                    | `1`                               | Starting z-index value.                               |
| `zIndexRange`              | `number`                    | `10`                              | Range added across the path.                          |
| `cssVariableInterpolation` | `object[]`                  | `[]`                              | Interpolate CSS variables across path progress.       |
| `responsive`               | `boolean`                   | `false`                           | Scale the path coordinate space to fit its container. |
| `class`                    | `string`                    | —                                 | Additional classes merged onto the root element.      |

Pass one or more elements as the default slot. Each slot element is repeated and positioned along the path.

#credits

- Ported from [Fancy Components Marquee Along SVG Path](https://fancycomponents.dev/docs/components/blocks/marquee-along-svg-path).

::

---

### En 2.Components Miscellaneous Photo Gallery (`content/en/2.components/miscellaneous/photo-gallery.md`)

---
title: Photo Gallery
description: Showcase your team with pride using our stunning Photo Gallery Component.
category: Miscellaneous
tags: [css, tailwind, gallery]
---

::ComponentViewer{demoFile="PhotoGalleryDemo.vue" config="PhotoGalleryConfig" componentId="photo-gallery" :componentFiles='["PhotoGallery.vue"]'}

#api

## API

| Prop Name        | Type                | Default | Description                                            |
| ---------------- | ------------------- | ------- | ------------------------------------------------------ |
| `items`          | `"[{src: string}]"` | `[]`    | Pass items / image src to animate                      |
| `containerClass` | `string`            | `""`    | Additional tailwind CSS classes for container styling. |
| `class`          | `string`            | `""`    | Additional tailwind CSS classes for custom styling.    |

#credits

- All images from [Pexels](https://www.pexels.com/@soldiervip/)
- Thanks to [SivaReddy Uppathi](https://github.com/sivareddyuppathi) for providing this component.

::

---

### En 2.Components Miscellaneous Scroll Island (`content/en/2.components/miscellaneous/scroll-island.md`)

---
title: Scroll Island
description: A dynamic and interactive component that displays scroll progress with animated visuals and an expandable area for additional content.
category: Miscellaneous
tags: [css, tailwind, number-flow]
---

::ComponentViewer{demoFile="ScrollIslandDemo.vue" config="ScrollIslandConfig" componentId="scroll-island" :componentFiles='["ScrollIsland.vue"]' dependencies="@number-flow/vue"}

#api

## API

| Prop Name | Type     | Default      | Description                                     |
| --------- | -------- | ------------ | ----------------------------------------------- |
| `class`   | `string` | `""`         | Additional CSS classes for custom styling.      |
| `title`   | `string` | `"Progress"` | Title displayed in the header of the component. |
| `height`  | `string` | `44`         | Height of the component.                        |

#credits

- Inspired by the work of [Ali Samadi](https://x.com/alisamadi__/status/1854312982559502556) & [Nitish Khagwal](https://x.com/nitishkmrk)
- [NumberFlow by Maxwell Barvian](https://number-flow.barvian.me/vue) for number formatting and animations.

::

---

### En 2.Components Miscellaneous Shader Toy (`content/en/2.components/miscellaneous/shader-toy.md`)

---
title: Shader Toy Viewer
description: A powerful and flexible component to render interactive GLSL shaders from ShaderToy in the browser.
category: Miscellaneous
tags: [css, tailwind, shader-toy, ogl, webgl]
badge: Updated
---

::ComponentViewer{demoFile="ShaderToyDemo.vue" config="ShaderToyConfig" componentId="shader-toy" :componentFiles='["ShaderToy.vue", "InspiraShaderToy.ts"]' dependencies="ogl"}

#api

## API

| Prop Name    | Type                                 | Default   | Description                                               |
| ------------ | ------------------------------------ | --------- | --------------------------------------------------------- |
| `shaderCode` | `string`                             | `-`       | GLSL fragment shader source code from ShaderToy.          |
| `uniforms`   | `Record<string, number \| number[]>` | `{}`      | Values for custom uniforms declared by the shader.        |
| `mouseMode`  | `'click' \| 'hover'`                 | `'click'` | Mouse tracking mode: either on click or continuous hover. |
| `hue`        | `number`                             | `0`       | Adjust the hue of the shader output.                      |
| `saturation` | `number`                             | `1`       | Adjust the saturation of the shader output.               |
| `brightness` | `number`                             | `1`       | Adjust the brightness of the shader output.               |
| `speed`      | `number`                             | `1`       | Adjust the speed of the shader output.                    |
| `frameRate`  | `number`                             | `60`      | Caps render frequency for heavier shaders.                |
| `pixelRatio` | `number`                             | `1`       | Controls canvas render scale for quality/performance.     |
| `paused`     | `boolean`                            | `false`   | Pauses playback manually.                                 |
| `autoPause`  | `boolean`                            | `true`    | Pauses rendering while off-screen or when the tab hides.  |
| `class`      | `string`                             | `-`       | Custom classes to apply to the container.                 |

#credits

- Built with [OGL](https://github.com/oframe/ogl).
- Inspired by [Shadertoy](https://shadertoy.com/) and adapted for Vue compatibility.

::

---

### En 2.Components Miscellaneous Svg Mask (`content/en/2.components/miscellaneous/svg-mask.md`)

---
title: SVG Mask
description: A dynamic SVG mask component that reveals content with hover and mouse movement.
category: Miscellaneous
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="SvgMaskDemo.vue" config="SvgMaskConfig" componentId="svg-mask" :componentFiles='["SVGMask.vue"]'}

#api

## API

| Prop Name    | Type     | Default | Description                                |
| ------------ | -------- | ------- | ------------------------------------------ |
| `class`      | `string` | `""`    | Additional CSS classes for custom styling. |
| `size`       | `number` | `10`    | Initial size of the mask in pixels.        |
| `revealSize` | `number` | `600`   | Size of the mask during hover in pixels.   |

#credits

- Ported from [Aceternity UI's SVG Mask Effect](https://ui.aceternity.com/components/text-generate-effect).

::

---

### En 2.Components Miscellaneous Timeline (`content/en/2.components/miscellaneous/timeline.md`)

---
title: Timeline
description: A visually appealing and interactive timeline component with smooth animations, sticky labels, and a gradient scrolling effect.
category: Miscellaneous
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="TimelineDemo.vue" config="TimelineConfig" componentId="timeline" :componentFiles='["Timeline.vue"]'}

#api

## API

| Prop Name        | Type                               | Default | Description                                        |
| ---------------- | ---------------------------------- | ------- | -------------------------------------------------- |
| `containerClass` | `string`                           | `""`    | Additional CSS classes for the timeline container. |
| `class`          | `string`                           | `""`    | Additional CSS classes for styling.                |
| `items`          | `{ id: string; label: string; }[]` | `[]`    | List of timeline items, each with an ID and label. |
| `title`          | `string`                           | `""`    | Title of the timeline section.                     |
| `description`    | `string`                           | `""`    | Description text displayed below the title.        |

#credits

- Inspired and ported from [Aceternity UI's Timeline](https://ui.aceternity.com/components/timeline).

::

---

### En 2.Components Miscellaneous Tracing Beam (`content/en/2.components/miscellaneous/tracing-beam.md`)

---
title: Tracing Beam
description: A component that renders a tracing beam effect with dynamic scrolling animations and gradient strokes.
category: Miscellaneous
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="TracingBeamDemo.vue" config="TracingBeamConfig" componentId="tracing-beam" :componentFiles='["TracingBeam.vue"]'}

#api

## API

| Prop Name | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `class`   | `string` | `""`    | Additional CSS classes for custom styling. |

#credits

- Ported from [Aceternity UI](https://ui.aceternity.com/components/tracing-beam);

::

---

### En 2.Components Special Effects Animated Beam (`content/en/2.components/special-effects/animated-beam.md`)

---
title: Animated Beam
description: An SVG beam connecting elements with animation.
category: Special Effects
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="AnimatedBeamDemo.vue" config="AnimatedBeamConfig" componentId="animated-beam" :componentFiles='["AnimatedBeam.vue"]'}

#api

## API

| Prop Name            | Type          | Default                | Description                                                                  |
| -------------------- | ------------- | ---------------------- | ---------------------------------------------------------------------------- |
| `class`              | `string`      | `""`                   | Additional CSS classes to apply to the component for customization.          |
| `containerRef`       | `HTMLElement` | N/A                    | Reference to the container element where the beam is rendered.               |
| `fromRef`            | `HTMLElement` | N/A                    | Reference to the starting element from which the beam originates.            |
| `toRef`              | `HTMLElement` | N/A                    | Reference to the ending element where the beam points to.                    |
| `curvature`          | `number`      | `0`                    | Controls the curvature of the beam; higher values create a more curved path. |
| `reverse`            | `boolean`     | `false`                | Reverses the animation direction of the beam if set to `true`.               |
| `pathColor`          | `string`      | `"gray"`               | Color of the beam's path.                                                    |
| `pathWidth`          | `number`      | `2`                    | Stroke width of the beam's path.                                             |
| `pathOpacity`        | `number`      | `0.2`                  | Opacity of the beam's path.                                                  |
| `gradientStartColor` | `string`      | `"#FFAA40"`            | Starting color of the beam's gradient animation.                             |
| `gradientStopColor`  | `string`      | `"#9C40FF"`            | Ending color of the beam's gradient animation.                               |
| `delay`              | `number`      | `0`                    | Delay before the beam's animation starts, in seconds.                        |
| `duration`           | `number`      | `Random between 4–7 s` | Duration of the beam's animation cycle, in seconds.                          |
| `startXOffset`       | `number`      | `0`                    | Horizontal offset for the beam's starting point.                             |
| `startYOffset`       | `number`      | `0`                    | Vertical offset for the beam's starting point.                               |
| `endXOffset`         | `number`      | `0`                    | Horizontal offset for the beam's ending point.                               |
| `endYOffset`         | `number`      | `0`                    | Vertical offset for the beam's ending point.                                 |

#credits

- Inspired and ported from [Magic UI Animated Beam](https://magicui.design/docs/components/animated-beam).

::

---

### En 2.Components Special Effects Border Beam (`content/en/2.components/special-effects/border-beam.md`)

---
title: Border Beam
description: A stylish animated border beam effect with customizable size, duration, colors, and delay.
category: Special Effects
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="BorderBeamDemo.vue" config="BorderBeamConfig" componentId="border-beam" :componentFiles='["BorderBeam.vue"]'}

#api

## API

| Prop Name     | Type     | Default     | Description                                                           |
| ------------- | -------- | ----------- | --------------------------------------------------------------------- |
| `class`       | `string` | `""`        | Additional CSS classes for custom styling.                            |
| `size`        | `number` | `200`       | Size of the animated border beam effect.                              |
| `duration`    | `number` | `15`        | Duration of the animation in seconds.                                 |
| `borderWidth` | `number` | `1.5`       | Width of the border around the beam effect.                           |
| `anchor`      | `number` | `90`        | Anchor point for the beam, determining its position along the border. |
| `colorFrom`   | `string` | `"#ffaa40"` | Starting color for the gradient of the beam.                          |
| `colorTo`     | `string` | `"#9c40ff"` | Ending color for the gradient of the beam.                            |
| `delay`       | `number` | `0`         | Delay before the animation starts, in seconds.                        |

#credits

- Ported from [Magic UI](https://magicui.design/docs/components/border-beam).

::

---

### En 2.Components Special Effects Confetti (`content/en/2.components/special-effects/confetti.md`)

---
title: Confetti
description: A Vue component for confetti animations.
category: Special Effects
tags: [css, tailwind, canvas, magic-ui]
---

::ComponentViewer{demoFile="ConfettiDemo.vue" config="ConfettiConfig" componentId="confetti" :componentFiles='["Confetti.vue", "ConfettiButton.vue"]' dependencies="canvas-confetti" devDependencies="@types/canvas-confetti"}

#api

## API

### Props

#### `Confetti`

| Prop Name       | Type                    | Default | Description                                                       |
| --------------- | ----------------------- | ------- | ----------------------------------------------------------------- |
| `options`       | `ConfettiOptions`       | `{}`    | Options for individual confetti bursts.                           |
| `globalOptions` | `ConfettiGlobalOptions` | `{}`    | Global options for the confetti instance (e.g., resize behavior). |
| `manualstart`   | `boolean`               | `false` | If `true`, confetti won't start automatically on mount.           |

#### `ConfettiOptions`

| Property                  | Type                        | Default                                                                         | Description                                                            |
| ------------------------- | --------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `particleCount`           | `number`                    | `50`                                                                            | The number of confetti particles to launch.                            |
| `angle`                   | `number`                    | `90`                                                                            | The angle in degrees at which to launch the confetti.                  |
| `spread`                  | `number`                    | `45`                                                                            | The spread in degrees of the confetti.                                 |
| `startVelocity`           | `number`                    | `45`                                                                            | The initial velocity of the confetti particles.                        |
| `decay`                   | `number`                    | `0.9`                                                                           | The rate at which confetti particles slow down.                        |
| `gravity`                 | `number`                    | `1`                                                                             | The gravity applied to confetti particles.                             |
| `drift`                   | `number`                    | `0`                                                                             | The horizontal drift applied to confetti particles.                    |
| `ticks`                   | `number`                    | `200`                                                                           | The number of animation frames the confetti should last.               |
| `origin`                  | `{ x: number, y: number }`  | `{ x: 0.5, y: 0.5 }`                                                            | The origin point (from 0 to 1) of the confetti emission.               |
| `colors`                  | `string[]`                  | `['#26ccff', '#a25afd', '#ff5e7e', '#88ff5a', '#fcff42', '#ffa62d', '#ff36ff']` | Array of color strings in HEX format for the confetti particles.       |
| `shapes`                  | `string[]`                  | `['square', 'circle']`                                                          | Array of shapes for the confetti particles.                            |
| `scalar`                  | `number`                    | `1`                                                                             | Scaling factor for confetti particle sizes.                            |
| `zIndex`                  | `number`                    | `100`                                                                           | The z-index value for the confetti canvas element.                     |
| `disableForReducedMotion` | `boolean`                   | `false`                                                                         | Disables confetti for users who prefer reduced motion.                 |
| `useWorker`               | `boolean`                   | `true`                                                                          | Use a Web Worker for better performance.                               |
| `resize`                  | `boolean`                   | `true`                                                                          | Whether to automatically resize the canvas when the window resizes.    |
| `canvas`                  | `HTMLCanvasElement \| null` | `null`                                                                          | Custom canvas element to draw confetti on.                             |
| `gravity`                 | `number`                    | `1`                                                                             | The gravity applied to confetti particles.                             |
| `drift`                   | `number`                    | `0`                                                                             | The horizontal drift applied to particles.                             |
| `flat`                    | `boolean`                   | `false`                                                                         | If `true`, confetti particles will be flat (no rotation or 3D effect). |

#### `ConfettiButton`

| Prop Name | Type                                               | Default | Description                                      |
| --------- | -------------------------------------------------- | ------- | ------------------------------------------------ |
| `options` | `ConfettiOptions & { canvas?: HTMLCanvasElement }` | `{}`    | Options for confetti when the button is clicked. |

#credits

- Built using the [canvas-confetti](https://www.npmjs.com/package/canvas-confetti) library.
- Ported from [Magic UI Confetti](https://magicui.design/docs/components/confetti).

::

---

### En 2.Components Special Effects Dither Shader (`content/en/2.components/special-effects/dither-shader.md`)

---
title: Dither Shader
description: A real-time ordered dithering effect for images, perfect for pixel art and retro aesthetics.
category: Special Effects
tags: [tailwind, background, card, aceternity-ui]
---

::ComponentViewer{demoFile="DitherShaderDemo.vue" config="DitherShaderConfig" componentId="dither-shader" :componentFiles='["DitherShader.vue"]'}

#api

## API

| Prop              | Type                                                 | Default                  | Description                                                                  |
| ----------------- | ---------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------- |
| `src`             | `string`                                             | `–`                      | Source image URL                                                             |
| `gridSize`        | `number`                                             | `4`                      | Size of the dithering grid cells                                             |
| `ditherMode`      | `"bayer" \| "halftone" \| "noise" \| "crosshatch"`   | `"bayer"`                | Type of dithering pattern                                                    |
| `colorMode`       | `"original" \| "grayscale" \| "duotone" \| "custom"` | `"original"`             | Color processing mode                                                        |
| `invert`          | `boolean`                                            | `false`                  | Invert the dithered output colors                                            |
| `pixelRatio`      | `number`                                             | `1`                      | Pixelation multiplier (1 = no pixelation, higher = more pixelated)           |
| `primaryColor`    | `string`                                             | `"#000000"`              | Primary color for duotone mode                                               |
| `secondaryColor`  | `string`                                             | `"#ffffff"`              | Secondary color for duotone mode                                             |
| `customPalette`   | `string[]`                                           | `["#000000", "#ffffff"]` | Custom color palette array for custom mode                                   |
| `brightness`      | `number`                                             | `0`                      | Brightness adjustment (-1 to 1)                                              |
| `contrast`        | `number`                                             | `1`                      | Contrast adjustment (0 to 2, 1 = normal)                                     |
| `backgroundColor` | `string`                                             | `"transparent"`          | Background color behind the dithered image                                   |
| `objectFit`       | `"cover" \| "contain" \| "fill" \| "none"`           | `"cover"`                | Object fit behavior                                                          |
| `threshold`       | `number`                                             | `0.5`                    | Threshold bias for dithering (0 to 1)                                        |
| `animated`        | `boolean`                                            | `false`                  | Enable animation effect                                                      |
| `animationSpeed`  | `number`                                             | `0.02`                   | Animation speed (lower = slower)                                             |
| `class`           | `string`                                             | `–`                      | Additional CSS classes for the container (use this to set size via Tailwind) |

#credits

- Inspired and ported from [Aceternity UI Dither Shader](https://ui.aceternity.com/components/dither-shader).

::

---

### En 2.Components Special Effects Glow Border (`content/en/2.components/special-effects/glow-border.md`)

---
title: Glow Border
description: An animated border effect.
category: Special Effects
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="GlowBorderDemo.vue" config="GlowBorderConfig" componentId="glow-border" :componentFiles='["GlowBorder.vue"]'}

#api

## API

| Prop Name      | Type                 | Default | Description                                                |
| -------------- | -------------------- | ------- | ---------------------------------------------------------- |
| `duration`     | `number`             | `10`    | Duration of the glowing border animation.                  |
| `color`        | `string \| string[]` | `#FFF`  | Color or array of colors to applied on the glowing border. |
| `borderRadius` | `number`             | `10`    | Radius of the border.                                      |
| `borderWidth`  | `number`             | `2`     | Width of the border.                                       |

#instructions

Add following entry to inline theme in your `main.css` file.

```css
@theme inline {
  --animate-glow: glow var(--duration) infinite linear;
  @keyframes glow {
    0% {
      background-position: 0% 0%;
    }
    50% {
      background-position: 100% 100%;
    }
    to {
      background-position: 0% 0%;
    }
  }
}
```

#credits

- Credits to [Magic UI](https://magicui.design/docs/components/shine-border) for this fantastic component.

::

---

### En 2.Components Special Effects Glowing Effect (`content/en/2.components/special-effects/glowing-effect.md`)

---
title: Glowing Effect
description: A dynamic proximity-based glow effect that reacts to mouse movements and scroll events, perfect for highlighting interactive elements.
category: Special Effects
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="GlowingEffectDemo.vue" config="GlowingEffectConfig" componentId="glowing-effect" :componentFiles='["GlowingEffect.vue"]'}

#api

## API

| Prop Name          | Type                   | Default     | Description                                                                                           |
| ------------------ | ---------------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
| `blur`             | `number`               | `0`         | The blur radius applied to the glow layer.                                                            |
| `inactiveZone`     | `number`               | `0.7`       | Defines the inner radius (as a fraction of the smallest dimension) within which the glow is inactive. |
| `proximity`        | `number`               | `0`         | Additional proximity distance (in pixels) to trigger the glow when the cursor is near the element.    |
| `spread`           | `number`               | `20`        | Size of the spread of the glow effect around the element.                                             |
| `variant`          | `"default" \| "white"` | `"default"` | Variant of the glow style (e.g., a white-themed version).                                             |
| `glow`             | `boolean`              | `false`     | Controls the visibility of the static glow border.                                                    |
| `class`            | `string`               | `""`        | Additional CSS classes for custom styling.                                                            |
| `disabled`         | `boolean`              | `true`      | Disables the proximity detection and glow animations when `true`.                                     |
| `movementDuration` | `number`               | `2`         | Duration (in seconds) of the smooth rotation animation.                                               |
| `borderWidth`      | `number`               | `1`         | Width (in pixels) of the border applied to the glow effect.                                           |

#credits

- Ported from (Aceternity UI Glowing Effect)[https://ui.aceternity.com/components/glowing-effect]

::

---

### En 2.Components Special Effects Images Badge (`content/en/2.components/special-effects/images-badge.md`)

---
title: Images Badge
description: A badge with images that can be hovered to reveal more images.
category: Special Effects
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="ImagesBadgeDemo.vue" config="ImagesBadgeConfig" componentId="images-badge" :componentFiles='["ImagesBadge.vue"]'}

#api

## API

| Prop Name         | Type                                | Default                     | Description                                                               |
| ----------------- | ----------------------------------- | --------------------------- | ------------------------------------------------------------------------- |
| `text`            | `string`                            | —                           | Text label displayed next to the folder badge.                            |
| `images`          | `string[]`                          | —                           | Array of image URLs to display (up to 3 are shown).                       |
| `class`           | `string`                            | —                           | Additional CSS classes for the root element.                              |
| `href`            | `string`                            | —                           | Optional link URL; renders an `<a>` tag instead of `<div>` when provided. |
| `target`          | `string`                            | —                           | Link target attribute (e.g. `_blank` for new tab).                        |
| `folderSize`      | `{ width: number; height: number }` | `{ width: 32, height: 24 }` | Folder icon dimensions in pixels.                                         |
| `teaserImageSize` | `{ width: number; height: number }` | `{ width: 20, height: 14 }` | Image dimensions while peeking (idle state) in pixels.                    |
| `hoverImageSize`  | `{ width: number; height: number }` | `{ width: 48, height: 32 }` | Image dimensions when hovered in pixels.                                  |
| `hoverTranslateY` | `number`                            | `-35`                       | How far images translate upward on hover in pixels.                       |
| `hoverSpread`     | `number`                            | `20`                        | Horizontal spread between images on hover in pixels.                      |
| `hoverRotation`   | `number`                            | `15`                        | Fan rotation angle for images on hover in degrees.                        |

#credits

- Ported from [Aceternity UI Images Badge](https://ui.aceternity.com/components/images-badge)

::

---

### En 2.Components Special Effects Meteors (`content/en/2.components/special-effects/meteors.md`)

---
title: Meteors
description: A component that displays a meteor shower animation with customizable meteor count and styling.
category: Special Effects
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="MeteorsDemo.vue" config="MeteorsConfig" componentId="meteors" :componentFiles='["Meteors.vue"]'}

#api

## API

| Prop Name | Type     | Default | Description                                                       |
| --------- | -------- | ------- | ----------------------------------------------------------------- |
| `count`   | `number` | `20`    | The number of meteors to display in the animation.                |
| `class`   | `string` | `""`    | Additional CSS classes to apply to the meteors for customization. |

#instructions

Add following entry to inline theme in your `main.css` file.

```css
@theme inline {
  --animate-meteor-effect: meteor 5s linear infinite;
  @keyframes meteor {
    0% {
      transform: rotate(215deg) translateX(0);
      opacity: 1;
    }
    70% {
      opacity: 1;
    }
    100% {
      transform: rotate(215deg) translateX(-500px);
      opacity: 0;
    }
  }
}
```

#credits

- Ported from [Aceternity UI's Meteor Effect](https://ui.aceternity.com/components/meteors)

::

---

### En 2.Components Special Effects Neon Border (`content/en/2.components/special-effects/neon-border.md`)

---
title: Neon Border
description: A visually appealing neon border component with customizable animations and colors.
category: Special Effects
tags: [css, tailwind, border]
---

::ComponentViewer{demoFile="NeonBorderDemo.vue" config="NeonBorderConfig" componentId="neon-border" :componentFiles='["NeonBorder.vue"]'}

#api

## API

| Prop Name       | Type                         | Default     | Description                                     |
| --------------- | ---------------------------- | ----------- | ----------------------------------------------- |
| `color1`        | `string`                     | `"#0496ff"` | Primary color of the neon border.               |
| `color2`        | `string`                     | `"#ff0a54"` | Secondary color of the neon border.             |
| `animationType` | `"none" \| "half" \| "full"` | `"half"`    | Type of animation effect applied to the border. |
| `duration`      | `number`                     | `6`         | Duration of the animation effect in seconds.    |
| `class`         | `string`                     | `""`        | Additional CSS classes for styling.             |

#instructions

Add following entry to inline theme in your `main.css` file.

```css
@theme inline {
  --animate-neon-border: neon-border var(--neon-border-duration) linear infinite;
  @keyframes neon-border {
    0% {
      transform: rotate(0deg);
    }
    100% {
      transform: rotate(360deg);
    }
  }
}
```

#credits

- Inspired by modern neon border effects.

::

---

### En 2.Components Special Effects Particle Image (`content/en/2.components/special-effects/particle-image.md`)

---
title: Particle Image
description: Visually appealing particle animation applied to images as seen on NuxtLabs.com
category: Special Effects
tags: [css, tailwind, canvas, particles]
---

::ComponentViewer{demoFile="ParticleImageDemo.vue" config="ParticleImageConfig" componentId="particle-image" :componentFiles='["ParticleImage.vue", "inspiraImageParticles.js", "inspiraImageParticles.d.ts"]'}

#api

## API

| Prop Name         | Type                                                                          | Default  | Description                                                                     |
| ----------------- | ----------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------- |
| `imageSrc`        | `string`                                                                      | `null`   | Source URL for the image to which the particle effect is applied.               |
| `class`           | `string`                                                                      | `null`   | Additional CSS classes to apply to the image element.                           |
| `canvasWidth`     | `string`                                                                      | `null`   | Width of the particle effect canvas.                                            |
| `canvasHeight`    | `string`                                                                      | `null`   | Height of the particle effect canvas.                                           |
| `gravity`         | `string`                                                                      | `null`   | Gravity force affecting the particle movement.                                  |
| `particleSize`    | `string`                                                                      | `null`   | Size of the particles.                                                          |
| `particleGap`     | `string`                                                                      | `null`   | Gap between particles.                                                          |
| `mouseForce`      | `string`                                                                      | `null`   | Force applied to particles based on mouse movement.                             |
| `renderer`        | `"default" \| "webgl"`                                                        | `null`   | The renderer to use for particle generation, either default or WebGL.           |
| `color`           | `string`                                                                      | `#FFF`   | Hexadecimal color code used for particles. Supports 3 or 6 character hex codes. |
| `colorArr`        | `number[]`                                                                    | `null`   | Array of numbers to define multiple particle colors.                            |
| `initPosition`    | `"random" \| "top" \| "left" \| "bottom" \| "right" \| "misplaced" \| "none"` | `random` | Initial position of the particles when the animation starts.                    |
| `initDirection`   | `"random" \| "top" \| "left" \| "bottom" \| "right" \| "none"`                | `random` | Initial direction of the particles when the animation starts.                   |
| `fadePosition`    | `"explode" \| "top" \| "left" \| "bottom" \| "right" \| "random" \| "none"`   | `none`   | Position where the particles fade out.                                          |
| `fadeDirection`   | `"random" \| "top" \| "left" \| "bottom" \| "right" \| "none"`                | `none`   | Direction in which the particles fade out.                                      |
| `noise`           | `number`                                                                      | `null`   | Noise of the particles.                                                         |
| `responsiveWidth` | `boolean`                                                                     | `false`  | Should the canvas be responsive.                                                |

#credits

- Credits to [Nuxt Labs](https://nuxtlabs.com) for this inspiration.
- Credits to [NextParticles](https://nextparticle.nextco.de) for the base of the animation library.

::

---

### En 2.Components Special Effects Progressive Blur (`content/en/2.components/special-effects/progressive-blur.md`)

---
title: Progressive Blur
description: A layered backdrop blur effect that gradually increases intensity in a chosen direction, perfect for depth, focus, and visual separation.
category: Special Effects
tags: [css, tailwind, motion-v, blur, backdrop-filter]
---

::ComponentViewer{demoFile="ProgressiveBlurDemo.vue" config="ProgressiveBlurConfig" componentId="progressive-blur" :componentFiles='["ProgressiveBlur.vue"]'}

#api

## API

| Prop Name       | Type                                     | Default    | Description                                                  |
| --------------- | ---------------------------------------- | ---------- | ------------------------------------------------------------ |
| `direction`     | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Direction in which the blur progressively increases.         |
| `blurLayers`    | `number`                                 | `8`        | Number of blur layers used to create the progressive effect. |
| `blurIntensity` | `number`                                 | `0.25`     | Blur strength multiplier per layer (in pixels).              |
| `class`         | `string`                                 | `""`       | Optional class applied to the wrapper container.             |

> This component also accepts all valid `motion-v` props for a `div`.

#credits

- Ported from [Motion Primitives Progressive Blur](https://motion-primitives.com/docs/progressive-blur).
- Powered by `motion-v`

::

---

### En 2.Components Special Effects Scales (`content/en/2.components/special-effects/scales.md`)

---
title: Scales
description: A repeating diagonal, horizontal, or vertical line pattern background effect.
category: Special Effects
tags: [css, tailwind, aceternity-ui]
---

::ComponentViewer{demoFile="ScalesDemo.vue" config="ScalesConfig" componentId="scales" :componentFiles='["Scales.vue"]'}

#api

## API

| Prop Name        | Type                                       | Default      | Description                                             |
| ---------------- | ------------------------------------------ | ------------ | ------------------------------------------------------- |
| `orientation`    | `"horizontal" \| "vertical" \| "diagonal"` | `"diagonal"` | Direction of the repeating line pattern.                |
| `size`           | `number`                                   | `10`         | Size of each repeating tile in pixels.                  |
| `color`          | `string`                                   | —            | CSS color value for the pattern lines.                  |
| `class`          | `string`                                   | —            | Additional CSS classes for the inner pattern overlay.   |
| `containerClass` | `string`                                   | —            | Additional CSS classes for the outer container element. |

#credits

- Ported from [Aceternity UI Scales](https://ui.aceternity.com/components/scales).

::

---

### En 2.Components Special Effects Scratch To Reveal (`content/en/2.components/special-effects/scratch-to-reveal.md`)

---
title: Scratch To Reveal
description: The ScratchToReveal component creates an interactive scratch-off effect with customizable dimensions and animations, revealing hidden content beneath.
category: Special Effects
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="ScratchToRevealDemo.vue" config="ScratchToRevealConfig" componentId="scratch-to-reveal" :componentFiles='["ScratchToReveal.vue"]'}

#api

## API

| Prop Name              | Type                     | Default | Description                                                                                   |
| ---------------------- | ------------------------ | ------- | --------------------------------------------------------------------------------------------- |
| `class`                | `string`                 | `""`    | The class name to apply to the component.                                                     |
| `width`                | `number`                 | `""`    | Width of the scratch container.                                                               |
| `height`               | `number`                 | `""`    | Height of the scratch container.                                                              |
| `minScratchPercentage` | `number`                 | `50`    | Minimum percentage of scratched area to be considered as completed (Value between 0 and 100). |
| `gradientColors`       | `[string,string,string]` | `-`     | Gradient colors for the scratch effect.                                                       |

| Event Name | Payload | Description                                        |
| ---------- | ------- | -------------------------------------------------- |
| `complete` | `-`     | Callback function called when scratch is completed |

| Slot Name | Default Content | Description                            |
| --------- | --------------- | -------------------------------------- |
| `default` | `-`             | The text below the scratch-off ticket. |

#credits

- Credits to [Whbbit1999](https://github.com/Whbbit1999) for this component.
- Inspired by [MagicUI Scratch To Reveal](https://magicui.design/docs/components/scratch-to-reveal).

::

---

### En 2.Components Special Effects Spring Calendar (`content/en/2.components/special-effects/spring-calendar.md`)

---
title: Spring Calendar
description: An animated calendar widget that expands to reveal events and features smooth, spring‑based Motion‑V transitions.
category: Special Effects
tags: [css, tailwind, motion-v]
---

::ComponentViewer{demoFile="SpringCalendarDemo.vue" config="SpringCalendarConfig" componentId="spring-calendar" :componentFiles='["SpringCalendar.vue", "TextMorph.vue"]'}

#api

## API

| Prop Name      | Type                                                                                                           | Default | Description                                                           |
| -------------- | -------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------- |
| `calendarData` | `Array<{ month: string; date: number; day: string; events?: { title: string; day: string; time: string }[] }>` | **—**   | Array defining each calendar day and its optional events. _Required_. |
| `initialIndex` | `number`                                                                                                       | `0`     | Day index initially selected.                                         |

### Emits

| Event                | Payload  | Description                                                        |
| -------------------- | -------- | ------------------------------------------------------------------ |
| `update:activeIndex` | `number` | Fires when a day button is clicked, emitting the new active index. |

#credits

- Inspired from the work of [sekachov](https://x.com/sekachov)

::

---

### En 2.Components Testimonials Animated Testimonials (`content/en/2.components/testimonials/animated-testimonials.md`)

---
title: Animated Testimonials
description: An engaging and animated testimonial component showcasing user feedback with transitions and auto-play functionality.
category: Testimonials
tags: [css, tailwind, aceternity-ui, testimonial]
---

::ComponentViewer{demoFile="AnimatedTestimonialsDemo.vue" config="AnimatedTestimonialsConfig" componentId="animated-testimonials" :componentFiles='["AnimatedTestimonials.vue"]'}

#api

## API

| Prop Name      | Type            | Default | Description                                                                                    |
| -------------- | --------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `testimonials` | `Testimonial[]` | `[]`    | An array of testimonial objects containing quote, name, image, and designation.                |
| `autoplay`     | `boolean`       | `false` | Whether to cycle through testimonials automatically.                                           |
| `duration`     | `number`        | `5000`  | Duration (in milliseconds) to wait before automatically transitioning to the next testimonial. |

### Testimonial Object

Each testimonial object must contain the following fields:

| Property      | Type     | Description                                                       |
| ------------- | -------- | ----------------------------------------------------------------- |
| `quote`       | `string` | The testimonial text.                                             |
| `name`        | `string` | The name of the person or entity providing the testimonial.       |
| `designation` | `string` | The position or role of the testimonial author (e.g., CEO, user). |
| `image`       | `string` | URL of the image or avatar for the testimonial author.            |

#credits

- Ported from (Aceternity UI Animated Testimonials)[https://ui.aceternity.com/components/animated-testimonials].

::

---

### En 2.Components Testimonials Design Testimonials (`content/en/2.components/testimonials/design-testimonials.md`)

---
title: Design Testimonials
description: A premium, design-forward testimonial section featuring cinematic typography, magnetic parallax, word-by-word animations, and auto-cycling navigation.
category: Testimonials
tags: [css, tailwind, motion-v, testimonial, animation]
---

::ComponentViewer{demoFile="DesignTestimonialsDemo.vue" config="DesignTestimonialsConfig" componentId="design-testimonials" :componentFiles='["DesignTestimonials.vue"]'}

#api

## API

| Prop Name      | Type                | Default          | Description                                                          |
| -------------- | ------------------- | ---------------- | -------------------------------------------------------------------- |
| `title`        | `string`            | `"Testimonials"` | Vertical label shown on the left side of the layout.                 |
| `duration`     | `number`            | `6000`           | Time (in ms) before automatically switching to the next testimonial. |
| `testimonials` | `TestimonialItem[]` | **required**     | List of testimonial entries to render and animate.                   |

### `TestimonialItem` Object

Each testimonial must follow this structure:

| Property  | Type     | Description                                              |
| --------- | -------- | -------------------------------------------------------- |
| `quote`   | `string` | The testimonial text, animated word-by-word.             |
| `author`  | `string` | Name of the testimonial author.                          |
| `role`    | `string` | Role or designation of the author.                       |
| `company` | `string` | Company or organization name (used in badge and ticker). |

#credits

- Animation powered by `motion-v`
- Ported from [Design Testimonials by Jatin Yadav](https://21st.dev/community/components/jatin-yadav05/design-testimonial/default)

::

---

### En 2.Components Testimonials Testimonial Slider (`content/en/2.components/testimonials/testimonial-slider.md`)

---
title: Testimonial Slider
description: A lightweight testimonial slider with image rotation, text transitions, and optional auto‑rotation.
category: Testimonials
tags: [css, tailwind, testimonial]
---

::ComponentViewer{demoFile="TestimonialSliderDemo.vue" config="TestimonialSliderConfig" componentId="testimonial-slider" :componentFiles='["TestimonialSlider.vue"]'}

#api

## API

| Prop Name      | Type                                                                | Default | Description                                                            |
| -------------- | ------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------- |
| `testimonials` | `Array<{ img: string; quote: string; name: string; role: string }>` | `[]`    | Array of testimonial objects displayed by the slider.                  |
| `autoRotate`   | `boolean`                                                           | `true`  | If `true`, the slider advances automatically every `duration` seconds. |
| `duration`     | `number`                                                            | `5`     | Interval in seconds between slides when auto‑rotation is enabled.      |

::

---

### En 2.Components Text Animations 3d Text (`content/en/2.components/text-animations/3d-text.md`)

---
title: 3D Text
description: A stylish 3D text component with customizable colors, shadows, and animation options.
category: Text Animation
tags: [css, tailwind, 3d]
---

::ComponentViewer{demoFile="Text3dDemo.vue" config="Text3dConfig" componentId="text-3d" :componentFiles='["Text3d.vue"]'}

#api

## API

| Prop Name           | Type      | Default    | Description                                        |
| ------------------- | --------- | ---------- | -------------------------------------------------- |
| `textColor`         | `string`  | `"white"`  | Color of the main text.                            |
| `letterSpacing`     | `number`  | `-0.1`     | Adjusts the spacing between letters in `ch` units. |
| `strokeColor`       | `string`  | `"black"`  | Color of the text stroke.                          |
| `shadowColor`       | `string`  | `"yellow"` | Color of the text shadow.                          |
| `strokeSize`        | `number`  | `20`       | Thickness of the text stroke in pixels.            |
| `shadow1Size`       | `number`  | `7`        | Size of the first shadow layer in pixels.          |
| `shadow2Size`       | `number`  | `10`       | Size of the second shadow layer in pixels.         |
| `class`             | `string`  | `""`       | Additional CSS classes for custom styling.         |
| `animate`           | `boolean` | `true`     | Enables wiggle animation when set to `true`.       |
| `animationDuration` | `number`  | `1500`     | Duration of the wiggle animation in milliseconds.  |

::

---

### En 2.Components Text Animations Blur Reveal (`content/en/2.components/text-animations/blur-reveal.md`)

---
title: Blur Reveal
description: A component to smoothly blur fade in content.
category: Text Animation
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="BlurRevealDemo.vue" config="BlurRevealConfig" componentId="blur-reveal" :componentFiles='["BlurReveal.vue"]'}

#api

## API

| Prop Name  | Type     | Default | Description                                                                  |
| ---------- | -------- | ------- | ---------------------------------------------------------------------------- |
| `duration` | `number` | `1`     | Duration of the blur fade in animation.                                      |
| `delay`    | `number` | `1`     | Delay between child components to reveal                                     |
| `blur`     | `string` | `10px`  | Amount of blur to apply to the child components.                             |
| `yOffset`  | `number` | `20`    | Specifies the vertical offset distance (yOffset) for the entrance animation. |

#credits

- Credits to [Magic UI](https://magicui.design/docs/components/blur-fade) for this fantastic component.

::

---

### En 2.Components Text Animations Box Reveal (`content/en/2.components/text-animations/box-reveal.md`)

---
title: Box Reveal
description: An animated box reveal effect with customizable colors, duration, and delay.
category: Text Animation
tags: [css, tailwind, magic-ui]
---

::ComponentViewer{demoFile="BoxRevealDemo.vue" config="BoxRevealConfig" componentId="box-reveal" :componentFiles='["BoxReveal.vue"]'}

#api

## API

| Prop Name  | Type     | Default     | Description                                          |
| ---------- | -------- | ----------- | ---------------------------------------------------- |
| `color`    | `string` | `"#5046e6"` | Background color of the reveal box.                  |
| `duration` | `number` | `0.5`       | Duration of the reveal animation in seconds.         |
| `delay`    | `number` | `0.25`      | Delay before the reveal animation starts in seconds. |
| `class`    | `string` | `""`        | Additional CSS classes for custom styling.           |

#credits

- Ported from [Magic UI Box Reveal](https://magicui.design/docs/components/box-reveal).

::

---

### En 2.Components Text Animations Breathing Text (`content/en/2.components/text-animations/breathing-text.md`)

---
title: Breathing Text
description: Animate variable font axes continuously with a staggered breathing rhythm.
category: Text Animation
tags: [css, tailwind, motion-v, variable-font]
badge: New
dependencies: motion-v
---

::ComponentViewer{demoFile="BreathingTextDemo.vue" config="BreathingTextConfig" componentId="breathing-text" :componentFiles='["BreathingText.vue", "index.ts"]'}

#api

## API

| Prop                        | Type                                      | Default                                | Description                                              |
| --------------------------- | ----------------------------------------- | -------------------------------------- | -------------------------------------------------------- |
| `text`                      | `string`                                  | Slot content                           | Text to split into independently animated letters.       |
| `as`                        | `string`                                  | `"span"`                               | HTML element used for the root text node.                |
| `fromFontVariationSettings` | `string`                                  | —                                      | Font variation settings used at the start of each cycle. |
| `toFontVariationSettings`   | `string`                                  | —                                      | Font variation settings used at the end of each cycle.   |
| `transition`                | `Transition`                              | `{ duration: 1.5, ease: "easeInOut" }` | Motion transition for each letter.                       |
| `staggerDuration`           | `number`                                  | `0.1`                                  | Delay between each letter's animation.                   |
| `staggerFrom`               | `"first" \| "last" \| "center" \| number` | `"first"`                              | Origin used to calculate the stagger order.              |
| `repeatDelay`               | `number`                                  | `0.1`                                  | Delay between repeated breathing cycles.                 |
| `class`                     | `string`                                  | —                                      | Additional classes merged onto the root element.         |

Use a variable font and pass the axes it supports. For example, Roboto Flex can use `wght` and `wdth`.

#credits

- Ported from [Fancy Components Breathing Text](https://fancycomponents.dev/docs/components/text/breathing-text).

::

---

--- METRICS ---
- Files Extracted: 293
- Estimated Token Budget: ~125291 tokens
- Canonical Reference: https://codewiki.google/github.com/unovue/inspira-ui