# Animated components for Vue and Nuxt.



# Getting Started

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

This collection offers beautifully designed, reusable components, taking inspiration from the amazing work done on both [Aceternity UI](https://ui.aceternity.com){rel=""nofollow""} and [Magic UI](https://magicui.design){rel=""nofollow""}. 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){rel=""nofollow""}
- Highly [configurable](https://inspira-ui.com/components) to meet your design needs
- A wide range of [components](https://inspira-ui.com/components) to choose from
- Optimized for mobile use
- Fully compatible with Nuxt

### Acknowledgments

Special thanks to:

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

### About Me

Hi, I'm [Rahul Vashishtha](https://rahulv.dev){rel=""nofollow""}. 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){rel=""nofollow""} and join me on this journey [here](https://github.com/unovue/inspira-ui){rel=""nofollow""}!

Feel free to explore and enjoy building with Inspira UI!


# Installation

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){rel=""nofollow""}.**
::

## 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){rel=""nofollow""} or using this [framework-specific guide for Nuxt](https://tailwindcss.com/docs/installation/framework-guides/nuxt){rel=""nofollow""}.

### 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){rel=""nofollow""}.

### 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
      ```css [main.css]
      @import "tailwindcss";
      @import "@nuxt/ui";

      @theme static {
        --color-background: var(--ui-bg);
        --color-foreground: var(--ui-text);

        --color-card: var(--ui-bg-elevated);
        --color-card-foreground: var(--ui-text);

        --color-popover: var(--ui-bg-elevated);
        --color-popover-foreground: var(--ui-text);

        --color-muted: var(--ui-bg-muted);
        --color-muted-foreground: var(--ui-text-muted);

        --color-accent: var(--ui-bg-accented);
        --color-accent-foreground: var(--ui-text);

        --color-border: var(--ui-border);
        --color-input: var(--ui-border);

        --color-primary: var(--ui-primary);
        --color-primary-foreground: var(--ui-text-inverted);

        --color-secondary: var(--ui-secondary);
        --color-secondary-foreground: var(--ui-text-inverted);

        --color-destructive: var(--ui-error);
        --color-destructive-foreground: var(--ui-text-inverted);

        --color-ring: var(--ui-primary);

        --radius: var(--ui-radius);
      }

      :root {
        --background: var(--ui-bg);
        --foreground: var(--ui-text);

        --card: var(--ui-bg-elevated);
        --card-foreground: var(--ui-text);

        --popover: var(--ui-bg-elevated);
        --popover-foreground: var(--ui-text);

        --muted: var(--ui-bg-muted);
        --muted-foreground: var(--ui-text-muted);

        --accent: var(--ui-bg-accented);
        --accent-foreground: var(--ui-text);

        --border: var(--ui-border);
        --input: var(--ui-border);

        --primary: var(--ui-primary);
        --primary-foreground: var(--ui-text-inverted);

        --secondary: var(--ui-secondary);
        --secondary-foreground: var(--ui-text-inverted);

        --destructive: var(--ui-error);
        --destructive-foreground: var(--ui-text-inverted);

        --ring: var(--ui-primary);
      }
      ```
      :::::
    ::::

    ::::tabs-item{icon="simple-icons:tailwindcss" label="Other TailwindCSS Kit"}
      :::::code-collapse
      ```css [main.css]
      @import "tailwindcss";
      @import "tw-animate-css";

      @custom-variant dark (&:is(.dark *));

      :root {
        --card: oklch(1 0 0);
        --card-foreground: oklch(0.141 0.005 285.823);
        --popover: oklch(1 0 0);
        --popover-foreground: oklch(0.141 0.005 285.823);
        --primary: oklch(0.21 0.006 285.885);
        --primary-foreground: oklch(0.985 0 0);
        --secondary: oklch(0.967 0.001 286.375);
        --secondary-foreground: oklch(0.21 0.006 285.885);
        --muted: oklch(0.967 0.001 286.375);
        --muted-foreground: oklch(0.552 0.016 285.938);
        --accent: oklch(0.967 0.001 286.375);
        --accent-foreground: oklch(0.21 0.006 285.885);
        --destructive: oklch(0.577 0.245 27.325);
        --destructive-foreground: oklch(0.577 0.245 27.325);
        --border: oklch(0.92 0.004 286.32);
        --input: oklch(0.92 0.004 286.32);
        --ring: oklch(0.705 0.015 286.067);
        --radius: 0.625rem;
        --background: oklch(1 0 0);
        --foreground: oklch(0.141 0.005 285.823);
      }

      .dark {
        --background: oklch(0.141 0.005 285.823);
        --foreground: oklch(0.985 0 0);
        --card: oklch(0.141 0.005 285.823);
        --card-foreground: oklch(0.985 0 0);
        --popover: oklch(0.141 0.005 285.823);
        --popover-foreground: oklch(0.985 0 0);
        --primary: oklch(0.985 0 0);
        --primary-foreground: oklch(0.21 0.006 285.885);
        --secondary: oklch(0.274 0.006 286.033);
        --secondary-foreground: oklch(0.985 0 0);
        --muted: oklch(0.274 0.006 286.033);
        --muted-foreground: oklch(0.705 0.015 286.067);
        --accent: oklch(0.274 0.006 286.033);
        --accent-foreground: oklch(0.985 0 0);
        --destructive: oklch(0.396 0.141 25.723);
        --destructive-foreground: oklch(0.637 0.237 25.331);
        --border: oklch(0.274 0.006 286.033);
        --input: oklch(0.274 0.006 286.033);
        --ring: oklch(0.442 0.017 285.786);
      }

      @theme inline {
        --color-background: var(--background);
        --color-foreground: var(--foreground);
        --color-card: var(--card);
        --color-card-foreground: var(--card-foreground);
        --color-popover: var(--popover);
        --color-popover-foreground: var(--popover-foreground);
        --color-primary: var(--primary);
        --color-primary-foreground: var(--primary-foreground);
        --color-secondary: var(--secondary);
        --color-secondary-foreground: var(--secondary-foreground);
        --color-muted: var(--muted);
        --color-muted-foreground: var(--muted-foreground);
        --color-accent: var(--accent);
        --color-accent-foreground: var(--accent-foreground);
        --color-destructive: var(--destructive);
        --color-destructive-foreground: var(--destructive-foreground);
        --color-border: var(--border);
        --color-input: var(--input);
        --color-ring: var(--ring);

        --radius-sm: calc(var(--radius) - 4px);
        --radius-md: calc(var(--radius) - 2px);
        --radius-lg: var(--radius);
        --radius-xl: calc(var(--radius) + 4px);
      }

      @layer base {
        * {
          @apply border-border outline-ring/50;
        }
        body {
          @apply bg-background text-foreground;
        }
      }

      html {
        color-scheme: light dark;
      }
      html.dark {
        color-scheme: dark;
      }
      html.light {
        color-scheme: light;
      }
      ```
      :::::
    ::::
  :::
::

::tip{.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/){rel="&#x22;nofollow&#x22;"}.

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


# How To Contribute

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](https://inspira-ui.com/#getting-started)
2. [Code of Conduct](https://inspira-ui.com/#code-of-conduct)
3. [How to Contribute](https://inspira-ui.com/#how-to-contribute)
   - [Reporting Bugs](https://inspira-ui.com/#reporting-bugs)
   - [Suggesting Enhancements](https://inspira-ui.com/#suggesting-enhancements)
   - [Adding New Components](https://inspira-ui.com/#adding-new-components)
4. [Project Structure](https://inspira-ui.com/#project-structure)
5. [Style Guidelines](https://inspira-ui.com/#style-guidelines)
   - [Coding Standards](https://inspira-ui.com/#coding-standards)
   - [Component Format](https://inspira-ui.com/#component-format)
   - [Commit Messages](https://inspira-ui.com/#commit-messages)
6. [Documentation Guidelines](https://inspira-ui.com/#documentation-guidelines)
   - [Single-File Components](https://inspira-ui.com/#single-file-components)
   - [Multi-File Components](https://inspira-ui.com/#multi-file-components)
7. [Testing](https://inspira-ui.com/#testing)
8. [License](https://inspira-ui.com/#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](https://inspira-ui.com/code-of-conduct), 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" rel="&#x22;nofollow&#x22;"} 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" rel="&#x22;nofollow&#x22;"} 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`**:br
   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. :br 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
<!-- Template -->
<script lang="ts" setup>
// Your script code goes here
</script>

<!-- Script (if required) -->
<template>
  <!-- Your template code goes here -->
</template>

<!-- Styles (if required) -->
<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>{rel="&#x22;nofollow&#x22;"}

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

Contants 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/){rel="&#x22;nofollow&#x22;"} 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](https://inspira-ui.com/#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**:br 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**:br 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**:br 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**:br 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**:br 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**:br 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**:br 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**:br 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**:br 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**:br Provide comprehensive API documentation covering all components:
   ```markdown
   ## API

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

**Example:**

```markdown
---
title: Pattern Background
description: Simple animated pattern background to make your sections stand out.
---

Grid background with dot
::ComponentLoader{label="Preview" componentName="PatternBackgroundDotDemo" type="examples" id="pattern-background"}
::

## Install using CLI

::InstallationCli{componentId="pattern-background"}
::

## Install Manually

Copy and paste the following code in the same folder

::code-group

:CodeViewerTab{label="PatternBackground.vue" language="vue" componentName="PatternBackground" type="ui" id="pattern-background"}
:CodeViewerTab{filename="index.ts" language="typescript" componentName="index" type="ui" id="pattern-background" extension="ts"}

::

## Examples

Grid background with big dot and ellipse on top
::ComponentLoader{label="Preview" componentName="PatternBackgroundBigDotDemo" type="examples" id="pattern-background"}
::

Grid background without animation
::ComponentLoader{label="Preview" componentName="PatternBackgroundGridDemo" type="examples" id="pattern-background"}
::

Small grid background with animation
::ComponentLoader{label="Preview" componentName="PatternBackgroundGridSmallDemo" type="examples" id="pattern-background"}
::

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

### Custom variants, values and constants

You can customize your needs directly within the `index.ts` file. See code below.

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

## 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" rel="&#x22;nofollow&#x22;"}.


# Code of Conduct

## 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){rel="&#x22;nofollow&#x22;"}

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){rel="&#x22;nofollow&#x22;"}


# Aurora Background

::component-viewer
---
component-files:
  - AuroraBackground.vue
component-id: aurora-background
config: AuroraBackgroundConfig
demo-file: AuroraBackgroundDemo.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){rel=""nofollow""}.
- Credits to [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} for porting this component.
::


# Black Hole Background

::component-viewer
---
component-files:
  - BlackHoleBackground.vue
component-id: bg-black-hole
config: BlackHoleBackgroundConfig
demo-file: BlackHoleBackgroundDemo.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.
::


# Bubbles Background

::component-viewer
---
component-files:
  - BubblesBg.vue
component-id: bg-bubbles
config: BubblesBgConfig
demo-file: BubblesBgDemo.vue
dependencies: three
dev-dependencies: "@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/){rel=""nofollow""} library for 3D rendering and animations.
- Inspired from [Tresjs Experiment](https://lab.tresjs.org/experiments/overlay){rel=""nofollow""}.
::


# Cosmic Portal

::component-viewer
---
component-files:
  - CosmicPortal.vue
component-id: cosmic-portal
config: CosmicPortalConfig
demo-file: CosmicPortalDemo.vue
dependencies: three postprocessing
dev-dependencies: "@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_){rel=""nofollow""}.
::


# Falling Stars Background

::component-viewer
---
component-files:
  - FallingStarsBg.vue
component-id: bg-falling-stars
config: FallingStarsBgConfig
demo-file: FallingStarsBgDemo.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){rel=""nofollow""} for porting the original component to Vue & Nuxt.
::


# Flickering Grid

::component-viewer
---
component-files:
  - FlickeringGrid.vue
component-id: flickering-grid
config: FlickeringGridConfig
demo-file: FlickeringGridDemo.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){rel=""nofollow""} for this component.
::


# Interactive Grid Pattern

::component-viewer
---
component-files:
  - InteractiveGridPattern.vue
component-id: interactive-grid-pattern
config: InteractiveGridPatternConfig
demo-file: InteractiveGridPatternDemo.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){rel=""nofollow""}.
- Credits to [kalix127](https://github.com/kalix127){rel=""nofollow""} for porting this component.
::


# Lamp Effect

::component-viewer
---
component-files:
  - LampEffect.vue
component-id: lamp-effect
config: LampEffectConfig
demo-file: LampEffectDemo.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){rel=""nofollow""}
::


# Liquid Background

::component-viewer
---
component-files:
  - LiquidBackground.vue
component-id: liquid-background
config: LiquidBackgroundConfig
demo-file: LiquidBackgroundDemo.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){rel=""nofollow""} library for 3D rendering.
- Inspired by generative art patterns.
- Uses Vue's Composition API for lifecycle and state management.
::


# Neural Background

::component-viewer
---
component-files:
  - NeuralBg.vue
component-id: bg-neural
config: NeuralBgConfig
demo-file: NeuralBgDemo.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){rel=""nofollow""} — 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){rel=""nofollow""}.
::


# Particle Whirlpool

::component-viewer
---
component-files:
  - ParticleWhirlpoolBg.vue
component-id: bg-particle-whirlpool
config: ParticleWhirlpoolBgConfig
demo-file: ParticleWhirlpoolBgDemo.vue
dependencies: three postprocessing
dev-dependencies: "@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/){rel=""nofollow""} library for 3D rendering and animations.
- Inspired by [TroisJs](https://troisjs.github.io/examples/demos/3.html){rel=""nofollow""}
::


# Particles Background

::component-viewer
---
component-files:
  - ParticlesBg.vue
component-id: particles-bg
config: ParticlesBgConfig
demo-file: ParticlesBgDemo.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){rel=""nofollow""} for this fantastic component.
- Credit to [Prodromos Pantos](https://github.com/prpanto){rel=""nofollow""} for porting the original component to Vue & Nuxt.
::


# Pattern Background

::component-viewer
---
component-files:
  - PatternBackground.vue
  - index.ts
component-id: pattern-background
config: PatternBackgroundConfig
demo-file: PatternBackgroundDemo.vue
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){rel=""nofollow""} component.
- Inspired by [Magic UI's Grid Pattern](https://magicui.design/docs/components/grid-pattern){rel=""nofollow""} component.
- Inspired by [Magic UI's Animated Grid Pattern](https://magicui.design/docs/components/animated-grid-pattern){rel=""nofollow""} component.
- Credits to [Nathan De Pachtere](https://nathandepachtere.com/){rel=""nofollow""} for porting this component.
::


# Ribbon Background

::component-viewer
---
component-files:
  - RibbonBackground.vue
component-id: ribbon-background
config: RibbonBackgroundConfig
demo-file: RibbonBackgroundDemo.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){rel=""nofollow""}.
::


# Ripple

::component-viewer
---
component-files:
  - Ripple.vue
  - RippleCircle.vue
  - RippleContainer.vue
component-id: ripple
config: RippleConfig
demo-file: RippleDemo.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){rel=""nofollow""}.
- Credits to [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} for porting this component.
- Credits to [Nathan De Pachtere](https://nathandepachtere.com/){rel=""nofollow""} for updating this component.
::


# Silk Background

::component-viewer
---
component-files:
  - SilkBackground.vue
component-id: bg-silk
config: SilkBackgroundConfig
demo-file: SilkBackgroundDemo.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){rel=""nofollow""} by Giorgi Azmaipharashvili (MIT License).
- Inspired by silk textures and fluid motion patterns found in organic materials.
::


# Singularity Background

::component-viewer
---
component-files:
  - SingularityBackground.vue
component-id: bg-singularity
config: SingularityBackgroundConfig
demo-file: SingularityBackgroundDemo.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){rel=""nofollow""}.
::


# Snowfall Background

::component-viewer
---
component-files:
  - SnowfallBg.vue
component-id: snowfall-bg
config: SnowfallBgConfig
demo-file: SnowfallBgDemo.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.
::


# Sparkles

::component-viewer
---
component-files:
  - Sparkles.vue
component-id: sparkles
config: SparklesConfig
demo-file: SparklesDemo.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){rel=""nofollow""} for porting this component.
- Ported from [Aceternity UI's Sparkles](https://ui.aceternity.com/components/sparkles){rel=""nofollow""}.
::


# Stars Background

::component-viewer
---
component-files:
  - StarsBackground.vue
component-id: bg-stars
config: StarsBackgroundConfig
demo-file: StarsBackgroundDemo.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){rel=""nofollow""}
::


# Stractium Background

::component-viewer
---
component-files:
  - StractiumBackground.vue
component-id: bg-stractium
config: StractiumBackgroundConfig
demo-file: StractiumBackgroundDemo.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.
::


# Tetris

::component-viewer
---
component-files:
  - Tetris.vue
component-id: tetris
config: TetrisConfig
demo-file: TetrisDemo.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){rel=""nofollow""} for this component.
- Inspired and ported from [Nuxt UI Home](https://ui2.nuxt.com/){rel=""nofollow""}.
::


# Thunderstorm Background

::component-viewer
---
component-files:
  - ThunderstormBackground.vue
component-id: bg-thunderstorm
config: ThunderstormBackgroundConfig
demo-file: ThunderstormBackgroundDemo.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){rel=""nofollow""}.
::


# Video Text

::component-viewer
---
component-files:
  - VideoText.vue
component-id: video-text
config: VideoTextConfig
demo-file: VideoTextDemo.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){rel=""nofollow""} for this component.
- Ported from [Magic UI's Video Text](https://magicui.design/docs/components/video-text){rel=""nofollow""}.
::


# Vortex Background

::component-viewer
---
component-files:
  - Vortex.vue
component-id: vortex
config: VortexConfig
demo-file: VortexDemo.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){rel=""nofollow""}.
- Credits to [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} for porting this component.
::


# Warp Background

::component-viewer
---
component-files:
  - WarpBackground.vue
  - Beam.vue
component-id: warp-background
config: WarpBackgroundConfig
demo-file: WarpBackgroundDemo.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){rel=""nofollow""} for this component.
- Inspired and ported from [Magic UI WarpBackground](https://magicui.design/docs/components/warp-background){rel=""nofollow""}.
::


# Wavy Background

::component-viewer
---
component-files:
  - WavyBackground.vue
component-id: wavy-background
config: WavyBackgroundConfig
demo-file: WavyBackgroundDemo.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){rel=""nofollow""}.
- Credits to [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} for porting this component.
::


# Gradient Button

::component-viewer
---
component-files:
  - GradientButton.vue
component-id: gradient-button
config: GradientButtonConfig
demo-file: GradientButtonDemo.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.                      |
::


# Interactive Hover Button

::component-viewer
---
component-files:
  - InteractiveHoverButton.vue
component-id: interactive-hover-button
config: InteractiveHoverButtonConfig
demo-file: InteractiveHoverButtonDemo.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){rel=""nofollow""} for this component.
- Inspired and ported from [Magic UI Interactive Hover Button](https://magicui.design/docs/components/interactive-hover-button){rel=""nofollow""}.
::


# Rainbow Button

::component-viewer
---
component-files:
  - RainbowButton.vue
component-id: rainbow-button
config: RainbowButtonConfig
demo-file: RainbowButtonDemo.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){rel=""nofollow""} for porting this component.
- Credits to [Magic UI](https://magicui.design/docs/components/rainbow-button){rel=""nofollow""}.
::


# Ripple Button

::component-viewer
---
component-files:
  - RippleButton.vue
component-id: ripple-button
config: RippleButtonConfig
demo-file: RippleButtonDemo.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){rel=""nofollow""} component.
- Credits to [kalix127](https://github.com/kalix127){rel=""nofollow""} for porting this component.
::


# Shimmer Button

::component-viewer
---
component-files:
  - ShimmerButton.vue
component-id: shimmer-button
config: ShimmerButtonConfig
demo-file: ShimmerButtonDemo.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){rel=""nofollow""}.
::


# 3D Card Effect

::component-viewer
---
component-files:
  - CardContainer.vue
  - CardBody.vue
  - CardItem.vue
  - useMouseState.ts
component-id: card-3d
config: Card3dConfig
demo-file: CardDemo.vue
---
#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.
::


# Apple Card Carousel

::component-viewer
---
component-files:
  - AppleCardCarousel.vue
  - AppleCarouselItem.vue
  - AppleCard.vue
  - AppleBlurImage.vue
  - AppleCarouselContext.ts
component-id: apple-card-carousel
config: AppleCardCarouselConfig
demo-file: AppleCardCarouselDemo.vue
---
#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){rel=""nofollow""}.
::


# Card Spotlight

::component-viewer
---
component-files:
  - CardSpotlight.vue
component-id: card-spotlight
config: CardSpotlightConfig
demo-file: CardSpotlightDemo.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){rel=""nofollow""}.
::


# Card Stack

::component-viewer
---
component-files:
  - CardStack.vue
  - CardStackItem.vue
  - CardStackContext.ts
  - index.ts
component-id: card-stack
config: CardStackConfig
demo-file: CardStackDemo.vue
---
#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){rel=""nofollow""}.
::


# Cube Carousel

::component-viewer
---
component-files:
  - CubeCarousel.vue
  - index.ts
component-id: cube-carousel
config: CubeCarouselConfig
demo-file: CubeCarouselDemo.vue
---
#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){rel=""nofollow""}.
- Demo artwork by [Daniel Petho](https://www.cosmos.so/danielpetho/box-carousel-demo){rel=""nofollow""}.
- Inspired by [Framer University](https://framer.university/resources/3d-box-carousel-in-framer){rel=""nofollow""}.
::


# Direction Aware Hover Card

::component-viewer
---
component-files:
  - DirectionAwareHover.vue
component-id: direction-aware-hover
config: DirectionAwareHoverConfig
demo-file: DirectionAwareHoverDemo.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){rel=""nofollow""} for porting this component.
- Ported from [Aceternity UI's Direction Aware Hover](https://ui.aceternity.com/components/direction-aware-hover){rel=""nofollow""}
::


# Fey Cards

::component-viewer
---
component-files:
  - FeyCards.vue
component-id: fey-cards
config: FeyCardsConfig
demo-file: FeyCardsDemo.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){rel=""nofollow""}.
::


# Flip Card

::component-viewer
---
component-files:
  - FlipCard.vue
component-id: flip-card
config: FlipCardConfig
demo-file: FlipCardDemo.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){rel=""nofollow""} for this component.
::


# Floating Card

::component-viewer
---
component-files:
  - FloatingCard.vue
component-id: floating-card
config: FloatingCardConfig
demo-file: FloatingCardDemo.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){rel=""nofollow""}.
::


# Glare Card

::component-viewer
---
component-files:
  - GlareCard.vue
component-id: glare-card
config: GlareCardConfig
demo-file: GlareCardDemo.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){rel=""nofollow""} for this component.
- Inspired from [Aceternity UI](https://ui.aceternity.com/components/glare-card){rel=""nofollow""}.
::


# Fluid Cursor

::component-viewer
---
component-files:
  - FluidCursor.vue
component-id: fluid-cursor
config: FluidCursorConfig
demo-file: FluidCursorDemo.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){rel=""nofollow""}
- Utilizes WebGL 1/2 context and custom GLSL shaders for fluid physics and rendering.
::


# Image Trail Cursor

::component-viewer
---
component-files:
  - ImageTrailCursor.vue
  - trail-variants.ts
component-id: image-trail-cursor
config: ImageTrailCursorConfig
demo-file: ImageTrailCursorDemo.vue
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/){rel=""nofollow""}
::


# Sleek Line Cursor

::component-viewer
---
component-files:
  - SleekLineCursor.vue
component-id: sleek-line-cursor
config: SleekLineCursorConfig
demo-file: SleekLineCursorDemo.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){rel=""nofollow""}.
::


# Smooth Cursor

::component-viewer
---
component-files:
  - SmoothCursor.vue
component-id: smooth-cursor
config: SmoothCursorConfig
demo-file: SmoothCursorDemo.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){rel=""nofollow""} for this component.
- Ported from [Magic UI Smooth Cursor](https://magicui.design/docs/components/smooth-cursor){rel=""nofollow""}.
::


# Tailed Cursor

::component-viewer
---
component-files:
  - TailedCursor.vue
component-id: tailed-cursor
config: TailedCursorConfig
demo-file: TailedCursorDemo.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){rel=""nofollow""}, a lightweight WebGL framework.
- Inspired from [Codrops Article](https://tympanus.net/codrops/2019/09/24/crafting-stylised-mouse-trails-with-ogl/){rel=""nofollow""}
::


# iPhone Mockup

::component-viewer
---
component-files:
  - iPhone15ProMockup.vue
component-id: iphone-mockup
config: iPhone15ProMockupConfig
demo-file: iPhone15ProMockupDemo.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){rel=""nofollow""}.
::


# Safari Mockup

::component-viewer
---
component-files:
  - SafariMockup.vue
component-id: safari-mockup
config: SafariMockupConfig
demo-file: SafariMockupDemo.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){rel=""nofollow""}.
::


# HTML ASCII

::component-viewer
---
component-files:
  - HtmlAscii.vue
component-id: html-ascii
config: HtmlAsciiConfig
demo-file: HtmlAsciiDemo.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){rel=""nofollow""}.
::


# HTML Blaze

::component-viewer
---
component-files:
  - HtmlBlaze.vue
component-id: html-blaze
config: HtmlBlazeConfig
demo-file: HtmlBlazeDemo.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){rel=""nofollow""}.
::


# HTML Chromatic

::component-viewer
---
component-files:
  - HtmlChromatic.vue
component-id: html-chromatic
config: HtmlChromaticConfig
demo-file: HtmlChromaticDemo.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. |
::


# HTML Cloth

::component-viewer
---
component-files:
  - HtmlCloth.vue
component-id: html-cloth
config: HtmlClothConfig
demo-file: HtmlClothDemo.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){rel=""nofollow""}.
::


# HTML Drag

::component-viewer
---
component-files:
  - HtmlDrag.vue
component-id: html-drag
config: HtmlDragConfig
demo-file: HtmlDragDemo.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. |
::


# HTML in Canvas

::component-viewer
---
component-files:
  - HtmlInCanvas.vue
  - HtmlInCanvasRenderer.ts
  - captureElement.ts
  - index.ts
component-id: html-in-canvas
config: HtmlInCanvasConfig
demo-file: HtmlInCanvasDemo.vue
---
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){rel=""nofollow""}.
::


# HTML Liquid

::component-viewer
---
component-files:
  - HtmlLiquid.vue
component-id: html-liquid
config: HtmlLiquidConfig
demo-file: HtmlLiquidDemo.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. |
::


# All Components

:components-list


# Balance Slider

::component-viewer
---
component-files:
  - BalanceSlider.vue
component-id: balance-slider
config: BalanceSliderConfig
demo-file: BalanceSliderDemo.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){rel=""nofollow""}
- Original concept by [Malay Vasa](https://x.com/MalayVasa/status/1748726374079381930){rel=""nofollow""}.
::


# Color Picker

::component-viewer
---
component-files:
  - ColorPicker.vue
  - ObjectColorInput.vue
  - ContrastRatio.vue
  - index.ts
component-id: color-picker
config: ColorPickerConfig
demo-file: ColorPickerDemo.vue
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){rel=""nofollow""} for porting this component.
- Inspired by [@uplusion23](https://21st.dev/uplusion23/color-picker/color-picker-with-swatches-and-onchange){rel=""nofollow""}.
::


# File Upload

::component-viewer
---
component-files:
  - FileUpload.vue
  - FileUploadGrid.vue
component-id: file-upload
config: FileUploadConfig
demo-file: FileUploadDemo.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){rel=""nofollow""} for porting this component.
- Inspired by [AcernityUI](https://ui.aceternity.com/components/file-upload){rel=""nofollow""}.
::


# Halo Search

::component-viewer
---
component-files:
  - HaloSearch.vue
component-id: halo-search
config: HaloSearchConfig
demo-file: HaloSearchDemo.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.
::


# Input

::component-viewer
---
component-files:
  - IInput.vue
component-id: input
config: InputConfig
demo-file: InputDemo.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){rel=""nofollow""}
::


# Placeholders And Vanish Input

::component-viewer
---
component-files:
  - VanishingInput.vue
component-id: vanishing-input
config: VanishingInputConfig
demo-file: VanishingInputDemo.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){rel=""nofollow""} for porting this component.
- Ported from [Aceternity UI's Placeholders And Vanish Input](https://ui.aceternity.com/components/placeholders-and-vanish-input){rel=""nofollow""}.
::


# Animate Grid

::component-viewer
---
component-files:
  - AnimateGrid.vue
component-id: animate-grid
config: AnimateGridConfig
demo-file: AnimateGridDemo.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){rel=""nofollow""} for providing this component.
::


# Animated Circular Progress Bar

::component-viewer
---
component-files:
  - AnimatedCircularProgressBar.vue
component-id: animated-circular-progressbar
config: AnimatedCircularProgressBarConfig
demo-file: AnimatedCircularProgressBarDemo.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){rel=""nofollow""}.
- Credits to [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} for porting this component.
::


# Animated List

::component-viewer
---
component-files:
  - AnimatedList.vue
  - Notification.vue
component-id: animated-list
config: AnimatedListConfig
demo-file: AnimatedListDemo.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){rel=""nofollow""}.
::


# Animated Modal

::component-viewer
---
component-files:
  - AnimatedModal.vue
  - AnimatedModalBody.vue
  - AnimatedModalContent.vue
  - AnimatedModalFooter.vue
  - AnimatedModalTrigger.vue
  - AnimatedModalContext.ts
  - useAnimatedModal.ts
  - index.ts
component-id: animated-modal
config: AnimatedModalConfig
demo-file: AnimatedModalDemo.vue
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){rel=""nofollow""}.
- Animations powered by [motion-v](https://motion.dev/){rel=""nofollow""}.
::


# Animated Tabs

::component-viewer
---
component-files:
  - AnimatedTabs.vue
  - AnimatedTabsFadeInDiv.vue
  - types.ts
  - index.ts
component-id: animated-tabs
config: AnimatedTabsConfig
demo-file: AnimatedTabsDemo.vue
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){rel=""nofollow""}.
- Animations powered by [motion-v](https://motion.dev/docs/vue){rel=""nofollow""}.
::


# Animated Tooltip

::component-viewer
---
component-files:
  - AnimatedTooltip.vue
component-id: animated-tooltip
config: AnimatedTooltipConfig
demo-file: AnimatedTooltipDemo.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){rel=""nofollow""} for this component.
- Inspired from [Aceternity UI's Animated Tooltip](https://ui.aceternity.com/components/animated-tooltip){rel=""nofollow""}.
::


# Bento Grid

::component-viewer
---
component-files:
  - BentoGrid.vue
  - BentoGridCard.vue
  - BentoGridItem.vue
component-id: bento-grid
config: BentoGridConfig
demo-file: BentoGridDemo.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){rel=""nofollow""} and [Magic UI](https://magicui.design/docs/components/bento-grid){rel=""nofollow""} for this fantastic component.
::


# Book

::component-viewer
---
component-files:
  - Book.vue
  - BookHeader.vue
  - BookTitle.vue
  - BookDescription.vue
  - index.ts
component-id: book
config: BookConfig
demo-file: BookDemo.vue
---
#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){rel=""nofollow""} for inspiring this component.
- Credits to [kalix127](https://github.com/kalix127){rel=""nofollow""} for porting this component.
::


# Circular Gallery

::component-viewer
---
component-files:
  - CircularGallery.vue
  - index.ts
component-id: circular-gallery
config: CircularGalleryConfig
demo-file: CircularGalleryDemo.vue
---
#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){rel=""nofollow""}.
::


# Compare

::component-viewer
---
component-files:
  - Compare.vue
  - StarField.vue
component-id: compare
config: CompareConfig
demo-file: CompareDemo.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){rel=""nofollow""} for this component.
- Inspired from [Aceternity UI's Compare](https://ui.aceternity.com/components/compare){rel=""nofollow""}.
::


# Container Scroll

::component-viewer
---
component-files:
  - ContainerScroll.vue
  - ContainerScrollTitle.vue
  - ContainerScrollCard.vue
component-id: container-scroll
config: ContainerScrollConfig
demo-file: ContainerScrollDemo.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){rel=""nofollow""}.
::


# Dock

::component-viewer
---
component-files:
  - Dock.vue
  - DockIcon.vue
  - DockSeparator.vue
  - index.ts
  - types.ts
  - injectionKeys.ts
component-id: dock
config: DockConfig
demo-file: DockDemo.vue
---
#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.
::


# Expandable Gallery

::component-viewer
---
component-files:
  - ExpandableGallery.vue
component-id: expandable-gallery
config: ExpandableGalleryConfig
demo-file: ExpandableGalleryDemo.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){rel=""nofollow""}
::


# Float

::component-viewer
---
component-files:
  - Float.vue
  - index.ts
component-id: float
config: FloatConfig
demo-file: FloatDemo.vue
---
#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){rel=""nofollow""}.
::


# Images Slider

::component-viewer
---
component-files:
  - ImagesSlider.vue
component-id: images-slider
config: ImagesSliderConfig
demo-file: ImagesSliderDemo.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){rel=""nofollow""} for porting this component.
- Credits to [Aceternity UI](https://ui.aceternity.com/components/images-slider){rel=""nofollow""} for inspiring this component.
::


# Lens

::component-viewer
---
component-files:
  - Lens.vue
  - Rays.vue
  - Beams.vue
component-id: lens
config: LensConfig
demo-file: LensDemo.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){rel=""nofollow""}.
- Credits to [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} for porting this component.
::


# Link Preview

::component-viewer
---
component-files:
  - LinkPreview.vue
component-id: link-preview
config: LinkPreviewConfig
demo-file: LinkPreviewDemo.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){rel=""nofollow""} for porting this component.
- Ported from [Aceternity UI's Link Preview](https://ui.aceternity.com/components/link-preview){rel=""nofollow""}.
::


# Marquee

::component-viewer
---
component-files:
  - Marquee.vue
  - ReviewCard.vue
component-id: marquee
config: MarqueeConfig
demo-file: MarqueeDemo.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){rel=""nofollow""}.
::


# Media Text

::component-viewer
---
component-files:
  - MediaText.vue
  - index.ts
component-id: media-text
config: MediaTextConfig
demo-file: MediaTextDemo.vue
---
#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){rel=""nofollow""}.
::


# Morphing Tabs

::component-viewer
---
component-files:
  - MorphingTabs.vue
component-id: morphing-tabs
config: MorphingTabsConfig
demo-file: MorphingTabsDemo.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){rel=""nofollow""} for this component.
- Inspired and ported from [@Preet "Exclusion tabs"](https://x.com/wickedmishra/status/1823026659894940124){rel=""nofollow""}.
::


# Multi Step Loader

::component-viewer
---
component-files:
  - MultiStepLoader.vue
component-id: multi-step-loader
config: MultiStepLoaderConfig
demo-file: MultiStepLoaderDemo.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){rel=""nofollow""} for this component.
- Inspired from [Aceternity UI's Multi Step Loader](https://ui.aceternity.com/components/multi-step-loader){rel=""nofollow""}.
::


# Parallax Float

::component-viewer
---
component-files:
  - ParallaxFloat.vue
  - ParallaxFloatElement.vue
  - ParallaxFloatContext.ts
  - index.ts
component-id: parallax-float
config: ParallaxFloatConfig
demo-file: ParallaxFloatDemo.vue
---
#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){rel=""nofollow""}.
::


# Path Marquee

::component-viewer
---
component-files:
  - PathMarquee.vue
  - index.ts
component-id: path-marquee
config: PathMarqueeConfig
demo-file: PathMarqueeDemo.vue
---
#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){rel=""nofollow""}.
::


# Photo Gallery

::component-viewer
---
component-files:
  - PhotoGallery.vue
component-id: photo-gallery
config: PhotoGalleryConfig
demo-file: PhotoGalleryDemo.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/){rel=""nofollow""}
- Thanks to [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} for providing this component.
::


# Scroll Island

::component-viewer
---
component-files:
  - ScrollIsland.vue
component-id: scroll-island
config: ScrollIslandConfig
demo-file: ScrollIslandDemo.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){rel=""nofollow""} & [Nitish Khagwal](https://x.com/nitishkmrk){rel=""nofollow""}
- [NumberFlow by Maxwell Barvian](https://number-flow.barvian.me/vue){rel=""nofollow""} for number formatting and animations.
::


# Shader Toy Viewer

::component-viewer
---
component-files:
  - ShaderToy.vue
  - InspiraShaderToy.ts
component-id: shader-toy
config: ShaderToyConfig
demo-file: ShaderToyDemo.vue
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){rel=""nofollow""}.
- Inspired by [Shadertoy](https://shadertoy.com/){rel=""nofollow""} and adapted for Vue compatibility.
::


# SVG Mask

::component-viewer
---
component-files:
  - SVGMask.vue
component-id: svg-mask
config: SvgMaskConfig
demo-file: SvgMaskDemo.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){rel=""nofollow""}.
::


# Timeline

::component-viewer
---
component-files:
  - Timeline.vue
component-id: timeline
config: TimelineConfig
demo-file: TimelineDemo.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){rel=""nofollow""}.
::


# Tracing Beam

::component-viewer
---
component-files:
  - TracingBeam.vue
component-id: tracing-beam
config: TracingBeamConfig
demo-file: TracingBeamDemo.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){rel=""nofollow""};
::


# Animated Beam

::component-viewer
---
component-files:
  - AnimatedBeam.vue
component-id: animated-beam
config: AnimatedBeamConfig
demo-file: AnimatedBeamDemo.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){rel=""nofollow""}.
::


# Border Beam

::component-viewer
---
component-files:
  - BorderBeam.vue
component-id: border-beam
config: BorderBeamConfig
demo-file: BorderBeamDemo.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){rel=""nofollow""}.
::


# Confetti

::component-viewer
---
component-files:
  - Confetti.vue
  - ConfettiButton.vue
component-id: confetti
config: ConfettiConfig
demo-file: ConfettiDemo.vue
dependencies: canvas-confetti
dev-dependencies: "@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){rel=""nofollow""} library.
- Ported from [Magic UI Confetti](https://magicui.design/docs/components/confetti){rel=""nofollow""}.
::


# Dither Shader

::component-viewer
---
component-files:
  - DitherShader.vue
component-id: dither-shader
config: DitherShaderConfig
demo-file: DitherShaderDemo.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){rel=""nofollow""}.
::


# Glow Border

::component-viewer
---
component-files:
  - GlowBorder.vue
component-id: glow-border
config: GlowBorderConfig
demo-file: GlowBorderDemo.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){rel=""nofollow""} for this fantastic component.
::


# Glowing Effect

::component-viewer
---
component-files:
  - GlowingEffect.vue
component-id: glowing-effect
config: GlowingEffectConfig
demo-file: GlowingEffectDemo.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>{rel=""nofollow""}]
::


# Images Badge

::component-viewer
---
component-files:
  - ImagesBadge.vue
component-id: images-badge
config: ImagesBadgeConfig
demo-file: ImagesBadgeDemo.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){rel=""nofollow""}
::


# Meteors

::component-viewer
---
component-files:
  - Meteors.vue
component-id: meteors
config: MeteorsConfig
demo-file: MeteorsDemo.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){rel=""nofollow""}
::


# Neon Border

::component-viewer
---
component-files:
  - NeonBorder.vue
component-id: neon-border
config: NeonBorderConfig
demo-file: NeonBorderDemo.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.
::


# Particle Image

::component-viewer
---
component-files:
  - ParticleImage.vue
  - inspiraImageParticles.js
  - inspiraImageParticles.d.ts
component-id: particle-image
config: ParticleImageConfig
demo-file: ParticleImageDemo.vue
---
#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){rel=""nofollow""} for this inspiration.
- Credits to [NextParticles](https://nextparticle.nextco.de){rel=""nofollow""} for the base of the animation library.
::


# Progressive Blur

::component-viewer
---
component-files:
  - ProgressiveBlur.vue
component-id: progressive-blur
config: ProgressiveBlurConfig
demo-file: ProgressiveBlurDemo.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){rel=""nofollow""}.
- Powered by `motion-v`
::


# Scales

::component-viewer
---
component-files:
  - Scales.vue
component-id: scales
config: ScalesConfig
demo-file: ScalesDemo.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){rel=""nofollow""}.
::


# Scratch To Reveal

::component-viewer
---
component-files:
  - ScratchToReveal.vue
component-id: scratch-to-reveal
config: ScratchToRevealConfig
demo-file: ScratchToRevealDemo.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){rel=""nofollow""} for this component.
- Inspired by [MagicUI Scratch To Reveal](https://magicui.design/docs/components/scratch-to-reveal){rel=""nofollow""}.
::


# Spring Calendar

::component-viewer
---
component-files:
  - SpringCalendar.vue
  - TextMorph.vue
component-id: spring-calendar
config: SpringCalendarConfig
demo-file: SpringCalendarDemo.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){rel=""nofollow""}
::


# Animated Testimonials

::component-viewer
---
component-files:
  - AnimatedTestimonials.vue
component-id: animated-testimonials
config: AnimatedTestimonialsConfig
demo-file: AnimatedTestimonialsDemo.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>{rel=""nofollow""}].
::


# Design Testimonials

::component-viewer
---
component-files:
  - DesignTestimonials.vue
component-id: design-testimonials
config: DesignTestimonialsConfig
demo-file: DesignTestimonialsDemo.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){rel=""nofollow""}
::


# Testimonial Slider

::component-viewer
---
component-files:
  - TestimonialSlider.vue
component-id: testimonial-slider
config: TestimonialSliderConfig
demo-file: TestimonialSliderDemo.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.      |
::


# 3D Text

::component-viewer
---
component-files:
  - Text3d.vue
component-id: text-3d
config: Text3dConfig
demo-file: Text3dDemo.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.  |
::


# Blur Reveal

::component-viewer
---
component-files:
  - BlurReveal.vue
component-id: blur-reveal
config: BlurRevealConfig
demo-file: BlurRevealDemo.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){rel=""nofollow""} for this fantastic component.
::


# Box Reveal

::component-viewer
---
component-files:
  - BoxReveal.vue
component-id: box-reveal
config: BoxRevealConfig
demo-file: BoxRevealDemo.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){rel=""nofollow""}.
::


# Breathing Text

::component-viewer
---
component-files:
  - BreathingText.vue
  - index.ts
component-id: breathing-text
config: BreathingTextConfig
demo-file: BreathingTextDemo.vue
---
#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){rel=""nofollow""}.
::


# Colourful Text

::component-viewer
---
component-files:
  - ColourfulText.vue
component-id: colourful-text
config: ColourfulTextConfig
demo-file: ColourfulTextDemo.vue
---
#api
## API

| Prop Name    | Type       | Default                                                                                                                                                                                                            | Description                                                                                                                                               |
| ------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`       | `string`   | `"black"`                                                                                                                                                                                                          | The text string to be rendered with colorful animated characters. Each character will be individually animated with color transitions and motion effects. |
| `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)", ]` | The text use colors.                                                                                                                                      |
| `startColor` | `string`   | `"rgb(255,255,255)"`                                                                                                                                                                                               | The char start color.                                                                                                                                     |
| `duration`   | `number`   | `5`                                                                                                                                                                                                                | The animation duration time in seconds.                                                                                                                   |

#credits
- Credits to [Whbbit1999](https://github.com/Whbbit1999){rel=""nofollow""} for this component.
- Ported from [Aceternity UI Colourful Text](https://ui.aceternity.com/components/colourful-text){rel=""nofollow""}
::


# Container Text Flip

::component-viewer
---
component-files:
  - ContainerTextFlip.vue
component-id: container-text-flip
config: ContainerTextFlipConfig
demo-file: ContainerTextFlipDemo.vue
---
#api
## API

| Prop Name           | Type       | Default                                        | Description                                          |
| ------------------- | ---------- | ---------------------------------------------- | ---------------------------------------------------- |
| `words`             | `string[]` | `["better", "modern", "beautiful", "awesome"]` | Array of words to cycle through in the animation     |
| `interval`          | `number`   | `3000`                                         | Time in milliseconds between word transitions        |
| `animationDuration` | `number`   | `700`                                          | Duration of the transition animation in milliseconds |
| `class`             | `string`   | \`\`                                           | Additional CSS classes to apply to the container     |
| `textClass`         | `string`   | \`\`                                           | Additional CSS classes to apply to the text          |

#credits
- Credits to [Whbbit1999](https://github.com/Whbbit1999){rel=""nofollow""} for this component.
- Ported from [Aceternity UI Container Text Flip](https://ui.aceternity.com/components/container-text-flip){rel=""nofollow""}.
::


# Encrypted Text

::component-viewer
---
component-files:
  - EncryptedText.vue
component-id: encrypted-text
config: EncryptedTextConfig
demo-file: EncryptedTextDemo.vue
---
#api
## API

| Prop Name        | Type     | Default                                  | Description                                                  |
| ---------------- | -------- | ---------------------------------------- | ------------------------------------------------------------ |
| `text`           | `string` | **required**                             | The text to render and reveal.                               |
| `class`          | `string` | `""`                                     | Base class applied to the wrapper element.                   |
| `revealDelayMs`  | `number` | `50`                                     | Delay (in ms) between revealing each next character.         |
| `flipDelayMs`    | `number` | `50`                                     | Delay (in ms) between re-scrambling unrevealed characters.   |
| `charset`        | `string` | `A–Z a–z 0–9 !@#$%^&*()_+-={}[];:,.<>/?` | Character set used for the scrambled glyphs.                 |
| `encryptedClass` | `string` | `""`                                     | Class applied to characters while still encrypted/scrambled. |
| `revealedClass`  | `string` | `""`                                     | Class applied to characters once revealed.                   |

#credits
- Ported from [Aceternity UI Encrypted Text](https://ui.aceternity.com/components/encrypted-text){rel=""nofollow""}.
- Animation powered by `motion-v`.
::


# 适用于 Vue 和 Nuxt 的动画组件。



# 入门指南

欢迎来到 [**Inspira UI**](https://inspira-ui.com){rel="&#x22;nofollow&#x22;"}，一个为 [Vue](https://vuejs.org){rel="&#x22;nofollow&#x22;"} 开发的社区驱动项目！

这个集合提供了精美设计的可复用组件，灵感来自 [Aceternity UI](https://ui.aceternity.com){rel="&#x22;nofollow&#x22;"} 和 [Magic UI](https://magicui.design){rel="&#x22;nofollow&#x22;"} 所做的令人惊艳的工作。虽然我们与这些项目没有官方联系，但我们已获得 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){rel="&#x22;nofollow&#x22;"}
- 高度 [可配置](https://inspira-ui.com/cn/components) 以满足您的设计需求
- 范围广泛的 [组件](https://inspira-ui.com/cn/components) 可供选择
- 为移动使用优化
- 与 Nuxt 完全兼容

### 致谢

特别感谢：

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

### 关于我

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

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


# 安装

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

::warning
如果你正在使用 Tailwind CSS v3，

**[请在这里查看 Inspira UI v1](https://v1.inspira-ui.com){rel=""nofollow""}。**
::

## 开始使用 Inspira UI

::steps
### 配置 `tailwindcss`

首先，请按照 [此指南](https://tailwindcss.com/docs/installation){rel=""nofollow""} 安装 `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){rel=""nofollow""} 中配置 `motion-v`。

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

  :::tip
  如果你正在使用 

  `shadcn-vue`

   或 ，可以跳过此步骤
  :::

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

  :::tabs{.w-full}
    ::::tabs-item{icon="simple-icons:nuxt" label="Nuxt UI"}
      :::::code-collapse
      ```css [main.css]
      @import "tailwindcss";
      @import "@nuxt/ui";

      @theme static {
        --color-background: var(--ui-bg);
        --color-foreground: var(--ui-text);

        --color-card: var(--ui-bg-elevated);
        --color-card-foreground: var(--ui-text);

        --color-popover: var(--ui-bg-elevated);
        --color-popover-foreground: var(--ui-text);

        --color-muted: var(--ui-bg-muted);
        --color-muted-foreground: var(--ui-text-muted);

        --color-accent: var(--ui-bg-accented);
        --color-accent-foreground: var(--ui-text);

        --color-border: var(--ui-border);
        --color-input: var(--ui-border);

        --color-primary: var(--ui-primary);
        --color-primary-foreground: var(--ui-text-inverted);

        --color-secondary: var(--ui-secondary);
        --color-secondary-foreground: var(--ui-text-inverted);

        --color-destructive: var(--ui-error);
        --color-destructive-foreground: var(--ui-text-inverted);

        --color-ring: var(--ui-primary);

        --radius: var(--ui-radius);
      }

      :root {
        --background: var(--ui-bg);
        --foreground: var(--ui-text);

        --card: var(--ui-bg-elevated);
        --card-foreground: var(--ui-text);

        --popover: var(--ui-bg-elevated);
        --popover-foreground: var(--ui-text);

        --muted: var(--ui-bg-muted);
        --muted-foreground: var(--ui-text-muted);

        --accent: var(--ui-bg-accented);
        --accent-foreground: var(--ui-text);

        --border: var(--ui-border);
        --input: var(--ui-border);

        --primary: var(--ui-primary);
        --primary-foreground: var(--ui-text-inverted);

        --secondary: var(--ui-secondary);
        --secondary-foreground: var(--ui-text-inverted);

        --destructive: var(--ui-error);
        --destructive-foreground: var(--ui-text-inverted);

        --ring: var(--ui-primary);
      }
      ```
      :::::
    ::::

    ::::tabs-item{icon="simple-icons:tailwindcss" label="Other TailwindCSS Kit"}
      :::::code-collapse
      ```css [main.css]
      @import "tailwindcss";
      @import "tw-animate-css";

      @custom-variant dark (&:is(.dark *));

      :root {
        --card: oklch(1 0 0);
        --card-foreground: oklch(0.141 0.005 285.823);
        --popover: oklch(1 0 0);
        --popover-foreground: oklch(0.141 0.005 285.823);
        --primary: oklch(0.21 0.006 285.885);
        --primary-foreground: oklch(0.985 0 0);
        --secondary: oklch(0.967 0.001 286.375);
        --secondary-foreground: oklch(0.21 0.006 285.885);
        --muted: oklch(0.967 0.001 286.375);
        --muted-foreground: oklch(0.552 0.016 285.938);
        --accent: oklch(0.967 0.001 286.375);
        --accent-foreground: oklch(0.21 0.006 285.885);
        --destructive: oklch(0.577 0.245 27.325);
        --destructive-foreground: oklch(0.577 0.245 27.325);
        --border: oklch(0.92 0.004 286.32);
        --input: oklch(0.92 0.004 286.32);
        --ring: oklch(0.705 0.015 286.067);
        --radius: 0.625rem;
        --background: oklch(1 0 0);
        --foreground: oklch(0.141 0.005 285.823);
      }

      .dark {
        --background: oklch(0.141 0.005 285.823);
        --foreground: oklch(0.985 0 0);
        --card: oklch(0.141 0.005 285.823);
        --card-foreground: oklch(0.985 0 0);
        --popover: oklch(0.141 0.005 285.823);
        --popover-foreground: oklch(0.985 0 0);
        --primary: oklch(0.985 0 0);
        --primary-foreground: oklch(0.21 0.006 285.885);
        --secondary: oklch(0.274 0.006 286.033);
        --secondary-foreground: oklch(0.985 0 0);
        --muted: oklch(0.274 0.006 286.033);
        --muted-foreground: oklch(0.705 0.015 286.067);
        --accent: oklch(0.274 0.006 286.033);
        --accent-foreground: oklch(0.985 0 0);
        --destructive: oklch(0.396 0.141 25.723);
        --destructive-foreground: oklch(0.637 0.237 25.331);
        --border: oklch(0.274 0.006 286.033);
        --input: oklch(0.274 0.006 286.033);
        --ring: oklch(0.442 0.017 285.786);
      }

      @theme inline {
        --color-background: var(--background);
        --color-foreground: var(--foreground);
        --color-card: var(--card);
        --color-card-foreground: var(--card-foreground);
        --color-popover: var(--popover);
        --color-popover-foreground: var(--popover-foreground);
        --color-primary: var(--primary);
        --color-primary-foreground: var(--primary-foreground);
        --color-secondary: var(--secondary);
        --color-secondary-foreground: var(--secondary-foreground);
        --color-muted: var(--muted);
        --color-muted-foreground: var(--muted-foreground);
        --color-accent: var(--accent);
        --color-accent-foreground: var(--accent-foreground);
        --color-destructive: var(--destructive);
        --color-destructive-foreground: var(--destructive-foreground);
        --color-border: var(--border);
        --color-input: var(--input);
        --color-ring: var(--ring);

        --radius-sm: calc(var(--radius) - 4px);
        --radius-md: calc(var(--radius) - 2px);
        --radius-lg: var(--radius);
        --radius-xl: calc(var(--radius) + 4px);
      }

      @layer base {
        * {
          @apply border-border outline-ring/50;
        }
        body {
          @apply bg-background text-foreground;
        }
      }

      html {
        color-scheme: light dark;
      }
      html.dark {
        color-scheme: dark;
      }
      html.light {
        color-scheme: light;
      }
      ```
      :::::
    ::::
  :::
::

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

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

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

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

### 开始使用 Inspira UI 🚀

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


# 如何贡献

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

## 目录

1. [入门](https://inspira-ui.com/#%E5%85%A5%E9%97%A8)
2. [行为准则](https://inspira-ui.com/#%E8%A1%8C%E4%B8%BA%E5%87%86%E5%88%99)
3. [如何贡献](https://inspira-ui.com/#%E5%A6%82%E4%BD%95%E8%B4%A1%E7%8C%AE)
   - [报告 Bug](https://inspira-ui.com/#%E6%8A%A5%E5%91%8A-bug)
   - [建议改进](https://inspira-ui.com/#%E5%BB%BA%E8%AE%AE%E6%94%B9%E8%BF%9B)
   - [添加新组件](https://inspira-ui.com/#%E6%B7%BB%E5%8A%A0%E6%96%B0%E7%BB%84%E4%BB%B6)
4. [项目结构](https://inspira-ui.com/#%E9%A1%B9%E7%9B%AE%E7%BB%93%E6%9E%84)
5. [风格指南](https://inspira-ui.com/#%E9%A3%8E%E6%A0%BC%E6%8C%87%E5%8D%97)
   - [编码标准](https://inspira-ui.com/#%E7%BC%96%E7%A0%81%E6%A0%87%E5%87%86)
   - [组件格式](https://inspira-ui.com/#%E7%BB%84%E4%BB%B6%E6%A0%BC%E5%BC%8F)
   - [提交消息](https://inspira-ui.com/#%E6%8F%90%E4%BA%A4%E6%B6%88%E6%81%AF)
6. [文档指南](https://inspira-ui.com/#%E6%96%87%E6%A1%A3%E6%8C%87%E5%8D%97)
   - [单文件组件](https://inspira-ui.com/#%E5%8D%95%E6%96%87%E4%BB%B6%E7%BB%84%E4%BB%B6)
   - [多文件组件](https://inspira-ui.com/#%E5%A4%9A%E6%96%87%E4%BB%B6%E7%BB%84%E4%BB%B6)
7. [测试](https://inspira-ui.com/#%E6%B5%8B%E8%AF%95)
8. [许可证](https://inspira-ui.com/#%E8%AE%B8%E5%8F%AF%E8%AF%81)

---

## 入门

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

## 行为准则

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

## 如何贡献

### 报告 Bug

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

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

### 建议改进

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

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

### 添加新组件

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

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

#### 组件指南

1. **创建或更新 `index.ts`**:br`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 外部使用该组件时可能存在限制或额外步骤。 :br 这确保用户可以通过 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";
   // 包含所有导入明确
   ```


# 行为准则

## 简介

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

## 我们的承诺

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

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

## 预期行为

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

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

## 不可接受行为

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

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

## 报告指南

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

[Inspira UI Discord 频道](https://discord.gg/Xbh5DwJRc9){rel="&#x22;nofollow&#x22;"}

在报告事件时，请包括：

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

所有报告将被保密处理。

## 实施

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

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

## 范围

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

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

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

## 上诉流程

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

## 隐私

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

## 致谢

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

## 联系信息

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

[Inspira UI Discord 频道](https://discord.gg/Xbh5DwJRc9){rel="&#x22;nofollow&#x22;"}


# 极光背景

::component-viewer
---
component-files:
  - AuroraBackground.vue
component-id: aurora-background
config: AuroraBackgroundConfig
demo-file: AuroraBackgroundDemo.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){rel=""nofollow""}。
- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} 移植该组件。
::


# 黑洞背景

::component-viewer
---
component-files:
  - BlackHoleBackground.vue
component-id: bg-black-hole
config: BlackHoleBackgroundConfig
demo-file: BlackHoleBackgroundDemo.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` 仅作装饰。
::


# 气泡背景

::component-viewer
---
component-files:
  - BubblesBg.vue
component-id: bg-bubbles
config: BubblesBgConfig
demo-file: BubblesBgDemo.vue
dependencies: three
dev-dependencies: "@types/three"
---
#api
## API

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

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


# 宇宙传送门

::component-viewer
---
component-files:
  - CosmicPortal.vue
component-id: cosmic-portal
config: CosmicPortalConfig
demo-file: CosmicPortalDemo.vue
dependencies: three postprocessing
dev-dependencies: "@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_){rel=""nofollow""}。
::


# 流星背景

::component-viewer
---
component-files:
  - FallingStarsBg.vue
component-id: bg-falling-stars
config: FallingStarsBgConfig
demo-file: FallingStarsBgDemo.vue
---
#api
## API

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

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


# 闪烁网格

::component-viewer
---
component-files:
  - FlickeringGrid.vue
component-id: flickering-grid
config: FlickeringGridConfig
demo-file: FlickeringGridDemo.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){rel=""nofollow""} 组件。
::


# 交互网格图案

::component-viewer
---
component-files:
  - InteractiveGridPattern.vue
component-id: interactive-grid-pattern
config: InteractiveGridPatternConfig
demo-file: InteractiveGridPatternDemo.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){rel=""nofollow""}。
- 感谢 [kalix127](https://github.com/kalix127){rel=""nofollow""} 移植该组件。
::


# 灯光效果

::component-viewer
---
component-files:
  - LampEffect.vue
component-id: lamp-effect
config: LampEffectConfig
demo-file: LampEffectDemo.vue
---
#api
## API

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

#credits
- 移植自 [Aceternity UI](https://ui.aceternity.com/components/lamp-effect){rel=""nofollow""}
::


# 液态背景

::component-viewer
---
component-files:
  - LiquidBackground.vue
component-id: liquid-background
config: LiquidBackgroundConfig
demo-file: LiquidBackgroundDemo.vue
dependencies: ogl
---
#api
## API

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

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


# 神经网络背景

::component-viewer
---
component-files:
  - NeuralBg.vue
component-id: bg-neural
config: NeuralBgConfig
demo-file: NeuralBgDemo.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){rel=""nofollow""} 构建。
- 数学与图案逻辑源自递归三角函数叠加。
- 移植自 [Cursify 的 Neural Glow Cursor](https://cursify.vercel.app/components/neural-glow){rel=""nofollow""}。
::


# 粒子漩涡

::component-viewer
---
component-files:
  - ParticleWhirlpoolBg.vue
component-id: bg-particle-whirlpool
config: ParticleWhirlpoolBgConfig
demo-file: ParticleWhirlpoolBgDemo.vue
dependencies: three postprocessing
dev-dependencies: "@types/three"
---
#api
## API

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

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


# 粒子背景

::component-viewer
---
component-files:
  - ParticlesBg.vue
component-id: particles-bg
config: ParticlesBgConfig
demo-file: ParticlesBgDemo.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){rel=""nofollow""} 提供该组件。
- 感谢 [Prodromos Pantos](https://github.com/prpanto){rel=""nofollow""} 将原组件移植到 Vue & Nuxt。
::


# 图案背景

::component-viewer
---
component-files:
  - PatternBackground.vue
  - index.ts
component-id: pattern-background
config: PatternBackgroundConfig
demo-file: PatternBackgroundDemo.vue
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){rel=""nofollow""}。
- 灵感来自 [Magic UI 的 Grid Pattern](https://magicui.design/docs/components/grid-pattern){rel=""nofollow""}。
- 灵感来自 [Magic UI 的 Animated Grid Pattern](https://magicui.design/docs/components/animated-grid-pattern){rel=""nofollow""}。
- 感谢 [Nathan De Pachtere](https://nathandepachtere.com/){rel=""nofollow""} 移植该组件。
::


# 丝带背景

::component-viewer
---
component-files:
  - RibbonBackground.vue
component-id: ribbon-background
config: RibbonBackgroundConfig
demo-file: RibbonBackgroundDemo.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){rel=""nofollow""} 渲染。
::


# 涟漪

::component-viewer
---
component-files:
  - Ripple.vue
  - RippleCircle.vue
  - RippleContainer.vue
component-id: ripple
config: RippleConfig
demo-file: RippleDemo.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){rel=""nofollow""}。
- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} 移植该组件。
- 感谢 [Nathan De Pachtere](https://nathandepachtere.com/){rel=""nofollow""} 更新该组件。
::


# 丝绸背景

::component-viewer
---
component-files:
  - SilkBackground.vue
component-id: bg-silk
config: SilkBackgroundConfig
demo-file: SilkBackgroundDemo.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){rel=""nofollow""} 的着色器（MIT License）。
- 灵感来自丝绸纹理与自然流动的运动模式。
::


# 奇点背景

::component-viewer
---
component-files:
  - SingularityBackground.vue
component-id: bg-singularity
config: SingularityBackgroundConfig
demo-file: SingularityBackgroundDemo.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){rel=""nofollow""}。
::


# 雪花背景

::component-viewer
---
component-files:
  - SnowfallBg.vue
component-id: snowfall-bg
config: SnowfallBgConfig
demo-file: SnowfallBgDemo.vue
---
#api
## API

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

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


# 闪光

::component-viewer
---
component-files:
  - Sparkles.vue
component-id: sparkles
config: SparklesConfig
demo-file: SparklesDemo.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){rel=""nofollow""} 移植该组件。
- 移植自 [Aceternity UI 的 Sparkles](https://ui.aceternity.com/components/sparkles){rel=""nofollow""}。
::


# 星空背景

::component-viewer
---
component-files:
  - StarsBackground.vue
component-id: bg-stars
config: StarsBackgroundConfig
demo-file: StarsBackgroundDemo.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){rel=""nofollow""}
::


# Stractium 背景

::component-viewer
---
component-files:
  - StractiumBackground.vue
component-id: bg-stractium
config: StractiumBackgroundConfig
demo-file: StractiumBackgroundDemo.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 组件并适配动态输入。
- 灵感来自分形纹理、自然纹理与高级光线步进技术。
::


# 俄罗斯方块

::component-viewer
---
component-files:
  - Tetris.vue
component-id: tetris
config: TetrisConfig
demo-file: TetrisDemo.vue
dependencies: theme-colors
---
#api
## API

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

#credits
- 感谢 [Whbbit1999](https://github.com/Whbbit1999){rel=""nofollow""} 提供该组件。
- 灵感并移植自 [Nuxt UI Home](https://ui2.nuxt.com/){rel=""nofollow""}。
::


# 雷暴背景

::component-viewer
---
component-files:
  - ThunderstormBackground.vue
component-id: bg-thunderstorm
config: ThunderstormBackgroundConfig
demo-file: ThunderstormBackgroundDemo.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){rel=""nofollow""}。
::


# 视频文字

::component-viewer
---
component-files:
  - VideoText.vue
component-id: video-text
config: VideoTextConfig
demo-file: VideoTextDemo.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){rel=""nofollow""} 提供该组件。
- 移植自 [Magic UI 的 Video Text](https://magicui.design/docs/components/video-text){rel=""nofollow""}。
::


# 漩涡背景

::component-viewer
---
component-files:
  - Vortex.vue
component-id: vortex
config: VortexConfig
demo-file: VortexDemo.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){rel=""nofollow""}。
- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} 移植该组件。
::


# 扭曲背景

::component-viewer
---
component-files:
  - WarpBackground.vue
  - Beam.vue
component-id: warp-background
config: WarpBackgroundConfig
demo-file: WarpBackgroundDemo.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){rel=""nofollow""} 提供该组件。
- 灵感并移植自 [Magic UI WarpBackground](https://magicui.design/docs/components/warp-background){rel=""nofollow""}。
::


# 波浪背景

::component-viewer
---
component-files:
  - WavyBackground.vue
component-id: wavy-background
config: WavyBackgroundConfig
demo-file: WavyBackgroundDemo.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){rel=""nofollow""}。
- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} 移植该组件。
::


# 渐变按钮

::component-viewer
---
component-files:
  - GradientButton.vue
component-id: gradient-button
config: GradientButtonConfig
demo-file: GradientButtonDemo.vue
---
#api
## API

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


# 交互悬停按钮

::component-viewer
---
component-files:
  - InteractiveHoverButton.vue
component-id: interactive-hover-button
config: InteractiveHoverButtonConfig
demo-file: InteractiveHoverButtonDemo.vue
---
#api
## API

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

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


# 彩虹按钮

::component-viewer
---
component-files:
  - RainbowButton.vue
component-id: rainbow-button
config: RainbowButtonConfig
demo-file: RainbowButtonDemo.vue
---
#api
## API

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

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


# 波纹按钮

::component-viewer
---
component-files:
  - RippleButton.vue
component-id: ripple-button
config: RippleButtonConfig
demo-file: RippleButtonDemo.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){rel=""nofollow""} 组件。
- 感谢 [kalix127](https://github.com/kalix127){rel=""nofollow""} 对该组件的移植。
::


# 闪光按钮

::component-viewer
---
component-files:
  - ShimmerButton.vue
component-id: shimmer-button
config: ShimmerButtonConfig
demo-file: ShimmerButtonDemo.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){rel=""nofollow""}。
::


# 3D 卡片效果

::component-viewer
---
component-files:
  - CardContainer.vue
  - CardBody.vue
  - CardItem.vue
  - useMouseState.ts
component-id: card-3d
config: Card3dConfig
demo-file: CardDemo.vue
---
#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 组件。
::


# Apple 卡片轮播

::component-viewer
---
component-files:
  - AppleCardCarousel.vue
  - AppleCarouselItem.vue
  - AppleCard.vue
  - AppleBlurImage.vue
  - AppleCarouselContext.ts
component-id: apple-card-carousel
config: AppleCardCarouselConfig
demo-file: AppleCardCarouselDemo.vue
---
#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){rel=""nofollow""}。
::


# 卡片聚光效果

::component-viewer
---
component-files:
  - CardSpotlight.vue
component-id: card-spotlight
config: CardSpotlightConfig
demo-file: CardSpotlightDemo.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){rel=""nofollow""} 的 Magic Card 组件。
::


# 卡片堆叠

::component-viewer
---
component-files:
  - CardStack.vue
  - CardStackItem.vue
  - CardStackContext.ts
  - index.ts
component-id: card-stack
config: CardStackConfig
demo-file: CardStackDemo.vue
---
#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){rel=""nofollow""}。
::


# 立方体轮播

::component-viewer
---
component-files:
  - CubeCarousel.vue
  - index.ts
component-id: cube-carousel
config: CubeCarouselConfig
demo-file: CubeCarouselDemo.vue
---
#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){rel=""nofollow""}。
- Demo 图片来自 [Daniel Petho](https://www.cosmos.so/danielpetho/box-carousel-demo){rel=""nofollow""}。
- 灵感来自 [Framer University](https://framer.university/resources/3d-box-carousel-in-framer){rel=""nofollow""}。
::


# 方向感知悬停卡片

::component-viewer
---
component-files:
  - DirectionAwareHover.vue
component-id: direction-aware-hover
config: DirectionAwareHoverConfig
demo-file: DirectionAwareHoverDemo.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){rel=""nofollow""} 移植该组件。
- 移植自 [Aceternity UI 的 Direction Aware Hover](https://ui.aceternity.com/components/direction-aware-hover){rel=""nofollow""}。
::


# Fey Cards

::component-viewer
---
component-files:
  - FeyCards.vue
component-id: fey-cards
config: FeyCardsConfig
demo-file: FeyCardsDemo.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){rel=""nofollow""}。
::


# 翻转卡片

::component-viewer
---
component-files:
  - FlipCard.vue
component-id: flip-card
config: FlipCardConfig
demo-file: FlipCardDemo.vue
---
#api
## API

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

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

#credits
- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} 提供该组件。
::


# Floating Card

::component-viewer
---
component-files:
  - FloatingCard.vue
component-id: floating-card
config: FloatingCardConfig
demo-file: FloatingCardDemo.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){rel=""nofollow""}。
::


# 高光卡片

::component-viewer
---
component-files:
  - GlareCard.vue
component-id: glare-card
config: GlareCardConfig
demo-file: GlareCardDemo.vue
---
#api
## API

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

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


# 流体光标

::component-viewer
---
component-files:
  - FluidCursor.vue
component-id: fluid-cursor
config: FluidCursorConfig
demo-file: FluidCursorDemo.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){rel=""nofollow""}。
- 使用 WebGL 1/2 上下文与自定义 GLSL 着色器实现流体物理与渲染。
::


# 图像尾迹光标

::component-viewer
---
component-files:
  - ImageTrailCursor.vue
  - trail-variants.ts
component-id: image-trail-cursor
config: ImageTrailCursorConfig
demo-file: ImageTrailCursorDemo.vue
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/){rel=""nofollow""}。
::


# 流线光标

::component-viewer
---
component-files:
  - SleekLineCursor.vue
component-id: sleek-line-cursor
config: SleekLineCursorConfig
demo-file: SleekLineCursorDemo.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){rel=""nofollow""}。
::


# 平滑光标

::component-viewer
---
component-files:
  - SmoothCursor.vue
component-id: smooth-cursor
config: SmoothCursorConfig
demo-file: SmoothCursorDemo.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){rel=""nofollow""} 提供该组件。
- 移植自 [Magic UI Smooth Cursor](https://magicui.design/docs/components/smooth-cursor){rel=""nofollow""}。
::


# 尾迹光标

::component-viewer
---
component-files:
  - TailedCursor.vue
component-id: tailed-cursor
config: TailedCursorConfig
demo-file: TailedCursorDemo.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){rel=""nofollow""} 构建。
- 灵感来自 [Codrops 文章](https://tympanus.net/codrops/2019/09/24/crafting-stylised-mouse-trails-with-ogl/){rel=""nofollow""}。
::


# iPhone 模型

::component-viewer
---
component-files:
  - iPhone15ProMockup.vue
component-id: iphone-mockup
config: iPhone15ProMockupConfig
demo-file: iPhone15ProMockupDemo.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){rel=""nofollow""}。
::


# Safari 模型

::component-viewer
---
component-files:
  - SafariMockup.vue
component-id: safari-mockup
config: SafariMockupConfig
demo-file: SafariMockupDemo.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){rel=""nofollow""}。
::


# HTML ASCII

::component-viewer
---
component-files:
  - HtmlAscii.vue
component-id: html-ascii
config: HtmlAsciiConfig
demo-file: HtmlAsciiDemo.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){rel=""nofollow""}。
::


# HTML 火焰

::component-viewer
---
component-files:
  - HtmlBlaze.vue
component-id: html-blaze
config: HtmlBlazeConfig
demo-file: HtmlBlazeDemo.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){rel=""nofollow""} 的 MIT 许可 Simplex Noise 实现。
::


# HTML 色差

::component-viewer
---
component-files:
  - HtmlChromatic.vue
component-id: html-chromatic
config: HtmlChromaticConfig
demo-file: HtmlChromaticDemo.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 内容。 |
::


# HTML 布料

::component-viewer
---
component-files:
  - HtmlCloth.vue
component-id: html-cloth
config: HtmlClothConfig
demo-file: HtmlClothDemo.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){rel=""nofollow""} 的作品。
::


# HTML 拖拽

::component-viewer
---
component-files:
  - HtmlDrag.vue
component-id: html-drag
config: HtmlDragConfig
demo-file: HtmlDragDemo.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 内容。 |
::


# HTML in Canvas

::component-viewer
---
component-files:
  - HtmlInCanvas.vue
  - HtmlInCanvasRenderer.ts
  - captureElement.ts
  - index.ts
component-id: html-in-canvas
config: HtmlInCanvasConfig
demo-file: HtmlInCanvasDemo.vue
---
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){rel=""nofollow""} 构建。
::


# HTML 液体

::component-viewer
---
component-files:
  - HtmlLiquid.vue
component-id: html-liquid
config: HtmlLiquidConfig
demo-file: HtmlLiquidDemo.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 内容。 |
::


# 所有组件

:components-list


# 平衡滑块

::component-viewer
---
component-files:
  - BalanceSlider.vue
component-id: balance-slider
config: BalanceSliderConfig
demo-file: BalanceSliderDemo.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){rel=""nofollow""}。
- 原始概念由 [Malay Vasa](https://x.com/MalayVasa/status/1748726374079381930){rel=""nofollow""} 提出。
::


# 取色器

::component-viewer
---
component-files:
  - ColorPicker.vue
  - ObjectColorInput.vue
  - ContrastRatio.vue
  - index.ts
component-id: color-picker
config: ColorPickerConfig
demo-file: ColorPickerDemo.vue
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){rel=""nofollow""} 移植该组件。
- 灵感来自 [@uplusion23](https://21st.dev/uplusion23/color-picker/color-picker-with-swatches-and-onchange){rel=""nofollow""}。
::


# 文件上传

::component-viewer
---
component-files:
  - FileUpload.vue
  - FileUploadGrid.vue
component-id: file-upload
config: FileUploadConfig
demo-file: FileUploadDemo.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){rel=""nofollow""} 移植该组件。
- 灵感来自 [AcernityUI](https://ui.aceternity.com/components/file-upload){rel=""nofollow""}。
::


# 光晕搜索框

::component-viewer
---
component-files:
  - HaloSearch.vue
component-id: halo-search
config: HaloSearchConfig
demo-file: HaloSearchDemo.vue
---
#api
## API

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

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


# 输入框

::component-viewer
---
component-files:
  - IInput.vue
component-id: input
config: InputConfig
demo-file: InputDemo.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){rel=""nofollow""}。
::


# 占位符滚动与消失输入框

::component-viewer
---
component-files:
  - VanishingInput.vue
component-id: vanishing-input
config: VanishingInputConfig
demo-file: VanishingInputDemo.vue
---
#api
## API

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

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

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

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


# 动画网格

::component-viewer
---
component-files:
  - AnimateGrid.vue
component-id: animate-grid
config: AnimateGridConfig
demo-file: AnimateGridDemo.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){rel=""nofollow""} 提供该组件。
::


# 动画圆形进度条

::component-viewer
---
component-files:
  - AnimatedCircularProgressBar.vue
component-id: animated-circular-progressbar
config: AnimatedCircularProgressBarConfig
demo-file: AnimatedCircularProgressBarDemo.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){rel=""nofollow""}。
- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} 移植该组件。
::


# 动画列表

::component-viewer
---
component-files:
  - AnimatedList.vue
  - Notification.vue
component-id: animated-list
config: AnimatedListConfig
demo-file: AnimatedListDemo.vue
---
#api
## API

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

#credits
- 灵感来自 [Magic UI](https://magicui.design/docs/components/animated-list){rel=""nofollow""}。
::


# Animated Modal

::component-viewer
---
component-files:
  - AnimatedModal.vue
  - AnimatedModalBody.vue
  - AnimatedModalContent.vue
  - AnimatedModalFooter.vue
  - AnimatedModalTrigger.vue
  - AnimatedModalContext.ts
  - useAnimatedModal.ts
  - index.ts
component-id: animated-modal
config: AnimatedModalConfig
demo-file: AnimatedModalDemo.vue
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){rel=""nofollow""}。
- 动画基于 [motion-v](https://motion.dev/){rel=""nofollow""}。
::


# Animated Tabs

::component-viewer
---
component-files:
  - AnimatedTabs.vue
  - AnimatedTabsFadeInDiv.vue
  - types.ts
  - index.ts
component-id: animated-tabs
config: AnimatedTabsConfig
demo-file: AnimatedTabsDemo.vue
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){rel=""nofollow""}。
- 动画由 [motion-v](https://motion.dev/docs/vue){rel=""nofollow""} 提供支持。
::


# 动画提示

::component-viewer
---
component-files:
  - AnimatedTooltip.vue
component-id: animated-tooltip
config: AnimatedTooltipConfig
demo-file: AnimatedTooltipDemo.vue
---
#api
## API

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

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


# Bento 网格

::component-viewer
---
component-files:
  - BentoGrid.vue
  - BentoGridCard.vue
  - BentoGridItem.vue
component-id: bento-grid
config: BentoGridConfig
demo-file: BentoGridDemo.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){rel=""nofollow""} 与 [Magic UI](https://magicui.design/docs/components/bento-grid){rel=""nofollow""} 的出色组件。
::


# 书本

::component-viewer
---
component-files:
  - Book.vue
  - BookHeader.vue
  - BookTitle.vue
  - BookDescription.vue
  - index.ts
component-id: book
config: BookConfig
demo-file: BookDemo.vue
---
#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){rel=""nofollow""} 带来的灵感。
- 感谢 [kalix127](https://github.com/kalix127){rel=""nofollow""} 移植该组件。
::


# 环形画廊

::component-viewer
---
component-files:
  - CircularGallery.vue
  - index.ts
component-id: circular-gallery
config: CircularGalleryConfig
demo-file: CircularGalleryDemo.vue
---
#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){rel=""nofollow""}。
::


# 对比

::component-viewer
---
component-files:
  - Compare.vue
  - StarField.vue
component-id: compare
config: CompareConfig
demo-file: CompareDemo.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){rel=""nofollow""} 提供该组件。
- 灵感来自 [Aceternity UI's Compare](https://ui.aceternity.com/components/compare){rel=""nofollow""}。
::


# 容器滚动

::component-viewer
---
component-files:
  - ContainerScroll.vue
  - ContainerScrollTitle.vue
  - ContainerScrollCard.vue
component-id: container-scroll
config: ContainerScrollConfig
demo-file: ContainerScrollDemo.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){rel=""nofollow""}。
::


# Dock

::component-viewer
---
component-files:
  - Dock.vue
  - DockIcon.vue
  - DockSeparator.vue
  - index.ts
  - types.ts
  - injectionKeys.ts
component-id: dock
config: DockConfig
demo-file: DockDemo.vue
---
#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 及其出色的悬停放大效果。
::


# 可扩展画廊

::component-viewer
---
component-files:
  - ExpandableGallery.vue
component-id: expandable-gallery
config: ExpandableGalleryConfig
demo-file: ExpandableGalleryDemo.vue
---
#api
## API

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

#credits
- 灵感来自 [David Mráz 的 Expandable Gallery](https://x.com/davidm_ml/status/1872319793124282653){rel=""nofollow""}
::


# Float

::component-viewer
---
component-files:
  - Float.vue
  - index.ts
component-id: float
config: FloatConfig
demo-file: FloatDemo.vue
---
#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){rel=""nofollow""}。
::


# 图片滑块

::component-viewer
---
component-files:
  - ImagesSlider.vue
component-id: images-slider
config: ImagesSliderConfig
demo-file: ImagesSliderDemo.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){rel=""nofollow""} 移植此组件。
- 灵感来自 [Aceternity UI](https://ui.aceternity.com/components/images-slider){rel=""nofollow""}。
::


# 放大镜

::component-viewer
---
component-files:
  - Lens.vue
  - Rays.vue
  - Beams.vue
component-id: lens
config: LensConfig
demo-file: LensDemo.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){rel=""nofollow""}。
- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} 移植该组件。
::


# 链接预览

::component-viewer
---
component-files:
  - LinkPreview.vue
component-id: link-preview
config: LinkPreviewConfig
demo-file: LinkPreviewDemo.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){rel=""nofollow""} 移植该组件。
- 移植自 [Aceternity UI's Link Preview](https://ui.aceternity.com/components/link-preview){rel=""nofollow""}。
::


# 跑马灯

::component-viewer
---
component-files:
  - Marquee.vue
  - ReviewCard.vue
component-id: marquee
config: MarqueeConfig
demo-file: MarqueeDemo.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){rel=""nofollow""}。
::


# 媒体文字

::component-viewer
---
component-files:
  - MediaText.vue
  - index.ts
component-id: media-text
config: MediaTextConfig
demo-file: MediaTextDemo.vue
---
#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){rel=""nofollow""}。
::


# 变形标签页

::component-viewer
---
component-files:
  - MorphingTabs.vue
component-id: morphing-tabs
config: MorphingTabsConfig
demo-file: MorphingTabsDemo.vue
---
#api
## API

| 属性名                | 类型         | 默认值  | 描述                      |
| ------------------ | ---------- | ---- | ----------------------- |
| `class`            | `string`   | `""` | 用于样式的额外类名。              |
| `tabs`             | `string[]` | `[]` | 标签集合。                   |
| `activeTab`        | `string`   | `""` | 当前激活的标签。                |
| `margin`           | `number`   | `20` | 激活标签左右的外边距。             |
| `blurStdDeviation` | `number`   | `6`  | SVG 模糊的 stdDeviation 值。 |

#credits
- 感谢 [Whbbit1999](https://github.com/Whbbit1999){rel=""nofollow""} 提供该组件。
- 灵感并移植自 [@Preet "Exclusion tabs"](https://x.com/wickedmishra/status/1823026659894940124){rel=""nofollow""}。
::


# 多步加载器

::component-viewer
---
component-files:
  - MultiStepLoader.vue
component-id: multi-step-loader
config: MultiStepLoaderConfig
demo-file: MultiStepLoaderDemo.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){rel=""nofollow""} 提供该组件。
- 灵感来自 [Aceternity UI's Multi Step Loader](https://ui.aceternity.com/components/multi-step-loader){rel=""nofollow""}。
::


# 视差浮动

::component-viewer
---
component-files:
  - ParallaxFloat.vue
  - ParallaxFloatElement.vue
  - ParallaxFloatContext.ts
  - index.ts
component-id: parallax-float
config: ParallaxFloatConfig
demo-file: ParallaxFloatDemo.vue
---
#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){rel=""nofollow""}。
::


# 路径跑马灯

::component-viewer
---
component-files:
  - PathMarquee.vue
  - index.ts
component-id: path-marquee
config: PathMarqueeConfig
demo-file: PathMarqueeDemo.vue
---
#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){rel=""nofollow""}。
::


# 照片画廊

::component-viewer
---
component-files:
  - PhotoGallery.vue
component-id: photo-gallery
config: PhotoGalleryConfig
demo-file: PhotoGalleryDemo.vue
---
#api
## API

| 属性名              | 类型                  | 默认值  | 描述                       |
| ---------------- | ------------------- | ---- | ------------------------ |
| `items`          | `"[{src: string}]"` | `[]` | 传入要动画的图片项/图片源。           |
| `containerClass` | `string`            | `""` | 容器的额外 Tailwind CSS 类。    |
| `class`          | `string`            | `""` | 自定义样式的额外 Tailwind CSS 类。 |

#credits
- 所有图片来自 [Pexels](https://www.pexels.com/@soldiervip/){rel=""nofollow""}
- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} 提供该组件。
::


# 滚动岛

::component-viewer
---
component-files:
  - ScrollIsland.vue
component-id: scroll-island
config: ScrollIslandConfig
demo-file: ScrollIslandDemo.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){rel=""nofollow""} 与 [Nitish Khagwal](https://x.com/nitishkmrk){rel=""nofollow""}
- [NumberFlow by Maxwell Barvian](https://number-flow.barvian.me/vue){rel=""nofollow""} 用于数字格式化与动画。
::


# Shader Toy Viewer

::component-viewer
---
component-files:
  - ShaderToy.vue
  - InspiraShaderToy.ts
component-id: shader-toy
config: ShaderToyConfig
demo-file: ShaderToyDemo.vue
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){rel=""nofollow""} 构建。
- 灵感来自 [Shadertoy](https://shadertoy.com/){rel=""nofollow""}，并为 Vue 兼容性做了适配。
::


# SVG 遮罩

::component-viewer
---
component-files:
  - SVGMask.vue
component-id: svg-mask
config: SvgMaskConfig
demo-file: SvgMaskDemo.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){rel=""nofollow""}。
::


# 时间线

::component-viewer
---
component-files:
  - Timeline.vue
component-id: timeline
config: TimelineConfig
demo-file: TimelineDemo.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){rel=""nofollow""}。
::


# 跟踪光束

::component-viewer
---
component-files:
  - TracingBeam.vue
component-id: tracing-beam
config: TracingBeamConfig
demo-file: TracingBeamDemo.vue
---
#api
## API

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

#credits
- 移植自 [Aceternity UI](https://ui.aceternity.com/components/tracing-beam){rel=""nofollow""};
::


# 动画光束

::component-viewer
---
component-files:
  - AnimatedBeam.vue
component-id: animated-beam
config: AnimatedBeamConfig
demo-file: AnimatedBeamDemo.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){rel=""nofollow""}。
::


# 边框光束

::component-viewer
---
component-files:
  - BorderBeam.vue
component-id: border-beam
config: BorderBeamConfig
demo-file: BorderBeamDemo.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){rel=""nofollow""}。
::


# 彩带

::component-viewer
---
component-files:
  - Confetti.vue
  - ConfettiButton.vue
component-id: confetti
config: ConfettiConfig
demo-file: ConfettiDemo.vue
dependencies: canvas-confetti
dev-dependencies: "@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){rel=""nofollow""} 库构建。
- 移植自 [Magic UI Confetti](https://magicui.design/docs/components/confetti){rel=""nofollow""}。
::


# 抖动着色器

::component-viewer
---
component-files:
  - DitherShader.vue
component-id: dither-shader
config: DitherShaderConfig
demo-file: DitherShaderDemo.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){rel=""nofollow""}。
::


# 发光边框

::component-viewer
---
component-files:
  - GlowBorder.vue
component-id: glow-border
config: GlowBorderConfig
demo-file: GlowBorderDemo.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){rel=""nofollow""} 提供这个出色的组件。
::


# 发光效果

::component-viewer
---
component-files:
  - GlowingEffect.vue
component-id: glowing-effect
config: GlowingEffectConfig
demo-file: GlowingEffectDemo.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){rel=""nofollow""}
::


# 图片徽章

::component-viewer
---
component-files:
  - ImagesBadge.vue
component-id: images-badge
config: ImagesBadgeConfig
demo-file: ImagesBadgeDemo.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){rel=""nofollow""}
::


# 流星雨

::component-viewer
---
component-files:
  - Meteors.vue
component-id: meteors
config: MeteorsConfig
demo-file: MeteorsDemo.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){rel=""nofollow""}
::


# 霓虹边框

::component-viewer
---
component-files:
  - NeonBorder.vue
component-id: neon-border
config: NeonBorderConfig
demo-file: NeonBorderDemo.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
- 灵感来自现代霓虹边框效果。
::


# 粒子图像

::component-viewer
---
component-files:
  - ParticleImage.vue
  - inspiraImageParticles.js
  - inspiraImageParticles.d.ts
component-id: particle-image
config: ParticleImageConfig
demo-file: ParticleImageDemo.vue
---
#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){rel=""nofollow""} 提供灵感。
- 感谢 [NextParticles](https://nextparticle.nextco.de){rel=""nofollow""} 提供动画库基础。
::


# 渐进模糊

::component-viewer
---
component-files:
  - ProgressiveBlur.vue
component-id: progressive-blur
config: ProgressiveBlurConfig
demo-file: ProgressiveBlurDemo.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){rel=""nofollow""}。
- 由 `motion-v` 驱动。
::


# 鳞片纹理

::component-viewer
---
component-files:
  - Scales.vue
component-id: scales
config: ScalesConfig
demo-file: ScalesDemo.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){rel=""nofollow""}.
::


# 刮刮乐揭示

::component-viewer
---
component-files:
  - ScratchToReveal.vue
component-id: scratch-to-reveal
config: ScratchToRevealConfig
demo-file: ScratchToRevealDemo.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){rel=""nofollow""} 提供该组件。
- 灵感来自 [MagicUI Scratch To Reveal](https://magicui.design/docs/components/scratch-to-reveal){rel=""nofollow""}。
::


# 弹性日历

::component-viewer
---
component-files:
  - SpringCalendar.vue
  - TextMorph.vue
component-id: spring-calendar
config: SpringCalendarConfig
demo-file: SpringCalendarDemo.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){rel=""nofollow""} 的作品。
::


# 动态评价

::component-viewer
---
component-files:
  - AnimatedTestimonials.vue
component-id: animated-testimonials
config: AnimatedTestimonialsConfig
demo-file: AnimatedTestimonialsDemo.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){rel=""nofollow""}。
::


# 设计感评价

::component-viewer
---
component-files:
  - DesignTestimonials.vue
component-id: design-testimonials
config: DesignTestimonialsConfig
demo-file: DesignTestimonialsDemo.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){rel=""nofollow""}
::


# 评价滑块

::component-viewer
---
component-files:
  - TestimonialSlider.vue
component-id: testimonial-slider
config: TestimonialSliderConfig
demo-file: TestimonialSliderDemo.vue
---
#api
## API

| 属性名            | 类型                                                                  | 默认值    | 描述                               |
| -------------- | ------------------------------------------------------------------- | ------ | -------------------------------- |
| `testimonials` | `Array<{ img: string; quote: string; name: string; role: string }>` | `[]`   | 滑块中显示的评价对象数组。                    |
| `autoRotate`   | `boolean`                                                           | `true` | 若为 `true`，滑块每隔 `duration` 秒自动切换。 |
| `duration`     | `number`                                                            | `5`    | 启用自动轮播时的切换间隔（秒）。                 |
::


# 3D 文字

::component-viewer
---
component-files:
  - Text3d.vue
component-id: text-3d
config: Text3dConfig
demo-file: Text3dDemo.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`     | 晃动动画时长（毫秒）。       |
::


# 模糊揭示

::component-viewer
---
component-files:
  - BlurReveal.vue
component-id: blur-reveal
config: BlurRevealConfig
demo-file: BlurRevealDemo.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){rel=""nofollow""} 提供该组件。
::


# 盒子揭示

::component-viewer
---
component-files:
  - BoxReveal.vue
component-id: box-reveal
config: BoxRevealConfig
demo-file: BoxRevealDemo.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){rel=""nofollow""}。
::


# 呼吸文字

::component-viewer
---
component-files:
  - BreathingText.vue
  - index.ts
component-id: breathing-text
config: BreathingTextConfig
demo-file: BreathingTextDemo.vue
---
#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){rel=""nofollow""}。
::


# 彩色文字

::component-viewer
---
component-files:
  - ColourfulText.vue
component-id: colourful-text
config: ColourfulTextConfig
demo-file: ColourfulTextDemo.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){rel=""nofollow""} 提供该组件。
- 移植自 [Aceternity UI Colourful Text](https://ui.aceternity.com/components/colourful-text){rel=""nofollow""}
::


# 容器文字翻转

::component-viewer
---
component-files:
  - ContainerTextFlip.vue
component-id: container-text-flip
config: ContainerTextFlipConfig
demo-file: ContainerTextFlipDemo.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){rel=""nofollow""} 提供该组件。
- 移植自 [Aceternity UI Container Text Flip](https://ui.aceternity.com/components/container-text-flip){rel=""nofollow""}。
::


# 加密文字

::component-viewer
---
component-files:
  - EncryptedText.vue
component-id: encrypted-text
config: EncryptedTextConfig
demo-file: EncryptedTextDemo.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){rel=""nofollow""}。
- 动画由 `motion-v` 驱动。
::


# 翻转单词

::component-viewer
---
component-files:
  - FlipWords.vue
component-id: flip-words
config: FlipWordsConfig
demo-file: FlipWordsDemo.vue
---
#api
## API

| 属性名        | 类型       | 描述                        |
| ---------- | -------- | ------------------------- |
| `words`    | `Array`  | 要展示并动画的单词数组。              |
| `duration` | `number` | 每个单词显示的时间（毫秒），之后翻转到下一个单词。 |
| `class`    | `string` | 应用于组件的额外 CSS 类。           |

#credits
- 感谢 [M Atif](https://github.com/atif0075){rel=""nofollow""} 移植该组件。
- 移植自 [Aceternity UI's Flip Words](https://ui.aceternity.com/components/flip-words){rel=""nofollow""}
::


# 聚焦

::component-viewer
---
component-files:
  - Focus.vue
component-id: focus
config: FocusConfig
demo-file: FocusDemo.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){rel=""nofollow""}。
::


# 高亮文本

::component-viewer
---
component-files:
  - HighlightText.vue
  - index.ts
component-id: highlight-text
config: HighlightTextConfig
demo-file: HighlightTextDemo.vue
---
#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){rel=""nofollow""}。
::


# 超能文字

::component-viewer
---
component-files:
  - HyperText.vue
component-id: hyper-text
config: HyperTextConfig
demo-file: HyperTextDemo.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){rel=""nofollow""} 组件。
- 感谢 [Prem](https://github.com/premdasvm){rel=""nofollow""} 移植该组件。
::


# 字符上提

::component-viewer
---
component-files:
  - LetterPullup.vue
component-id: letter-pullup
config: LetterPullupConfig
demo-file: LetterPullupDemo.vue
---
#api
## API

| 属性名     | 类型       | 默认值                        | 描述            |
| ------- | -------- | -------------------------- | ------------- |
| `class` | `string` | `-`                        | 应用于组件的类名。     |
| `words` | `string` | `Staggered Letter Pull Up` | 要做动画的文字。      |
| `delay` | `number` | `0.05`                     | 每个字符动画的延迟（秒）。 |

#credits
- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} 提供该组件。
- 灵感来自 [Magic UI](https://magicui.design/docs/components/letter-pullup){rel=""nofollow""}。
::


# 字母切换

::component-viewer
---
component-files:
  - LetterSwap.vue
  - index.ts
component-id: letter-swap
config: LetterSwapConfig
demo-file: LetterSwapDemo.vue
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){rel=""nofollow""}。
- 原始作品来自 [Daniel Petho](https://github.com/danielpetho/fancy){rel=""nofollow""}。
::


# 线条阴影文字

::component-viewer
---
component-files:
  - LineShadowText.vue
component-id: line-shadow-text
config: LineShadowTextConfig
demo-file: LineShadowTextDemo.vue
---
#api
## API

| 属性名           | 类型       | 默认值       | 描述                |
| ------------- | -------- | --------- | ----------------- |
| `shadowColor` | `string` | `"black"` | 阴影效果的颜色。          |
| `class`       | `string` | `""`      | 用于自定义样式的额外 CSS 类。 |
| `as`          | `string` | `"span"`  | 渲染文字所用的 HTML 元素。  |

#credits
- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} 提供该组件。
- 移植自 [Magic UI 的 Line Shadow Text](https://magicui.design/docs/components/line-shadow-text){rel=""nofollow""}
::


# 文字变形

::component-viewer
---
component-files:
  - MorphingText.vue
component-id: morphing-text
config: MorphingTextConfig
demo-file: MorphingTextDemo.vue
---
#api
## API

| 属性名            | 类型         | 默认值   | 描述         |
| -------------- | ---------- | ----- | ---------- |
| `texts`        | `string[]` | `[]`  | 需要变换的文本数组。 |
| `class`        | `string`   | `""`  | 容器的额外类名。   |
| `morphTime`    | `number`   | `1.5` | 动画执行时间。    |
| `coolDownTime` | `number`   | `0.5` | 动画停留时间。    |

#credits
- 感谢 [Whbbit1999](https://github.com/Whbbit1999){rel=""nofollow""} 提供该组件。
- 灵感并移植自 [Magic UI Morphing Text](https://magicui.design/docs/components/morphing-text){rel=""nofollow""}。
::


# 数字滚动

::component-viewer
---
component-files:
  - NumberTicker.vue
component-id: number-ticker
config: NumberTickerConfig
demo-file: NumberTickerDemo.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）。](https://vueuse.org/core/useTransition%EF%BC%89%E3%80%82){rel=""nofollow""} |

#credits
- 感谢 [Grzegorz Krol](https://github.com/Grzechu335){rel=""nofollow""} 移植该组件。
- 移植自 [Magic UI NumberTicker](https://magicui.design/docs/components/number-ticker){rel=""nofollow""}。
::


# 光辉文字

::component-viewer
---
component-files:
  - RadiantText.vue
component-id: radiant-text
config: RadiantTextConfig
demo-file: RadiantTextDemo.vue
---
#api
## API

| 属性名            | 类型       | 默认值   | 描述         |
| -------------- | -------- | ----- | ---------- |
| `duration`     | `number` | `10`  | 动画持续时间（秒）。 |
| `radiantWidth` | `number` | `100` | 高光动画的宽度。   |

#credits
- 感谢 [Magic UI](https://magicui.design/docs/components/animated-shiny-text){rel=""nofollow""} 提供该组件。
::


# 螺旋文字

::component-viewer
---
component-files:
  - ScrewText.vue
  - index.ts
component-id: screw-text
config: ScrewTextConfig
demo-file: ScrewTextDemo.vue
---
#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){rel=""nofollow""}。
- 原作者：[Daniel Petho](https://github.com/danielpetho/fancy){rel=""nofollow""}。
::


# 滚动切换文本

::component-viewer
---
component-files:
  - ScrollSwapText.vue
  - index.ts
component-id: scroll-swap-text
config: ScrollSwapTextConfig
demo-file: ScrollSwapTextDemo.vue
---
#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){rel=""nofollow""}。
::


# 闪光文字

::component-viewer
---
component-files:
  - SparklesText.vue
component-id: sparkles-text
config: SparklesTextConfig
demo-file: SparklesTextDemo.vue
---
#api
## API

| 属性名             | 类型       | 默认值                                      | 描述          |
| --------------- | -------- | ---------------------------------------- | ----------- |
| `class`         | `string` | `-`                                      | 应用于闪光文字的类名。 |
| `text`          | `string` | \`\`                                     | 要显示的文字。     |
| `sparklesCount` | `number` | `10`                                     | 文字上出现的闪光数量。 |
| `colors`        | `object` | `{first: '#A07CFE'; second: '#FE8FB5';}` | 闪光的颜色配置。    |

#credits
- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} 提供该组件。
- 灵感来自 [Magic UI](https://magicui.design/docs/components/sparkles-text){rel=""nofollow""}。
- 感谢 [M Atif](https://github.com/atif0075){rel=""nofollow""} 更新该组件。
::


# 旋转文字

::component-viewer
---
component-files:
  - SpinningText.vue
component-id: spinning-text
config: SpinningTextConfig
demo-file: SpinningTextDemo.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){rel=""nofollow""} 提供该组件。
- 移植自 [Magic UI Spinning Text](https://magicui.design/docs/components/spinning-text){rel=""nofollow""}。
::


# 文字生成效果

::component-viewer
---
component-files:
  - TextGenerateEffect.vue
component-id: text-generate-effect
config: TextGenerateConfig
demo-file: TextGenerateDemo.vue
---
#api
## API

| 属性名        | 类型        | 默认值      | 描述              |
| ---------- | --------- | -------- | --------------- |
| `words`    | `string`  | Required | 要展示并生成的文字。      |
| `duration` | `number`  | `0.7`    | 文字生成动画的持续时间（秒）。 |
| `delay`    | `number`  | `0`      | 动画开始前的延迟（毫秒）。   |
| `filter`   | `boolean` | `true`   | 文字的模糊效果。        |

#credits
- 感谢 [M Atif](https://github.com/atif0075){rel=""nofollow""} 移植该组件。
- 移植自 [Aceternity UI's Text Generate Effect](https://ui.aceternity.com/components/text-generate-effect){rel=""nofollow""}。
::


# 文字故障

::component-viewer
---
component-files:
  - TextGlitch.vue
component-id: text-glitch
config: TextGlitchConfig
demo-file: TextGlitchDemo.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>{rel=""nofollow""}
  - <https://www.youtube.com/watch?v=9CCkp_El1So>{rel=""nofollow""}
::


# 文字高亮

::component-viewer
---
component-files:
  - TextHighlight.vue
component-id: text-highlight
config: TextHighlightConfig
demo-file: TextHighlightDemo.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){rel=""nofollow""}
- 感谢 [Nathan De Pachtere](https://nathandepachtere.com){rel=""nofollow""} 移植该组件。
::


# 文字悬停效果

::component-viewer
---
component-files:
  - TextHoverEffect.vue
component-id: text-hover-effect
config: TextHoverEffectConfig
demo-file: TextHoverEffectDemo.vue
---
#api
## API

| 属性名           | 类型       | 默认值      | 描述              |
| ------------- | -------- | -------- | --------------- |
| `text`        | `string` | Required | 应用悬停效果的文字。      |
| `duration`    | `number` | `200`    | 蒙版过渡动画的持续时间（秒）。 |
| `strokeWidth` | `number` | `0.75`   | 文字描边宽度。         |
| `opacity`     | `number` | `null`   | 文字的不透明度。        |
::


# 文字揭示

::component-viewer
---
component-files:
  - TextReveal.vue
component-id: text-reveal
config: TextRevealConfig
demo-file: TextRevealDemo.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/){rel=""nofollow""} 与 [GSAP SplitText](https://gsap.com/docs/v3/Plugins/SplitText/){rel=""nofollow""}。
::


# 文字揭示卡片

::component-viewer
---
component-files:
  - TextRevealCard.vue
  - TextRevealStars.vue
component-id: text-reveal-card
config: TextRevealCardConfig
demo-file: TextRevealCardDemo.vue
---
#api
## API

| 属性名        | 类型       | 描述            |
| ---------- | -------- | ------------- |
| class      | `String` | 卡片的额外类名。      |
| starsCount | `Number` | 控制生成的星星数量。    |
| starsClass | `String` | 应用于漂浮星星的额外类名。 |

| 插槽名        | 描述             |
| ---------- | -------------- |
| header     | `String`       |
| text       | 卡片未悬停时显示的默认文字。 |
| revealText | 悬停卡片时显示的文字。    |

#credits
- 感谢 [M Atif](https://github.com/atif0075){rel=""nofollow""} 移植该组件。
- 移植自 [Aceternity UI's Text Reveal Card](https://ui.aceternity.com/components/text-reveal-card){rel=""nofollow""}。
::


# 滚动文字揭示

::component-viewer
---
component-files:
  - TextScrollReveal.vue
  - ScrollWord.vue
component-id: text-scroll-reveal
config: TextScrollRevealConfig
demo-file: TextScrollRevealDemo.vue
---
#api
## API

| 属性名     | 类型       | 默认值  | 描述                    |
| ------- | -------- | ---- | --------------------- |
| `text`  | `string` | N/A  | 在滚动时逐词显示的文本内容。        |
| `class` | `string` | `""` | 应用于组件的额外 CSS 类，便于自定义。 |

#credits
- 移植自 [Magic UI Text Reveal](https://magicui.design/docs/components/text-reveal){rel=""nofollow""}。
::


# 打字机文字

::component-viewer
---
component-files:
  - TypewriterText.vue
  - index.ts
component-id: typewriter-text
config: TypewriterTextConfig
demo-file: TypewriterTextDemo.vue
---
#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){rel=""nofollow""}。
::


# 下划线文字

::component-viewer
---
component-files:
  - UnderlineText.vue
  - index.ts
component-id: underline-text
config: UnderlineTextConfig
demo-file: UnderlineTextDemo.vue
---
#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){rel=""nofollow""}。
::


# 可变字母文字

::component-viewer
---
component-files:
  - VariableLetterText.vue
  - index.ts
component-id: variable-letter-text
config: VariableLetterTextConfig
demo-file: VariableLetterTextDemo.vue
---
#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){rel=""nofollow""}。
::


# 可变文字

::component-viewer
---
component-files:
  - VariableText.vue
  - index.ts
component-id: variable-text
config: VariableTextConfig
demo-file: VariableTextDemo.vue
---
#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){rel=""nofollow""}。
- 随机字母行为基于 [Fancy Components Variable Font Hover By Random Letter](https://fancycomponents.dev/docs/components/text/variable-font-hover-by-random-letter){rel=""nofollow""}。
::


# 弯曲画廊

::component-viewer
---
component-files:
  - BendingGallery.vue
component-id: bending-gallery
config: BendingGalleryConfig
demo-file: BendingGalleryDemo.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/){rel=""nofollow""}。
::


# 3D 轮播

::component-viewer
---
component-files:
  - Carousel3D.vue
component-id: carousel-3d
config: Carousel3dConfig
demo-file: Carousel3dDemo.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){rel=""nofollow""} 分享此组件。
::


# 文件树

::component-viewer
---
component-files:
  - Tree.vue
  - Folder.vue
  - File.vue
  - TreeIndicator.vue
  - index.ts
component-id: file-tree
config: FileTreeConfig
demo-file: FileTreeDemo.vue
---
#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){rel=""nofollow""}。
- 感谢 [kalix127](https://github.com/kalix127){rel=""nofollow""} 对该组件的移植。
::


# Github 地球

::component-viewer
---
component-files:
  - GithubGlobe.vue
component-id: github-globe
config: GithubGlobeConfig
demo-file: GithubGlobeDemo.vue
dependencies: three postprocessing three-globe
dev-dependencies: "@types/three"
---
#api
#### 下载 GeoJSON 文件

从 [GeoJSON Maps](https://geojson-maps.kyd.au/){rel=""nofollow""} 按需选择大陆与精度下载地理数据，将文件保存为与组件同目录的 `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){rel=""nofollow""}。
::


# 地球

::component-viewer
---
component-files:
  - Globe.vue
component-id: globe
config: GlobeConfig
demo-file: GlobeDemo.vue
dependencies: cobe vue-use-spring
---
#api
## API

| 属性名         | 类型            | 默认值     | 描述                                                                                             |
| ----------- | ------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `class`     | `string`      | `""`    | 用于自定义样式的额外 CSS 类。                                                                              |
| `config`    | `COBEOptions` | N/A     | 地球的配置对象，遵循 **[COBE](https://cobe.vercel.app/docs/api){rel=""nofollow""}** 库的选项。 |
| `mass`      | `number`      | `1`     | 控制旋转惯性的弹簧质量参数。                                                                                 |
| `tension`   | `number`      | `280`   | 弹簧张力参数，影响响应速度。                                                                                 |
| `friction`  | `number`      | `100`   | 弹簧摩擦参数，影响阻尼。                                                                                   |
| `precision` | `number`      | `0.001` | 弹簧计算的精度参数。                                                                                     |

#credits
- 基于 [cobe](https://github.com/shuding/cobe){rel=""nofollow""} 库实现 WebGL 地球可视化。
- 移植自 [Magic UI](https://magicui.design/docs/components/globe){rel=""nofollow""}。
::


# 图标云

::component-viewer
---
component-files:
  - IconCloud.vue
  - index.ts
component-id: icon-cloud
config: IconCloudConfig
demo-file: IconCloudDemo.vue
---
#api
## API

| 属性名      | 类型       | 默认值  | 描述                |
| -------- | -------- | ---- | ----------------- |
| `class`  | `string` | -    | 自定义组件样式的额外类名。     |
| `images` | `array`  | `[]` | 要在云中渲染的图片 URL 数组。 |

#credits
- 灵感来自 [MagicUI](https://magicui.design/docs/components/icon-cloud){rel=""nofollow""}。
- 感谢 [kalix127](https://github.com/kalix127){rel=""nofollow""} 对该组件的移植。
::


# 无限网格

::component-viewer
---
component-files:
  - InfiniteGrid.vue
  - InfiniteGridClass.ts
  - DisposalManager.ts
  - EventHandler.ts
  - GridManager.ts
  - PostProcessShader.ts
  - createTexture.ts
  - shaders.ts
  - types.ts
component-id: infinite-grid
config: InfiniteGridConfig
demo-file: InfiniteGridDemo.vue
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){rel=""nofollow""}。
- 特别感谢 [Safak Dinc](https://github.com/safakdinc){rel=""nofollow""} 提供想法并授权包含原项目，可在 [infinite-grid](https://github.com/safakdinc/infinite-grid){rel=""nofollow""} 查看原始仓库。
- 感谢 [kalix127](https://github.com/kalix127){rel=""nofollow""} 对该组件的移植。
::


# 光速动效

::component-viewer
---
component-files:
  - LightSpeed.vue
  - LightSpeedApp.ts
  - presets.ts
  - shaders.ts
component-id: light-speed
config: LightSpeedConfig
demo-file: LightSpeedDemo.vue
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/){rel=""nofollow""} 移植至 Vue。
::


# 液态玻璃效果

::component-viewer
---
component-files:
  - LiquidGlass.vue
component-id: liquid-glass
config: LiquidGlassConfig
demo-file: LiquidGlassDemo.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 上回退为磨砂玻璃效果。
::


# 液态 Logo

::component-viewer
---
component-files:
  - LiquidLogo.vue
  - parseLogoImage.ts
  - shader.ts
component-id: liquid-logo
config: LiquidLogoConfig
demo-file: LiquidLogoDemo.vue
---
#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){rel=""nofollow""} 移植并改进。
::


# 动态 Logo 云

::component-viewer
---
component-files:
  - AnimatedLogoCloud.vue
  - IconLogoCloud.vue
  - StaticLogoCloud.vue
  - index.ts
component-id: logo-cloud
config: IconLogoCloudConfig
demo-file: IconLogoCloudDemo.vue
---
#api
## API

| 属性名     | 类型       | 默认值                         | 描述                   |
| ------- | -------- | --------------------------- | -------------------- |
| `class` | `string` | `-`                         | 将每个项目加入列表前的延迟时间（毫秒）。 |
| `title` | `string` | `Trusted by Companies like` | 动态 Logo 云的标题。        |
| `logos` | `[]`     | `[{name: "", path: ""}]`    | Logo 数组，包含名称与路径字段。   |

#credits
- 感谢 [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} 提供该组件。
::


# 折纸 Logo

::component-viewer
---
component-files:
  - LogoOrigami.vue
  - LogoOrigamiItem.vue
component-id: logo-origami
config: LogoOrigamiConfig
demo-file: LogoOrigamiDemo.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){rel=""nofollow""} 的折纸翻转动画。
::


# 轨道动画

::component-viewer
---
component-files:
  - Orbit.vue
  - index.ts
component-id: orbit
config: OrbitConfig
demo-file: OrbitDemo.vue
---
#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){rel=""nofollow""}。
- 感谢 [Nathan De Pachtere](https://nathandepachtere.com/){rel=""nofollow""} 更新此组件。
::


# Spline

::component-viewer
---
component-files:
  - Spline.vue
  - ParentSize.vue
component-id: spline
config: SplineConfig
demo-file: SplineDemo.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 体验。
::


# 世界地图

::component-viewer
---
component-files:
  - WorldMap.vue
component-id: world-map
config: WorldMapConfig
demo-file: WorldMapDemo.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){rel=""nofollow""}。
::




# 更新日志

:inspira-changelog


# Composants animés pour Vue et Nuxt.



# Commencer

Bienvenue à [**Inspira UI**](https://inspira-ui.com){rel="&#x22;nofollow&#x22;"}, un projet communautaire pour [Vue](https://vuejs.org){rel="&#x22;nofollow&#x22;"} !

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){rel="&#x22;nofollow&#x22;"} et [Magic UI](https://magicui.design){rel="&#x22;nofollow&#x22;"}. 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){rel="&#x22;nofollow&#x22;"}
- Hautement [configurable](https://inspira-ui.com/fr/components) pour répondre à vos besoins de conception
- Une large gamme de [composants](https://inspira-ui.com/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){rel="&#x22;nofollow&#x22;"} pour avoir inspiré cette adaptation Vue.
- [Magic UI](https://magicui.design){rel="&#x22;nofollow&#x22;"} pour leur inspiration de conception.
- [shadcn-vue](https://www.shadcn-vue.com/){rel="&#x22;nofollow&#x22;"} 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){rel="&#x22;nofollow&#x22;"} pour le site de documentation Nuxt magnifiquement conçu.

### À mon sujet

Bonjour, je suis [Rahul Vashishtha](https://rahulv.dev){rel="&#x22;nofollow&#x22;"}. 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){rel="&#x22;nofollow&#x22;"} et rejoignez-moi dans ce voyage [ici](https://github.com/unovue/inspira-ui){rel="&#x22;nofollow&#x22;"} !

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


# Installation

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){rel=""nofollow""}.**
::

## Commencer avec Inspira UI

::steps
### Configurez `tailwindcss`

Pour commencer, installez `tailwindcss` en utilisant [ce guide](https://tailwindcss.com/docs/installation){rel=""nofollow""}.

### 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){rel=""nofollow""}.

### 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
      ```css [main.css]
      @import "tailwindcss";
      @import "@nuxt/ui";

      @theme static {
        --color-background: var(--ui-bg);
        --color-foreground: var(--ui-text);

        --color-card: var(--ui-bg-elevated);
        --color-card-foreground: var(--ui-text);

        --color-popover: var(--ui-bg-elevated);
        --color-popover-foreground: var(--ui-text);

        --color-muted: var(--ui-bg-muted);
        --color-muted-foreground: var(--ui-text-muted);

        --color-accent: var(--ui-bg-accented);
        --color-accent-foreground: var(--ui-text);

        --color-border: var(--ui-border);
        --color-input: var(--ui-border);

        --color-primary: var(--ui-primary);
        --color-primary-foreground: var(--ui-text-inverted);

        --color-secondary: var(--ui-secondary);
        --color-secondary-foreground: var(--ui-text-inverted);

        --color-destructive: var(--ui-error);
        --color-destructive-foreground: var(--ui-text-inverted);

        --color-ring: var(--ui-primary);

        --radius: var(--ui-radius);
      }

      :root {
        --background: var(--ui-bg);
        --foreground: var(--ui-text);

        --card: var(--ui-bg-elevated);
        --card-foreground: var(--ui-text);

        --popover: var(--ui-bg-elevated);
        --popover-foreground: var(--ui-text);

        --muted: var(--ui-bg-muted);
        --muted-foreground: var(--ui-text-muted);

        --accent: var(--ui-bg-accented);
        --accent-foreground: var(--ui-text);

        --border: var(--ui-border);
        --input: var(--ui-border);

        --primary: var(--ui-primary);
        --primary-foreground: var(--ui-text-inverted);

        --secondary: var(--ui-secondary);
        --secondary-foreground: var(--ui-text-inverted);

        --destructive: var(--ui-error);
        --destructive-foreground: var(--ui-text-inverted);

        --ring: var(--ui-primary);
      }
      ```
      :::::
    ::::

    ::::tabs-item{icon="simple-icons:tailwindcss" label="Other TailwindCSS Kit"}
      :::::code-collapse
      ```css [main.css]
      @import "tailwindcss";
      @import "tw-animate-css";

      @custom-variant dark (&:is(.dark *));

      :root {
        --card: oklch(1 0 0);
        --card-foreground: oklch(0.141 0.005 285.823);
        --popover: oklch(1 0 0);
        --popover-foreground: oklch(0.141 0.005 285.823);
        --primary: oklch(0.21 0.006 285.885);
        --primary-foreground: oklch(0.985 0 0);
        --secondary: oklch(0.967 0.001 286.375);
        --secondary-foreground: oklch(0.21 0.006 285.885);
        --muted: oklch(0.967 0.001 286.375);
        --muted-foreground: oklch(0.552 0.016 285.938);
        --accent: oklch(0.967 0.001 286.375);
        --accent-foreground: oklch(0.21 0.006 285.885);
        --destructive: oklch(0.577 0.245 27.325);
        --destructive-foreground: oklch(0.577 0.245 27.325);
        --border: oklch(0.92 0.004 286.32);
        --input: oklch(0.92 0.004 286.32);
        --ring: oklch(0.705 0.015 286.067);
        --radius: 0.625rem;
        --background: oklch(1 0 0);
        --foreground: oklch(0.141 0.005 285.823);
      }

      .dark {
        --background: oklch(0.141 0.005 285.823);
        --foreground: oklch(0.985 0 0);
        --card: oklch(0.141 0.005 285.823);
        --card-foreground: oklch(0.985 0 0);
        --popover: oklch(0.141 0.005 285.823);
        --popover-foreground: oklch(0.985 0 0);
        --primary: oklch(0.985 0 0);
        --primary-foreground: oklch(0.21 0.006 285.885);
        --secondary: oklch(0.274 0.006 286.033);
        --secondary-foreground: oklch(0.985 0 0);
        --muted: oklch(0.274 0.006 286.033);
        --muted-foreground: oklch(0.705 0.015 286.067);
        --accent: oklch(0.274 0.006 286.033);
        --accent-foreground: oklch(0.985 0 0);
        --destructive: oklch(0.396 0.141 25.723);
        --destructive-foreground: oklch(0.637 0.237 25.331);
        --border: oklch(0.274 0.006 286.033);
        --input: oklch(0.274 0.006 286.033);
        --ring: oklch(0.442 0.017 285.786);
      }

      @theme inline {
        --color-background: var(--background);
        --color-foreground: var(--foreground);
        --color-card: var(--card);
        --color-card-foreground: var(--card-foreground);
        --color-popover: var(--popover);
        --color-popover-foreground: var(--popover-foreground);
        --color-primary: var(--primary);
        --color-primary-foreground: var(--primary-foreground);
        --color-secondary: var(--secondary);
        --color-secondary-foreground: var(--secondary-foreground);
        --color-muted: var(--muted);
        --color-muted-foreground: var(--muted-foreground);
        --color-accent: var(--accent);
        --color-accent-foreground: var(--accent-foreground);
        --color-destructive: var(--destructive);
        --color-destructive-foreground: var(--destructive-foreground);
        --color-border: var(--border);
        --color-input: var(--input);
        --color-ring: var(--ring);

        --radius-sm: calc(var(--radius) - 4px);
        --radius-md: calc(var(--radius) - 2px);
        --radius-lg: var(--radius);
        --radius-xl: calc(var(--radius) + 4px);
      }

      @layer base {
        * {
          @apply border-border outline-ring/50;
        }
        body {
          @apply bg-background text-foreground;
        }
      }

      html {
        color-scheme: light dark;
      }
      html.dark {
        color-scheme: dark;
      }
      html.light {
        color-scheme: light;
      }
      ```
      :::::
    ::::
  :::
::

::tip{.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/){rel="&#x22;nofollow&#x22;"}.

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


# Comment contribuer

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](https://inspira-ui.com/#commencer)
2. [Code de conduite](https://inspira-ui.com/#code-de-conduite)
3. [Comment contribuer](https://inspira-ui.com/#comment-contribuer)
   - [Signaler des bogues](https://inspira-ui.com/#signaler-des-bogues)
   - [Suggérer des améliorations](https://inspira-ui.com/#sugg%C3%A9rer-des-am%C3%A9liorations)
   - [Ajouter de nouveaux composants](https://inspira-ui.com/#ajouter-de-nouveaux-composants)
4. [Structure du projet](https://inspira-ui.com/#structure-du-projet)
5. [Directives de style](https://inspira-ui.com/#directives-de-style)
   - [Normes de codage](https://inspira-ui.com/#normes-de-codage)
   - [Format des composants](https://inspira-ui.com/#format-des-composants)
   - [Messages de commit](https://inspira-ui.com/#messages-de-commit)
6. [Directives de documentation](https://inspira-ui.com/#directives-de-documentation)
   - [Composants à fichier unique](https://inspira-ui.com/#composants-%C3%A0-fichier-unique)
   - [Composants multi-fichiers](https://inspira-ui.com/#composants-multi-fichiers)
7. [Tests](https://inspira-ui.com/#tests)
8. [Licence](https://inspira-ui.com/#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](https://inspira-ui.com/code-of-conduct), 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" rel="&#x22;nofollow&#x22;"} 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" rel="&#x22;nofollow&#x22;"} 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`**:br
   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. :br 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
   ```


# Code de conduite

## 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){rel="&#x22;nofollow&#x22;"}

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){rel="&#x22;nofollow&#x22;"}


# Fond Aurore

::component-viewer
---
component-files:
  - AuroraBackground.vue
component-id: aurora-background
config: AuroraBackgroundConfig
demo-file: AuroraBackgroundDemo.vue
---
#instructions
Ajoutez l'entrée suivante au thème inline dans votre fichier `main.css`.

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

| Nom de propriété | Type      | Valeur par défaut | Description                                                         |
| ---------------- | --------- | ----------------- | ------------------------------------------------------------------- |
| `class`          | `string`  | `-`               | Classes CSS supplémentaires à appliquer pour le style du composant. |
| `radialGradient` | `boolean` | `true`            | Indique si un dégradé radial est appliqué sur le fond.              |

#credits
- Merci à [Aceternity UI](https://ui.aceternity.com/components/aurora-background){rel=""nofollow""}.
- Merci à [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} pour le portage de ce composant.
::


# Fond trou noir

::component-viewer
---
component-files:
  - BlackHoleBackground.vue
component-id: bg-black-hole
config: BlackHoleBackgroundConfig
demo-file: BlackHoleBackgroundDemo.vue
---
#api
## API

| Nom de propriété   | Type                       | Valeur par défaut | Description                                                             |
| ------------------ | -------------------------- | ----------------- | ----------------------------------------------------------------------- |
| `strokeColor`      | `string`                   | `"#737373"`       | Couleur de tracé pour les disques concentriques et les lignes.          |
| `numberOfLines`    | `number`                   | `50`              | Nombre total de lignes radiales partant du centre.                      |
| `numberOfDiscs`    | `number`                   | `50`              | Nombre total d'ellipses concentriques formant le tunnel.                |
| `particleRGBColor` | `[number, number, number]` | `[255,255,255]`   | Couleur RVB utilisée pour les petites particules attirées dans le trou. |
| `class`            | `string`                   | `""`              | Classes utilitaires supplémentaires fusionnées sur le wrapper racine.   |

#credits
- Logique d'art génératif inspirée des animations de tunnel/warp.
- Utilise **Motion-V** pour les dérives de dégradé et l'API de composition Vue 3 pour le cycle de vie.
- Conçu en gardant l'accessibilité à l'esprit — l'effet reste purement décoratif via un canvas `aria-hidden`.
::


# Fond bulles

::component-viewer
---
component-files:
  - BubblesBg.vue
component-id: bg-bubbles
config: BubblesBgConfig
demo-file: BubblesBgDemo.vue
dependencies: three
dev-dependencies: "@types/three"
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                 |
| ---------------- | -------- | ----------------- | ------------------------------------------- |
| `blur`           | `number` | `0`               | Niveau de flou appliqué au fond, en pixels. |

#credits
- Réalisé avec la bibliothèque [Three.js](https://threejs.org/){rel=""nofollow""} pour le rendu et les animations 3D.
- Inspiré de l'[expérience Tresjs](https://lab.tresjs.org/experiments/overlay){rel=""nofollow""}.
::


# Portail cosmique

::component-viewer
---
component-files:
  - CosmicPortal.vue
component-id: cosmic-portal
config: CosmicPortalConfig
demo-file: CosmicPortalDemo.vue
dependencies: three postprocessing
dev-dependencies: "@types/three"
---
#api
## API

| Nom de propriété   | Type     | Valeur par défaut | Description                                                      |
| ------------------ | -------- | ----------------- | ---------------------------------------------------------------- |
| `portalComplexity` | `number` | `4`               | Contrôle la complexité des effets et de la géométrie du portail. |
| `crystalCount`     | `number` | `12`              | Nombre de cristaux flottants dans la scène.                      |
| `primaryColor`     | `string` | `#9b59b6`         | Couleur principale pour le portail et la lueur d'arrière-plan.   |
| `secondaryColor`   | `string` | `#3498db`         | Couleur secondaire pour le mélange et la lueur.                  |
| `accentColor`      | `string` | `#e74c3c`         | Couleur utilisée pour l'énergie et les reflets du portail.       |
| `vortexColor`      | `string` | `#2ecc71`         | Couleur utilisée pour le vortex et les flux dimensionnels.       |
| `rotationSpeed`    | `number` | `0.3`             | Vitesse de rotation des éléments.                                |
| `bloomStrength`    | `number` | `1.2`             | Intensité du bloom en post-traitement.                           |
| `bloomRadius`      | `number` | `0.7`             | Rayon de l'effet de bloom.                                       |
| `bloomThreshold`   | `number` | `0.2`             | Seuil de visibilité du bloom.                                    |
| `dimensionShift`   | `number` | `4`               | Niveau de distorsion dimensionnelle pour l'animation shader.     |

#credits
- Inspiré et porté depuis [Dimensional Portal par Techartist](https://x.com/techartist_){rel=""nofollow""}.
::


# Fond étoiles filantes

::component-viewer
---
component-files:
  - FallingStarsBg.vue
component-id: bg-falling-stars
config: FallingStarsBgConfig
demo-file: FallingStarsBgDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                  |
| ---------------- | -------- | ----------------- | -------------------------------------------- |
| `color`          | `string` | `"#FFF"`          | Couleur des étoiles dans le champ.           |
| `count`          | `number` | `200`             | Nombre d'étoiles affichées dans l'animation. |

#credits
- Inspiré par les simulations de champ d'étoiles 3D et les effets de traînée des animations canvas modernes.
- Merci à [Prodromos Pantos](https://github.com/prpanto){rel=""nofollow""} pour le portage du composant original vers Vue & Nuxt.
::


# Grille scintillante

::component-viewer
---
component-files:
  - FlickeringGrid.vue
component-id: flickering-grid
config: FlickeringGridConfig
demo-file: FlickeringGridDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                 |
| ---------------- | -------- | ----------------- | ------------------------------------------- |
| `squareSize`     | `number` | `4`               | Taille de chaque carré de la grille.        |
| `gridGap`        | `number` | `6`               | Espacement entre les carrés.                |
| `flickerChance`  | `number` | `0.3`             | Probabilité qu'un carré scintille.          |
| `color`          | `string` | `rgb(0, 0, 0)`    | Couleur des carrés.                         |
| `width`          | `number` | `-`               | Largeur du canvas.                          |
| `height`         | `number` | `-`               | Hauteur du canvas.                          |
| `class`          | `string` | `-`               | Classes CSS supplémentaires pour le canvas. |
| `maxOpacity`     | `number` | `0.2`             | Opacité maximale des carrés.                |

#credits
- Merci à [magicui flickering-grid](https://magicui.design/docs/components/flickering-grid){rel=""nofollow""} pour ce composant.
::


# Motif de grille interactif

::component-viewer
---
component-files:
  - InteractiveGridPattern.vue
component-id: interactive-grid-pattern
config: InteractiveGridPatternConfig
demo-file: InteractiveGridPatternDemo.vue
---
#api
## API

| Nom de propriété   | Type               | Valeur par défaut | Description                                         |
| ------------------ | ------------------ | ----------------- | --------------------------------------------------- |
| `className`        | `string`           | -                 | Classes supplémentaires pour styliser le composant. |
| `squaresClassName` | `string`           | -                 | Classes supplémentaires pour styliser les carrés.   |
| `width`            | `number`           | `40`              | Largeur du carré en pixels.                         |
| `height`           | `number`           | `40`              | Hauteur du carré en pixels.                         |
| `squares`          | `[number, number]` | `[24, 24]`        | Nombre de carrés dans le motif de grille.           |

#credits
- Inspiré par [MagicUI](https://magicui.design/docs/components/interactive-grid-pattern){rel=""nofollow""}.
- Merci à [kalix127](https://github.com/kalix127){rel=""nofollow""} pour le portage de ce composant.
::


# Effet lampe

::component-viewer
---
component-files:
  - LampEffect.vue
component-id: lamp-effect
config: LampEffectConfig
demo-file: LampEffectDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                             |
| ---------------- | -------- | ----------------- | ------------------------------------------------------- |
| `delay`          | `number` | `0.5`             | Délai avant le début de l'animation, en secondes.       |
| `duration`       | `number` | `0.8`             | Durée de l'animation, en secondes.                      |
| `class`          | `string` | `""`              | Classes CSS supplémentaires pour un style personnalisé. |

#credits
- Porté depuis [Aceternity UI](https://ui.aceternity.com/components/lamp-effect){rel=""nofollow""}
::


# Fond liquide

::component-viewer
---
component-files:
  - LiquidBackground.vue
component-id: liquid-background
config: LiquidBackgroundConfig
demo-file: LiquidBackgroundDemo.vue
dependencies: ogl
---
#api
## API

Ce composant ne nécessite aucune prop externe : il rend dynamiquement l'effet de fond liquide au montage.

#credits
- Réalisé avec la bibliothèque [OGL](https://github.com/oframe/ogl){rel=""nofollow""} pour le rendu 3D.
- Inspiré par des motifs d'art génératif.
- Utilise l'API de composition de Vue pour le cycle de vie et la gestion d'état.
::


# Fond neuronal

::component-viewer
---
component-files:
  - NeuralBg.vue
component-id: bg-neural
config: NeuralBgConfig
demo-file: NeuralBgDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                                     |
| ---------------- | -------- | ----------------- | --------------------------------------------------------------- |
| `hue`            | `number` | `200`             | Teinte de base des couleurs de fond (en degrés, 0–360).         |
| `saturation`     | `number` | `0.8`             | Saturation de la couleur de fond (0–1).                         |
| `chroma`         | `number` | `0.6`             | Facteur de chroma/luminosité de la couleur HSL (0-1).           |
| `class`          | `string` | `—`               | Classes CSS optionnelles supplémentaires pour l'élément canvas. |

> 💡 Ce composant utilise par défaut un fond plein écran fixé avec `pointer-events-none`. Vous pouvez surcharger le style via la prop `class` si nécessaire.

#credits
- Construit avec [OGL](https://github.com/oframe/ogl){rel=""nofollow""}, un framework WebGL minimal.
- Logique mathématique et motifs basés sur des superpositions trigonométriques récursives.
- Porté depuis [Neural Glow Cursor par Cursify](https://cursify.vercel.app/components/neural-glow){rel=""nofollow""}.
::


# Tourbillon de particules

::component-viewer
---
component-files:
  - ParticleWhirlpoolBg.vue
component-id: bg-particle-whirlpool
config: ParticleWhirlpoolBgConfig
demo-file: ParticleWhirlpoolBgDemo.vue
dependencies: three postprocessing
dev-dependencies: "@types/three"
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                             |
| ---------------- | -------- | ----------------- | ------------------------------------------------------- |
| `class`          | `string` | `""`              | Classes CSS supplémentaires pour un style personnalisé. |
| `blur`           | `number` | `0`               | Niveau de flou appliqué au fond, en pixels.             |
| `particleCount`  | `number` | `2000`            | Nombre de particules dans l'animation de tourbillon.    |

#credits
- Réalisé avec la bibliothèque [Three.js](https://threejs.org/){rel=""nofollow""} pour le rendu et les animations 3D.
- Inspiré par [TroisJs](https://troisjs.github.io/examples/demos/3.html){rel=""nofollow""}
::


# Fond particules

::component-viewer
---
component-files:
  - ParticlesBg.vue
component-id: particles-bg
config: ParticlesBgConfig
demo-file: ParticlesBgDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                                                                                              |
| ---------------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `color`          | `string` | `#FFF`            | Code couleur hexadécimal utilisé pour les particules (3 ou 6 caractères).                                                |
| `quantity`       | `number` | `100`             | Nombre de particules générées et affichées sur le canvas.                                                                |
| `staticity`      | `number` | `50`              | Contrôle l'amplitude de mouvement des particules selon la proximité de la souris. Une valeur élevée réduit le mouvement. |
| `ease`           | `number` | `50`              | Contrôle l'effet d'easing du mouvement : plus la valeur est basse, plus les particules suivent la souris de près.        |

#credits
- Merci à [Magic UI](https://magicui.design/docs/components/particles){rel=""nofollow""} pour ce superbe composant.
- Merci à [Prodromos Pantos](https://github.com/prpanto){rel=""nofollow""} pour le portage du composant original vers Vue & Nuxt.
::


# Fond à motifs

::component-viewer
---
component-files:
  - PatternBackground.vue
  - index.ts
component-id: pattern-background
config: PatternBackgroundConfig
demo-file: PatternBackgroundDemo.vue
dependencies: class-variance-authority
---
#api
## API

| Nom de propriété | Type                                                                                                   | Valeur par défaut | Description                                                                                                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `animate`        | `boolean`                                                                                              | `false`           | Passez à `true` si vous souhaitez animer le fond.                                                                                                                        |
| `direction`      | `top` \| `bottom` \| `left` \| `right` \| `top-left` \| `top-right` \| `bottom-left` \| `bottom-right` | `top`             | Direction du mouvement d'animation. Vous pouvez utiliser la constante `PATTERN_BACKGROUND_DIRECTION`.                                                                    |
| `direction`      | `grid` \| `dot`                                                                                        | `grid`            | Type de motif. Vous pouvez utiliser la constante `PATTERN_BACKGROUND_VARIANT`.                                                                                           |
| `size`           | `xs` \| `sm` \| `md` \| `lg`                                                                           | `md`              | Taille du motif de fond.                                                                                                                                                 |
| `mask`           | `ellipse` \| `ellipse-top`                                                                             | `ellipse`         | Ajoute un masque sur le motif de fond. Vous pouvez utiliser la constante `PATTERN_BACKGROUND_MASK`.                                                                      |
| `speed`          | `number`                                                                                               | `10000`           | Durée de l'animation en `ms`. Plus la valeur est grande, plus l'animation est lente (`20000` est plus lent que `5000`). Vous pouvez utiliser `PATTERN_BACKGROUND_SPEED`. |

#credits
- Inspiré du composant [Dot Pattern de Magic UI](https://magicui.design/docs/components/dot-pattern){rel=""nofollow""}.
- Inspiré du composant [Grid Pattern de Magic UI](https://magicui.design/docs/components/grid-pattern){rel=""nofollow""}.
- Inspiré du composant [Animated Grid Pattern de Magic UI](https://magicui.design/docs/components/animated-grid-pattern){rel=""nofollow""}.
- Merci à [Nathan De Pachtere](https://nathandepachtere.com/){rel=""nofollow""} pour le portage de ce composant.
::


# Arrière-plan Ruban

::component-viewer
---
component-files:
  - RibbonBackground.vue
component-id: ribbon-background
config: RibbonBackgroundConfig
demo-file: RibbonBackgroundDemo.vue
---
#api
## API

| Nom de propriété  | Type       | Valeur par défaut                                         | Description                                                         |
| ----------------- | ---------- | --------------------------------------------------------- | ------------------------------------------------------------------- |
| `colors`          | `string[]` | `['#355070', '#6d597a', '#b56576', '#e56b6f', '#eaac8b']` | Cinq couleurs hexadécimales CSS utilisées par les rubans.           |
| `backgroundColor` | `string`   | `'#282828'`                                               | Couleur hexadécimale CSS affichée derrière les rubans.              |
| `transparent`     | `boolean`  | `false`                                                   | Rend les pixels du fond vide avec une valeur alpha de `0`.          |
| `enableShadows`   | `boolean`  | `true`                                                    | Active les ombres entre les couches de rubans superposées.          |
| `angle`           | `number`   | `0`                                                       | Fait pivoter l'ensemble des rubans en degrés.                       |
| `offsetX`         | `number`   | `0`                                                       | Déplace les rubans horizontalement en unités de viewport.           |
| `offsetY`         | `number`   | `0`                                                       | Déplace les rubans verticalement en unités de viewport.             |
| `speed`           | `number`   | `1`                                                       | Multiplie la vitesse d'animation.                                   |
| `class`           | `string`   | `—`                                                       | Classes supplémentaires appliquées à l'élément externe plein cadre. |

Le composant remplit son parent positionné le plus proche. Donnez au parent une hauteur explicite et `position: relative`.

#credits
- Rendu avec la visionneuse Shader Toy d'Inspira UI et [OGL](https://github.com/oframe/ogl){rel=""nofollow""}.
::


# Ondes concentriques

::component-viewer
---
component-files:
  - Ripple.vue
  - RippleCircle.vue
  - RippleContainer.vue
component-id: ripple
config: RippleConfig
demo-file: RippleDemo.vue
---
#api
## API

| Nom de propriété              | Type     | Valeur par défaut | Description                                              |
| ----------------------------- | -------- | ----------------- | -------------------------------------------------------- |
| `baseCircleSize`              | `number` | `210`             | Taille du cercle principal, en pixels.                   |
| `baseCircleOpacity`           | `number` | `0.24`            | Opacité du cercle principal.                             |
| `spaceBetweenCircle`          | `number` | `70`              | Espace entre chaque cercle d'ondulation, en pixels.      |
| `circleOpacityDowngradeRatio` | `number` | `0.03`            | Taux de diminution d'opacité pour chaque cercle suivant. |
| `circleClass`                 | `string` | `undefined`       | Classe(s) CSS supplémentaires pour styliser les cercles. |
| `waveSpeed`                   | `number` | `80`              | Vitesse de l'animation d'onde, en millisecondes.         |
| `numberOfCircles`             | `number` | `7`               | Nombre de cercles à afficher.                            |

#credits
- Merci à [Magic UI](https://magicui.design/docs/components/ripple){rel=""nofollow""}.
- Merci à [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} pour le portage de ce composant.
- Merci à [Nathan De Pachtere](https://nathandepachtere.com/){rel=""nofollow""} pour la mise à jour du composant.
::


# Fond soyeux

::component-viewer
---
component-files:
  - SilkBackground.vue
component-id: bg-silk
config: SilkBackgroundConfig
demo-file: SilkBackgroundDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                                              |
| ---------------- | -------- | ----------------- | ------------------------------------------------------------------------ |
| `hue`            | `number` | `300`             | Teinte de base de la texture soyeuse (en degrés, 0–360).                 |
| `saturation`     | `number` | `0.5`             | Saturation de la couleur (0–1).                                          |
| `brightness`     | `number` | `1`               | Multiplicateur de luminosité de la couleur de sortie (0–2 recommandé).   |
| `speed`          | `number` | `1`               | Multiplicateur de vitesse d'animation (ex. `2` = deux fois plus rapide). |
| `class`          | `string` | `—`               | Classes CSS optionnelles pour la div conteneur (z-index, etc.).          |

> 💡 Ce composant utilise par défaut un conteneur absolu plein écran. Vous pouvez surcharger la position ou l'empilement via la prop `class`.

#credits
- Adapté de [ce shader ShaderToy](https://www.shadertoy.com/view/X3yXRd){rel=""nofollow""} par Giorgi Azmaipharashvili (licence MIT).
- Inspiré par les textures de soie et les motifs de mouvement fluides des matériaux organiques.
::


# Fond singularité

::component-viewer
---
component-files:
  - SingularityBackground.vue
component-id: bg-singularity
config: SingularityBackgroundConfig
demo-file: SingularityBackgroundDemo.vue
---
#api
## API

| Nom de propriété   | Type     | Valeur par défaut | Description                                                            |
| ------------------ | -------- | ----------------- | ---------------------------------------------------------------------- |
| `hue`              | `number` | `0`               | Teinte de base pour la texture fractale (0–360 degrés).                |
| `saturation`       | `number` | `1`               | Saturation de la couleur (0–1).                                        |
| `brightness`       | `number` | `1`               | Multiplicateur de luminosité de la sortie (0–2 recommandé).            |
| `speed`            | `number` | `1`               | Multiplicateur de vitesse de l'animation.                              |
| `mouseSensitivity` | `number` | `0.5`             | Contrôle la réactivité aux mouvements de la souris (0–5).              |
| `damping`          | `number` | `1`               | Facteur d'amortissement pour lisser les déformations de texture (0–1). |
| `class`            | `string` | `-`               | Classes CSS supplémentaires pour le conteneur div (ex. z-index, etc.). |

> 💡 Ce composant est conçu pour être utilisé sur des fonds plein écran ou de larges sections. Il est optimisé pour les GPU modernes mais peut être exigeant sur les appareils plus modestes.

#credits
- Adapté depuis [ce shader ShaderToy](https://www.shadertoy.com/view/3csSWB){rel=""nofollow""}.
::


# Fond chute de neige

::component-viewer
---
component-files:
  - SnowfallBg.vue
component-id: snowfall-bg
config: SnowfallBgConfig
demo-file: SnowfallBgDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                           |
| ---------------- | -------- | ----------------- | ----------------------------------------------------- |
| `color`          | `string` | `#FFF`            | Couleur des flocons au format hexadécimal.            |
| `quantity`       | `number` | `100`             | Nombre de flocons à afficher.                         |
| `speed`          | `number` | `1`               | Vitesse de chute des flocons.                         |
| `maxRadius`      | `number` | `3`               | Rayon maximal des flocons.                            |
| `minRadius`      | `number` | `1`               | Rayon minimal des flocons.                            |
| `class`          | `string` | `null`            | Classes CSS supplémentaires à appliquer au conteneur. |

#credits
- Inspiré par les effets naturels de chute de neige.
::


# Étincelles

::component-viewer
---
component-files:
  - Sparkles.vue
component-id: sparkles
config: SparklesConfig
demo-file: SparklesDemo.vue
---
#api
## API

| Nom de propriété  | Type     | Valeur par défaut | Description                                                                                      |
| ----------------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------ |
| `background`      | `string` | `'#0d47a1'`       | Couleur de fond du conteneur. Utilisez `transparent` pour voir l'élément parent.                 |
| `particleColor`   | `string` | `'#ffffff'`       | Couleur des particules. Accepte toute valeur de couleur CSS valide.                              |
| `minSize`         | `number` | `1`               | Taille minimale des particules, en pixels.                                                       |
| `maxSize`         | `number` | `3`               | Taille maximale des particules, en pixels.                                                       |
| `speed`           | `number` | `4`               | Multiplicateur de vitesse de mouvement. Plus la valeur est élevée, plus le mouvement est rapide. |
| `particleDensity` | `number` | `120`             | Nombre de particules à rendre. Plus la valeur est élevée, plus le champ est dense.               |

#credits
- Merci à [M Atif](https://github.com/atif0075){rel=""nofollow""} pour le portage de ce composant.
- Porté depuis [Sparkles d'Aceternity UI](https://ui.aceternity.com/components/sparkles){rel=""nofollow""}.
::


# Fond étoilé

::component-viewer
---
component-files:
  - StarsBackground.vue
component-id: bg-stars
config: StarsBackgroundConfig
demo-file: StarsBackgroundDemo.vue
---
#api
## API

| Nom de propriété | Type            | Valeur par défaut                | Description                                                                     |
| ---------------- | --------------- | -------------------------------- | ------------------------------------------------------------------------------- |
| `factor`         | `number`        | `0.05`                           | Multiplicateur pour le mouvement de parallaxe de la souris.                     |
| `speed`          | `number`        | `50`                             | Vitesse de base (en secondes) pour l'animation de boucle verticale des couches. |
| `transition`     | `SpringOptions` | `{ stiffness: 50, damping: 20 }` | Configuration de physique à ressort pour une réponse fluide au curseur.         |
| `starColor`      | `string`        | `"#fff"`                         | Couleur des étoiles (toute valeur CSS valide).                                  |
| `class`          | `string`        | `—`                              | Classes optionnelles pour la div conteneur (pratique pour le z-index, etc.).    |

> 💡 Ce composant encapsule un slot enfant : vous pouvez placer d'autres éléments UI par-dessus le fond.

#credits
- Porté depuis [Animate UI](https://animate-ui.com/docs/backgrounds/stars){rel=""nofollow""}
::


# Fond Stractium

::component-viewer
---
component-files:
  - StractiumBackground.vue
component-id: bg-stractium
config: StractiumBackgroundConfig
demo-file: StractiumBackgroundDemo.vue
---
#api
## API

| Nom de propriété   | Type     | Valeur par défaut | Description                                                            |
| ------------------ | -------- | ----------------- | ---------------------------------------------------------------------- |
| `hue`              | `number` | `0`               | Teinte de base pour la texture fractale (0–360 degrés).                |
| `saturation`       | `number` | `1`               | Saturation de la couleur (0–1).                                        |
| `brightness`       | `number` | `1`               | Multiplicateur de luminosité de la couleur de sortie (0–2 recommandé). |
| `speed`            | `number` | `1`               | Multiplicateur de vitesse pour l'animation de texture.                 |
| `mouseSensitivity` | `number` | `0.5`             | Contrôle la réactivité de la texture aux mouvements de souris (0–1).   |
| `damping`          | `number` | `1`               | Facteur d'amortissement pour lisser les distorsions de texture (0–1).  |
| `class`            | `string` | `—`               | Classes CSS optionnelles pour la div conteneur (z-index, etc.).        |

> 💡 Ce composant est pensé pour des fonds plein écran ou de grandes sections. Il est optimisé pour les GPU modernes mais peut être exigeant sur les appareils plus modestes.

#credits
- Basé sur un fragment shader ShaderToy du créateur original des motifs fractals (licence MIT).
- Intégré dans un composant Vue et adapté pour accepter des entrées dynamiques via des props.
- Inspiré par les motifs fractals, les textures naturelles et les techniques avancées de raymarching.
::


# Tetris

::component-viewer
---
component-files:
  - Tetris.vue
component-id: tetris
config: TetrisConfig
demo-file: TetrisDemo.vue
dependencies: theme-colors
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                         |
| ---------------- | -------- | ----------------- | --------------------------------------------------- |
| `class`          | `string` | `""`              | Classes supplémentaires pour styliser le composant. |
| `base`           | `number` | `10`              | Nombre de blocs par ligne.                          |
| `square-color`   | `string` | `""`              | Couleur des blocs.                                  |

#credits
- Merci à [Whbbit1999](https://github.com/Whbbit1999){rel=""nofollow""} pour ce composant.
- Inspiré et porté depuis [Nuxt UI Home](https://ui2.nuxt.com/){rel=""nofollow""}.
::


# Fond orageux

::component-viewer
---
component-files:
  - ThunderstormBackground.vue
component-id: bg-thunderstorm
config: ThunderstormBackgroundConfig
demo-file: ThunderstormBackgroundDemo.vue
---
#api
## API

| Nom de propriété   | Type     | Valeur par défaut | Description                                                            |
| ------------------ | -------- | ----------------- | ---------------------------------------------------------------------- |
| `hue`              | `number` | `0`               | Teinte de base pour la texture fractale (0–360 degrés).                |
| `saturation`       | `number` | `1`               | Saturation de la couleur (0–1).                                        |
| `brightness`       | `number` | `1`               | Multiplicateur de luminosité de la sortie (0–2 recommandé).            |
| `speed`            | `number` | `1`               | Multiplicateur de vitesse de l'animation.                              |
| `mouseSensitivity` | `number` | `0.5`             | Contrôle la réactivité aux mouvements de la souris (0–5).              |
| `damping`          | `number` | `1`               | Facteur d'amortissement pour lisser les déformations de texture (0–1). |
| `class`            | `string` | `-`               | Classes CSS supplémentaires pour le conteneur div (ex. z-index, etc.). |

> 💡 Ce composant est conçu pour être utilisé sur des fonds plein écran ou de larges sections. Il est optimisé pour les GPU modernes mais peut être exigeant sur les appareils plus modestes.

#credits
- Adapté depuis [ce shader ShaderToy](https://www.shadertoy.com/view/W3d3z7){rel=""nofollow""}.
::


# Texte vidéo

::component-viewer
---
component-files:
  - VideoText.vue
component-id: video-text
config: VideoTextConfig
demo-file: VideoTextDemo.vue
---
#api
## API

| Nom de propriété   | Type                           | Valeur par défaut | Description                                   |
| ------------------ | ------------------------------ | ----------------- | --------------------------------------------- |
| `src`              | `string`                       | Requise           | URL source de la vidéo.                       |
| `class`            | `string`                       | `""`              | Classes supplémentaires pour le conteneur.    |
| `autoPlay`         | `boolean`                      | `true`            | Indique si la vidéo se lance automatiquement. |
| `muted`            | `boolean`                      | `true`            | Indique si la vidéo est muette.               |
| `loop`             | `boolean`                      | `true`            | Indique si la vidéo boucle.                   |
| `preload`          | `"auto" | "metadata" | "none"` | `"auto"`          | Indique si la vidéo est préchargée.           |
| `fontSize`         | `string | number`              | `"120"`           | Taille de police pour le masque de texte.     |
| `fontWeight`       | `string | number`              | `"bold"`          | Graisse de police pour le masque de texte.    |
| `textAnchor`       | `string`                       | `"middle"`        | Ancre de texte pour le masque.                |
| `dominantBaseline` | `string`                       | `"middle"`        | Ligne de base dominante pour le masque.       |
| `fontFamily`       | `string`                       | `"sans-serif"`    | Famille de police pour le masque de texte.    |

#credits
- Merci à [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} pour ce composant.
- Porté depuis [Video Text de Magic UI](https://magicui.design/docs/components/video-text){rel=""nofollow""}.
::


# Fond vortex

::component-viewer
---
component-files:
  - Vortex.vue
component-id: vortex
config: VortexConfig
demo-file: VortexDemo.vue
dependencies: simplex-noise
---
#api
## API

| Nom de propriété  | Type     | Valeur par défaut | Description                                          |
| ----------------- | -------- | ----------------- | ---------------------------------------------------- |
| `class`           | `string` |                   | Classe optionnelle pour styliser le wrapper enfants. |
| `containerClass`  | `string` |                   | Classe optionnelle pour styliser le conteneur.       |
| `particleCount`   | `number` | `700`             | Nombre de particules générées.                       |
| `rangeY`          | `number` | `100`             | Amplitude verticale du mouvement des particules.     |
| `baseHue`         | `number` | `220`             | Teinte de base pour la couleur des particules.       |
| `baseSpeed`       | `number` | `0.0`             | Vitesse de base du mouvement des particules.         |
| `rangeSpeed`      | `number` | `1.5`             | Amplitude de variation de vitesse des particules.    |
| `baseRadius`      | `number` | `1`               | Rayon de base des particules.                        |
| `rangeRadius`     | `number` | `2`               | Amplitude de variation de rayon des particules.      |
| `backgroundColor` | `string` | `"#000000"`       | Couleur de fond du canvas.                           |

#credits
- Merci à [Aceternity UI](https://ui.aceternity.com/components/vortex){rel=""nofollow""}.
- Merci à [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} pour le portage de ce composant.
::


# Fond Warp

::component-viewer
---
component-files:
  - WarpBackground.vue
  - Beam.vue
component-id: warp-background
config: WarpBackgroundConfig
demo-file: WarpBackgroundDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut      | Description                            |
| ---------------- | -------- | ---------------------- | -------------------------------------- |
| `perspective`    | `number` | `100`                  | Perspective de l'animation warp.       |
| `beamsPerSide`   | `number` | `3`                    | Nombre de rayons par côté.             |
| `beamSize`       | `number` | `5`                    | Taille des rayons.                     |
| `beamDelayMax`   | `number` | `3`                    | Délai maximum des rayons, en secondes. |
| `beamDelayMin`   | `number` | `0`                    | Délai minimum des rayons, en secondes. |
| `beamDuration`   | `number` | `3`                    | Durée d'animation des rayons.          |
| `gridColor`      | `string` | `"hsl(var(--border))"` | Couleur des lignes de la grille.       |

#credits
- Merci à [Whbbit1999](https://github.com/Whbbit1999){rel=""nofollow""} pour ce composant.
- Inspiré et porté depuis [Magic UI WarpBackground](https://magicui.design/docs/components/warp-background){rel=""nofollow""}.
::


# Fond ondulé

::component-viewer
---
component-files:
  - WavyBackground.vue
component-id: wavy-background
config: WavyBackgroundConfig
demo-file: WavyBackgroundDemo.vue
dependencies: simplex-noise
---
#api
## API

| Nom de propriété | Type              | Valeur par défaut                                         | Description                                   |
| ---------------- | ----------------- | --------------------------------------------------------- | --------------------------------------------- |
| `class`          | `string`          | `-`                                                       | Contenu affiché au-dessus du fond ondulé.     |
| `containerClass` | `string`          | `-`                                                       | Classe CSS appliquée au conteneur de contenu. |
| `colors`         | `string[]`        | `["#38bdf8", "#818cf8", "#c084fc", "#e879f9", "#22d3ee"]` | Couleurs des vagues.                          |
| `waveWidth`      | `number`          | `50`                                                      | Largeur des vagues.                           |
| `backgroundFill` | `string`          | `"black"`                                                 | Couleur de fond.                              |
| `blur`           | `number`          | `10`                                                      | Effet de flou appliqué aux vagues.            |
| `speed`          | `"slow" | "fast"` | `"fast"`                                                  | Vitesse des vagues.                           |
| `waveOpacity`    | `number`          | `0.5`                                                     | Opacité de base des vagues.                   |
| `[key: string]`  | `any`             | `-`                                                       | Entrées supplémentaires facultatives.         |

#credits
- Merci à [Aceternity UI](https://ui.aceternity.com/components/wavy-background){rel=""nofollow""}.
- Merci à [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} pour le portage de ce composant.
::


# Bouton dégradé

::component-viewer
---
component-files:
  - GradientButton.vue
component-id: gradient-button
config: GradientButtonConfig
demo-file: GradientButtonDemo.vue
---
#api
## API

| Nom de propriété | Type       | Valeur par défaut   | Description                                                        |
| ---------------- | ---------- | ------------------- | ------------------------------------------------------------------ |
| `borderWidth`    | `number`   | `2`                 | Largeur, en pixels, de la bordure dégradée.                        |
| `colors`         | `string[]` | Tableau de couleurs | Tableau des couleurs utilisées pour la bordure en dégradé conique. |
| `duration`       | `number`   | `2500`              | Durée de l'animation de rotation du dégradé en millisecondes.      |
| `borderRadius`   | `number`   | `8`                 | Rayon des coins arrondis, en pixels.                               |
| `blur`           | `number`   | `4`                 | Intensité du flou de l'effet de bordure dégradée, en pixels.       |
| `class`          | `string`   | `""`                | Classes CSS supplémentaires pour un style personnalisé.            |
| `bgColor`        | `string`   | `"#000"`            | Couleur de fond du contenu du bouton.                              |
::


# Bouton interactif au survol

::component-viewer
---
component-files:
  - InteractiveHoverButton.vue
component-id: interactive-hover-button
config: InteractiveHoverButtonConfig
demo-file: InteractiveHoverButtonDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                         |
| ---------------- | -------- | ----------------- | --------------------------------------------------- |
| `text`           | `string` | `Button`          | Texte affiché à l'intérieur du bouton.              |
| `class`          | `string` | `""`              | Classes supplémentaires pour styliser le composant. |

#credits
- Merci à [Whbbit1999](https://github.com/Whbbit1999){rel=""nofollow""} pour ce composant.
- Inspiré et porté depuis [Magic UI Interactive Hover Button](https://magicui.design/docs/components/interactive-hover-button){rel=""nofollow""}.
::


# Bouton arc-en-ciel

::component-viewer
---
component-files:
  - RainbowButton.vue
component-id: rainbow-button
config: RainbowButtonConfig
demo-file: RainbowButtonDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                        |
| ---------------- | -------- | ----------------- | -------------------------------------------------- |
| `class`          | `string` | `""`              | Classes CSS supplémentaires à appliquer au bouton. |
| `is`             | `string` | `"button"`        | Balise HTML utilisée pour rendre le composant.     |
| `speed`          | `number` | `2`               | Durée de l'animation en secondes.                  |

#credits
- Merci à [Grzegorz Krol](https://github.com/Grzechu335){rel=""nofollow""} d'avoir porté ce composant.
- Merci à [Magic UI](https://magicui.design/docs/components/rainbow-button){rel=""nofollow""}.
::


# Bouton à ondulation

::component-viewer
---
component-files:
  - RippleButton.vue
component-id: ripple-button
config: RippleButtonConfig
demo-file: RippleButtonDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                             |
| ---------------- | -------- | ----------------- | ------------------------------------------------------- |
| `class`          | `string` | -                 | Classes CSS supplémentaires pour un style personnalisé. |
| `rippleColor`    | `string` | `"#ADD8E6"`       | Couleur de l'effet d'onde.                              |
| `duration`       | `number` | `600`             | Durée de l'animation de l'onde en millisecondes.        |

## Événements émis

| Nom de l'événement | Type    | Description    |
| ------------------ | ------- | -------------- |
| `click`            | `event` | Événement clic |

#credits
- Inspiré par le composant [Ripple Button de Magic UI](https://magicui.design/docs/components/ripple-button){rel=""nofollow""}.
- Merci à [kalix127](https://github.com/kalix127){rel=""nofollow""} pour le portage de ce composant.
::


# Bouton scintillant

::component-viewer
---
component-files:
  - ShimmerButton.vue
component-id: shimmer-button
config: ShimmerButtonConfig
demo-file: ShimmerButtonDemo.vue
---
#api
## API

| Nom de propriété  | Type     | Valeur par défaut    | Description                                               |
| ----------------- | -------- | -------------------- | --------------------------------------------------------- |
| `class`           | `string` | `""`                 | Classes CSS supplémentaires à appliquer au bouton.        |
| `shimmerColor`    | `string` | `"#ffffff"`          | Couleur de l'effet scintillant.                           |
| `shimmerSize`     | `string` | `"0.05em"`           | Taille de l'effet scintillant.                            |
| `borderRadius`    | `string` | `"100px"`            | Rayon des coins du bouton.                                |
| `shimmerDuration` | `string` | `"3s"`               | Durée de l'animation scintillante.                        |
| `background`      | `string` | `"rgba(0, 0, 0, 1)"` | Couleur de fond du bouton, en rgb ou en code hexadécimal. |

#credits
- Porté depuis [Magic UI Shimmer Button](https://magicui.design/docs/components/shimmer-button){rel=""nofollow""}.
::


# Effet de carte 3D

::component-viewer
---
component-files:
  - CardContainer.vue
  - CardBody.vue
  - CardItem.vue
  - useMouseState.ts
component-id: card-3d
config: Card3dConfig
demo-file: CardDemo.vue
---
#api
## API

### `CardContainer`

Le composant `CardContainer` sert de conteneur pour l'effet de carte 3D. Il gère les événements souris pour créer la perspective.

#### Props

| Nom de propriété | Type   | Valeur par défaut | Description                                                 |
| ---------------- | ------ | ----------------- | ----------------------------------------------------------- |
| `class`          | string | `null`            | Classes supplémentaires pour styliser le conteneur interne. |
| `containerClass` | string | `null`            | Classes supplémentaires pour styliser le conteneur externe. |

---

### `CardBody`

Le composant `CardBody` est un conteneur flexible qui conserve le style 3D. Il est destiné à être utilisé dans un `CardContainer` pour accueillir du contenu avec un effet de transformation 3D.

#### Props

| Nom de propriété | Type   | Valeur par défaut | Description                                         |
| ---------------- | ------ | ----------------- | --------------------------------------------------- |
| `class`          | string | `null`            | Classes supplémentaires pour un style personnalisé. |

---

### `CardItem`

Le composant `CardItem` représente les éléments individuels de la carte 3D. Il prend en charge diverses transformations (translation et rotation) pour créer des effets 3D dynamiques.

#### Props

| Nom de propriété | Type   | Valeur par défaut | Description                                                   |
| ---------------- | ------ | ----------------- | ------------------------------------------------------------- |
| `as`             | string | `"div"`           | Balise HTML ou composant à utiliser pour l'élément.           |
| `class`          | string | `null`            | Classes supplémentaires pour styliser l'élément.              |
| `translateX`     | string | `0`               | Translation sur l'axe X, en pixels.                           |
| `translateY`     | string | `0`               | Translation sur l'axe Y, en pixels.                           |
| `translateZ`     | string | `0`               | Translation sur l'axe Z, en pixels, pour gérer la profondeur. |
| `rotateX`        | string | `0`               | Rotation sur l'axe X, en degrés.                              |
| `rotateY`        | string | `0`               | Rotation sur l'axe Y, en degrés.                              |
| `rotateZ`        | string | `0`               | Rotation sur l'axe Z, en degrés.                              |

---

> 💡 ***Note importante :***
>
> Si vous utilisez `CardItem` dans une `div`, ajoutez `style="transform-style: preserve-3d;"` sur la div pour que la prop `translate-z` fonctionne.

#credits
- Porté depuis le composant 3D Card d'Aceternity UI.
::


# Carrousel de cartes Apple

::component-viewer
---
component-files:
  - AppleCardCarousel.vue
  - AppleCarouselItem.vue
  - AppleCard.vue
  - AppleBlurImage.vue
  - AppleCarouselContext.ts
component-id: apple-card-carousel
config: AppleCardCarouselConfig
demo-file: AppleCardCarouselDemo.vue
---
#api
La suite **Apple Carousel** se compose de quatre composants liés :

| Composant           | Rôle                                                                        |
| ------------------- | --------------------------------------------------------------------------- |
| `AppleCardCarousel` | Le conteneur de défilement horizontal avec contrôles gauche / droite.       |
| `AppleCarouselItem` | Un wrapper qui ajoute animation d'entrée et espacement à chaque carte.      |
| `AppleCard`         | Une carte riche et cliquable pouvant s'étendre en modal plein écran.        |
| `AppleBlurImage`    | Un remplacement de `<img>` qui démarre flou jusqu'au chargement de l'image. |

Ensemble, ils reproduisent l'expérience de navigation interactive type App Store / Apple TV.

---

## `AppleCardCarousel`

| Propriété       | Type     | Valeur par défaut | Description                                      |
| --------------- | -------- | ----------------- | ------------------------------------------------ |
| `initialScroll` | `number` | `0`               | Décalage horizontal appliqué au montage (en px). |

### Slots

Le slot par défaut doit contenir un ou plusieurs composants **`AppleCarouselItem`**.

### Événements émis

*Aucun événement personnalisé.*

---

## `AppleCarouselItem`

| Propriété | Type     | Obligatoire | Description                                                            |
| --------- | -------- | ----------- | ---------------------------------------------------------------------- |
| `index`   | `number` | ✓           | Index basé sur zéro, utilisé pour échelonner l'animation d'apparition. |

### Slots

Slot par défaut — placez ici une **`AppleCard`**.

---

## `AppleCard`

| Propriété | Type                                               | Obligatoire | Valeur par défaut | Description                                  |
| --------- | -------------------------------------------------- | ----------- | ----------------- | -------------------------------------------- |
| `card`    | `{ src: string; title: string; category: string }` | ✓           | —                 | Objet de données de la carte.                |
| `index`   | `number`                                           | ✓           | —                 | Position dans le carrousel.                  |
| `layout`  | `boolean`                                          | ✕           | `false`           | Active l'animation FLIP avec layout partagé. |

### Slots

Lorsque la carte est **étendue** (modal ouverte), le slot par défaut s'affiche dans le corps de la modal ; vous pouvez y injecter du contenu enrichi comme du texte, des images ou des vidéos.

### Événements émis

*Aucun événement personnalisé (repose sur le contexte injecté `CarouselKey`).*

---

## `AppleBlurImage`

| Propriété | Type              | Valeur par défaut                | Description                                                                |
| --------- | ----------------- | -------------------------------- | -------------------------------------------------------------------------- |
| `src`     | `string`          | **—**                            | URL de l'image. *Requise.*                                            |
| `alt`     | `string`          | "Background of a beautiful view" | Texte alternatif.                                                          |
| `width`   | `number | string` | *taille naturelle de l'image*    | Attribut de largeur ; omis lors de l'utilisation de `fill`.                |
| `height`  | `number | string` | *taille naturelle de l'image*    | Attribut de hauteur ; omis lors de l'utilisation de `fill`.                |
| `fill`    | `boolean`         | `false`                          | Si `true`, applique `width:100%; height:100%` via des classes utilitaires. |
| `class`   | `string`          | `""`                             | Classes supplémentaires fusionnées via `cn()`.                             |

Lorsque l'image déclenche l'événement natif `load`, elle passe en douceur de `blur-sm` à sans flou.

---

#credits
- Porté depuis [Aceternity UI Apple Card Carousel](https://ui.aceternity.com/components/apple-cards-carousel){rel=""nofollow""}.
::


# Carte avec spot lumineux

::component-viewer
---
component-files:
  - CardSpotlight.vue
component-id: card-spotlight
config: CardSpotlightConfig
demo-file: CardSpotlightDemo.vue
---
#api
## API

| Nom de propriété  | Type     | Valeur par défaut | Description                                     |
| ----------------- | -------- | ----------------- | ----------------------------------------------- |
| `gradientSize`    | `number` | `200`             | Rayon de l'effet de spot, en pixels.            |
| `gradientColor`   | `string` | `'#262626'`       | Couleur du dégradé du spot.                     |
| `gradientOpacity` | `number` | `0.8`             | Niveau d'opacité du dégradé du spot.            |
| `slotClass`       | `string` | `undefined`       | Classe à appliquer au conteneur parent du slot. |

#credits
- Inspiré du composant Magic Card de [Magic UI](https://magicui.design/docs/components/magic-card){rel=""nofollow""}.
::


# Pile de cartes

::component-viewer
---
component-files:
  - CardStack.vue
  - CardStackItem.vue
  - CardStackContext.ts
  - index.ts
component-id: card-stack
config: CardStackConfig
demo-file: CardStackDemo.vue
---
#api
## API

### CardStack

| Nom de prop       | Type               | Valeur par défaut                        | Description                                    |
| ----------------- | ------------------ | ---------------------------------------- | ---------------------------------------------- |
| `totalCards`      | `number`           | —                                        | Nombre total de cartes utilisé pour le calcul. |
| `scaleMultiplier` | `number`           | `0.03`                                   | Intensité de réduction pendant le défilement.  |
| `scrollOptions`   | `UseScrollOptions` | `{ offset: ["start start", "end end"] }` | Options de défilement Motion, avec conteneur.  |
| `class`           | `string`           | `-`                                      | Classes supplémentaires du conteneur.          |

### CardStackItem

| Nom de prop   | Type     | Valeur par défaut | Description                               |
| ------------- | -------- | ----------------- | ----------------------------------------- |
| `index`       | `number` | —                 | Index de la carte utilisé pour le calcul. |
| `topPosition` | `string` | `5 + index * 3%`  | Décalage supérieur sticky de la carte.    |
| `class`       | `string` | `-`               | Classes supplémentaires du wrapper.       |

## Utilisation

Utilisez `CardStack` comme parent et placez un `CardStackItem` autour de chaque carte. Définissez une hauteur pour chaque élément afin de laisser le défilement sticky progresser.

```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
- Porté depuis [Fancy Components](https://fancycomponents.dev/docs/components/blocks/stacking-cards){rel=""nofollow""}.
::


# Carrousel cube

::component-viewer
---
component-files:
  - CubeCarousel.vue
  - index.ts
component-id: cube-carousel
config: CubeCarouselConfig
demo-file: CubeCarouselDemo.vue
---
#api
## API

### `CubeCarousel`

| Nom de prop        | Type                                  | Valeur par défaut                                 | Description                                            |
| ------------------ | ------------------------------------- | ------------------------------------------------- | ------------------------------------------------------ |
| `items`            | `CubeCarouselItem[]`                  | —                                                 | Images ou vidéos à placer sur les faces du cube.       |
| `width`            | `number`                              | —                                                 | Largeur de chaque face en pixels.                      |
| `height`           | `number`                              | —                                                 | Hauteur de chaque face en pixels.                      |
| `class`            | `string`                              | —                                                 | Classes supplémentaires de la racine.                  |
| `debug`            | `boolean`                             | `false`                                           | Affiche les couleurs et les identifiants des faces.    |
| `perspective`      | `number`                              | `600`                                             | Distance de perspective CSS en pixels.                 |
| `direction`        | `"top" | "bottom" | "left" | "right"` | `"left"`                                          | Axe et direction de rotation.                          |
| `transition`       | `Record<string, unknown>`             | `{ duration: 1.25, ease: [...] }`                 | Transition Motion des rotations par bouton et clavier. |
| `snapTransition`   | `Record<string, unknown>`             | `{ type: "spring", damping: 30, stiffness: 200 }` | Transition d’aimantation après un glissement.          |
| `dragSpring`       | `CubeCarouselSpringConfig`            | `{ stiffness: 200, damping: 30 }`                 | Ressort utilisé pendant le glissement.                 |
| `autoPlay`         | `boolean`                             | `false`                                           | Avance automatiquement entre les éléments.             |
| `autoPlayInterval` | `number`                              | `3000`                                            | Délai entre les rotations, en millisecondes.           |
| `onIndexChange`    | `(index: number) => void`             | —                                                 | Appelé à la fin d’une rotation.                        |
| `enableDrag`       | `boolean`                             | `true`                                            | Active le glissement à la souris et au toucher.        |
| `dragSensitivity`  | `number`                              | `0.5`                                             | Rotation produite par le mouvement du pointeur.        |

### `CubeCarouselItem`

| Propriété | Type                | Requis | Description                      |
| --------- | ------------------- | ------ | -------------------------------- |
| `id`      | `string`            | Oui    | Identifiant stable de l’élément. |
| `type`    | `"image" | "video"` | Oui    | Choisit le moteur de rendu.      |
| `src`     | `string`            | Oui    | URL de l’image ou de la vidéo.   |
| `alt`     | `string`            | Non    | Texte alternatif de l’image.     |
| `poster`  | `string`            | Non    | Image poster de la vidéo.        |

## Interaction

Faites glisser le long de l’axe du carrousel pour le faire tourner. Au relâchement, il s’aligne sur le quart de tour le plus proche. Une fois focalisé, utilisez les flèches correspondant à l’axe de rotation. Les méthodes `next`, `prev` et `getCurrentItemIndex` sont également exposées via une ref.

#credits
- Porté depuis [Fancy Components Box Carousel](https://fancycomponents.dev/docs/components/carousel/box-carousel){rel=""nofollow""}.
- Images de démonstration par [Daniel Petho](https://www.cosmos.so/danielpetho/box-carousel-demo){rel=""nofollow""}.
- Inspiré par [Framer University](https://framer.university/resources/3d-box-carousel-in-framer){rel=""nofollow""}.
::


# Carte sensible à la direction du survol

::component-viewer
---
component-files:
  - DirectionAwareHover.vue
component-id: direction-aware-hover
config: DirectionAwareHoverConfig
demo-file: DirectionAwareHoverDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                                   |
| ---------------- | -------- | ----------------- | ------------------------------------------------------------- |
| `imageUrl`       | `string` | Requise           | URL de l'image à afficher.                                    |
| `class`          | `string` | `undefined`       | Classes CSS supplémentaires pour le conteneur de carte.       |
| `imageClass`     | `string` | `undefined`       | Classes CSS supplémentaires pour l'élément image.             |
| `childrenClass`  | `string` | `undefined`       | Classes CSS supplémentaires pour la superposition de contenu. |

#credits
- Merci à [M Atif](https://github.com/atif0075){rel=""nofollow""} pour le portage de ce composant.
- Porté depuis [Direction Aware Hover d'Aceternity UI](https://ui.aceternity.com/components/direction-aware-hover){rel=""nofollow""}
::


# Fey Cards

::component-viewer
---
component-files:
  - FeyCards.vue
component-id: fey-cards
config: FeyCardsConfig
demo-file: FeyCardsDemo.vue
---
#api
## API

| Nom de propriété  | Type           | Valeur par défaut                                      | Description                                                                     |
| ----------------- | -------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------- |
| `imgSrc`          | `string[]`     | `[]`                                                   | Tableau de sources d’images utilisées pour les cartes empilées.                 |
| `mainImg`         | `string`       | `-`                                                    | Image principale affichée derrière la pile de cartes.                           |
| `idleImg`         | `string`       | `-`                                                    | Image d’attente affichée avant l’effet de swap au survol.                       |
| `cardSpacing`     | `number`       | `32`                                                   | Espacement horizontal entre les cartes.                                         |
| `spring`          | `SpringConfig` | `{ type: "spring", visualDuration: 0.5, bounce: 0.2 }` | Configuration du ressort de motion pour les animations d’entrée et de décalage. |
| `shiftDistance`   | `number`       | `60`                                                   | Distance de déplacement horizontal des cartes quand l’état de survol est actif. |
| `swapDuration`    | `number`       | `0.5`                                                  | Durée de la transition de swap d’image, en secondes.                            |
| `entranceStagger` | `number`       | `0.2`                                                  | Délai entre les animations d’entrée de chaque carte.                            |
| `class`           | `string`       | `-`                                                    | Classes Tailwind supplémentaires appliquées au conteneur.                       |

#credits
- Inspiré par [Aceternity UI](https://ui.aceternity.com/labs/fey-card){rel=""nofollow""}.
::


# Carte rotative

::component-viewer
---
component-files:
  - FlipCard.vue
component-id: flip-card
config: FlipCardConfig
demo-file: FlipCardDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                           |
| ---------------- | -------- | ----------------- | ------------------------------------- |
| `class`          | `string` | `-`               | Classe appliquée au composant.        |
| `rotate`         | `x | y`  | `y`               | Valeur d'axe de rotation à appliquer. |

| Nom du slot | Description                      |
| ----------- | -------------------------------- |
| `default`   | Composant affiché en face avant. |
| `back`      | Composant affiché au dos.        |

#credits
- Merci à [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} pour ce composant.
::


# Floating Card

::component-viewer
---
component-files:
  - FloatingCard.vue
component-id: floating-card
config: FloatingCardConfig
demo-file: FloatingCardDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                                     |
| ---------------- | -------- | ----------------- | --------------------------------------------------------------- |
| `rotateDepth`    | `number` | `17.5`            | Rotation X/Y maximale appliquée quand la carte est survolée.    |
| `translateDepth` | `number` | `20`              | Translation X/Y maximale appliquée pendant le suivi du curseur. |
| `class`          | `string` | `-`               | Classes Tailwind supplémentaires appliquées au conteneur.       |

#credits
- Inspiré par [Aceternity UI](https://ui.aceternity.com/components/comet-card){rel=""nofollow""}.
::


# Carte avec reflet

::component-viewer
---
component-files:
  - GlareCard.vue
component-id: glare-card
config: GlareCardConfig
demo-file: GlareCardDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                                  |
| ---------------- | -------- | ----------------- | ------------------------------------------------------------ |
| `class`          | `string` | `-`               | Classes Tailwind CSS supplémentaires à appliquer à la carte. |

#credits
- Merci à [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} pour ce composant.
- Inspiré par [Aceternity UI](https://ui.aceternity.com/components/glare-card){rel=""nofollow""}.
::


# Curseur fluide

::component-viewer
---
component-files:
  - FluidCursor.vue
component-id: fluid-cursor
config: FluidCursorConfig
demo-file: FluidCursorDemo.vue
---
#api
## API

| Nom de propriété      | Type      | Valeur par défaut        | Description                                                                                |
| --------------------- | --------- | ------------------------ | ------------------------------------------------------------------------------------------ |
| `simResolution`       | `number`  | `128`                    | Résolution de la grille de simulation, influe sur le niveau de détail et les performances. |
| `dyeResolution`       | `number`  | `1440`                   | Résolution de la texture de couleur (dye) du fluide.                                       |
| `captureResolution`   | `number`  | `512`                    | Résolution pour la capture des événements d'entrée.                                        |
| `densityDissipation`  | `number`  | `3.5`                    | Taux de dissipation de la densité de couleur au fil du temps.                              |
| `velocityDissipation` | `number`  | `2`                      | Taux de dissipation de la vélocité, influence la persistance du mouvement du fluide.       |
| `pressure`            | `number`  | `0.1`                    | Facteur de pression utilisé dans les calculs de physique du fluide.                        |
| `pressureIterations`  | `number`  | `20`                     | Nombre d'itérations pour l'exactitude du solveur de pression.                              |
| `curl`                | `number`  | `3`                      | Intensité de l'effet de tourbillon/vorticité pour renforcer les mouvements rotatifs.       |
| `splatRadius`         | `number`  | `0.2`                    | Rayon de l'effet de projection du pointeur dans le fluide.                                 |
| `splatForce`          | `number`  | `6000`                   | Force appliquée par le pointeur lors de l'interaction avec le fluide.                      |
| `shading`             | `boolean` | `true`                   | Active ou désactive les effets d'ombrage pour la profondeur et la lumière.                 |
| `colorUpdateSpeed`    | `number`  | `10`                     | Vitesse de mise à jour dynamique des couleurs du pointeur.                                 |
| `backColor`           | `object`  | `{ r: 0.5, g: 0, b: 0 }` | Couleur de fond du fluide au format RGB.                                                   |
| `transparent`         | `boolean` | `true`                   | Indique si le fond du canvas est transparent.                                              |
| `class`               | `string`  | `undefined`              | Classes CSS supplémentaires pour la div conteneur externe.                                 |

#credits
- Inspiré du [Fluid Cursor de Cursify](https://cursify.vercel.app/components/fluid-cursor){rel=""nofollow""}
- Utilise un contexte WebGL 1/2 et des shaders GLSL personnalisés pour la physique et le rendu du fluide.
::


# Curseur à traînée d'images

::component-viewer
---
component-files:
  - ImageTrailCursor.vue
  - trail-variants.ts
component-id: image-trail-cursor
config: ImageTrailCursorConfig
demo-file: ImageTrailCursorDemo.vue
dependencies: gsap
---
#api
## API

| Nom de propriété | Type          | Valeur par défaut | Description                                                |
| ---------------- | ------------- | ----------------- | ---------------------------------------------------------- |
| `images`         | `string[]`    | `[]`              | Tableau d'URL d'images à afficher dans l'effet de traînée. |
| `variant`        | `VariantType` | `"type1"`         | Type de variante d'animation (`"type1"` à `"type7"`).      |

> 💡 Ce composant crée un conteneur pleine largeur et pleine hauteur avec un z-index élevé pour le suivi du curseur. Chaque image fait 190px de large, avec un ratio 1.1 et des coins arrondis.

#credits
- Inspiré par les effets modernes de traînée de curseur et les interactions au survol d'images.
- Construit avec l'API de composition Vue 3 pour une réactivité optimale.
- Porté depuis [l'article Codrops](https://tympanus.net/codrops/2023/10/18/ideas-for-image-motion-trail-animations/){rel=""nofollow""}
::


# Curseur ligne fluide

::component-viewer
---
component-files:
  - SleekLineCursor.vue
component-id: sleek-line-cursor
config: SleekLineCursorConfig
demo-file: SleekLineCursorDemo.vue
---
## API

| Nom de propriété | Type                | Valeur par défaut | Description                                                                   |
| ---------------- | ------------------- | ----------------- | ----------------------------------------------------------------------------- |
| `class`          | `string | string[]` | `undefined`       | Classes CSS supplémentaires pour le conteneur du canvas.                      |
| `trails`         | `number`            | `20`              | Nombre de lignes de traînée rendues derrière le curseur.                      |
| `size`           | `number`            | `50`              | Nombre de nœuds reliés par ressort pour chaque traînée.                       |
| `friction`       | `number`            | `0.5`             | Friction globale appliquée à la vélocité.                                     |
| `dampening`      | `number`            | `0.25`            | Amortissement de la vélocité entre les nœuds connectés.                       |
| `tension`        | `number`            | `0.98`            | Réduit l'intensité du ressort le long de la traînée pour un mouvement fluide. |

> 💡 Ce composant utilise `pointer-events-none` et est fixé en plein écran par défaut. Vous pouvez étendre ou surcharger son style via la prop `class`.

#credits
- Porté depuis [Canvas Cursor par Cursify](https://cursify.vercel.app/components/canvas-cursor){rel=""nofollow""}.
::


# Curseur fluide

::component-viewer
---
component-files:
  - SmoothCursor.vue
component-id: smooth-cursor
config: SmoothCursorConfig
demo-file: SmoothCursorDemo.vue
---
#api
## API

| Nom de propriété | Type           | Valeur par défaut | Description                                                         |
| ---------------- | -------------- | ----------------- | ------------------------------------------------------------------- |
| `cursor`         | `Component`    | `DefaultCursor`   | Composant de curseur personnalisé remplaçant le curseur par défaut. |
| `springConfig`   | `SpringConfig` | `Voir ci-dessous` | Objet de configuration pour le comportement d'animation à ressort.  |

### Type SpringConfig

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

#credits
- Merci à [Whbbit1999](https://github.com/Whbbit1999){rel=""nofollow""} pour ce composant.
- Porté depuis [Magic UI Smooth Cursor](https://magicui.design/docs/components/smooth-cursor){rel=""nofollow""}.
::


# Curseur à ruban

::component-viewer
---
component-files:
  - TailedCursor.vue
component-id: tailed-cursor
config: TailedCursorConfig
demo-file: TailedCursorDemo.vue
dependencies: ogl
---
#api
## API

| Nom de propriété     | Type       | Valeur par défaut                              | Description                                                      |
| -------------------- | ---------- | ---------------------------------------------- | ---------------------------------------------------------------- |
| `colors`             | `string[]` | `["#ff9346", "#7cff67", "#ffee51", "#00d8ff"]` | Tableau des couleurs pour chaque ruban.                          |
| `baseSpring`         | `number`   | `0.03`                                         | Force du ressort pour la réactivité du mouvement de la traînée.  |
| `baseFriction`       | `number`   | `0.9`                                          | Facteur de friction ralentissant le mouvement de la traînée.     |
| `baseThickness`      | `number`   | `30`                                           | Épaisseur de base des rubans.                                    |
| `offsetFactor`       | `number`   | `0.05`                                         | Facteur de décalage horizontal entre chaque ligne de ruban.      |
| `maxAge`             | `number`   | `500`                                          | Âge maximal des segments de traînée contrôlant leur atténuation. |
| `pointCount`         | `number`   | `50`                                           | Nombre de points composant chaque ruban.                         |
| `speedMultiplier`    | `number`   | `0.6`                                          | Multiplicateur de vitesse contrôlant la rapidité de l'animation. |
| `enableFade`         | `boolean`  | `false`                                        | Active l'effet de fondu sur les bords du ruban.                  |
| `enableShaderEffect` | `boolean`  | `false`                                        | Active l'effet de vague via shader sur les rubans.               |
| `effectAmplitude`    | `number`   | `2`                                            | Amplitude de l'effet de vague du shader lorsqu'il est activé.    |
| `backgroundColor`    | `number[]` | `[0, 0, 0, 0]`                                 | Couleur de fond (RGBA) pour l'effacement du canvas WebGL.        |

#credits
- Construit avec [OGL](https://github.com/oframe/ogl){rel=""nofollow""}, un framework WebGL léger.
- Inspiré par [l'article Codrops](https://tympanus.net/codrops/2019/09/24/crafting-stylised-mouse-trails-with-ogl/){rel=""nofollow""}
::


# Maquette iPhone

::component-viewer
---
component-files:
  - iPhone15ProMockup.vue
component-id: iphone-mockup
config: iPhone15ProMockupConfig
demo-file: iPhone15ProMockupDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                 |
| ---------------- | -------- | ----------------- | ------------------------------------------- |
| `width`          | `number` | `433`             | Largeur de la maquette SVG en pixels.       |
| `height`         | `number` | `882`             | Hauteur de la maquette SVG en pixels.       |
| `src`            | `string` | `null`            | URL de l'image à afficher dans la maquette. |

#credits
- Porté depuis [Magic UI](https://magicui.design/docs/components/iphone-15-pro){rel=""nofollow""}.
::


# Maquette Safari

::component-viewer
---
component-files:
  - SafariMockup.vue
component-id: safari-mockup
config: SafariMockupConfig
demo-file: SafariMockupDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                          |
| ---------------- | -------- | ----------------- | ---------------------------------------------------- |
| `url`            | `string` | `null`            | URL affichée dans la barre d'adresse de la maquette. |
| `src`            | `string` | `null`            | URL de l'image à afficher dans la maquette.          |
| `width`          | `number` | `1203`            | Largeur de la maquette SVG en pixels.                |
| `height`         | `number` | `753`             | Hauteur de la maquette SVG en pixels.                |

#credits
- Porté depuis [Magic UI](https://magicui.design/docs/components/safari){rel=""nofollow""}.
::


# HTML ASCII

::component-viewer
---
component-files:
  - HtmlAscii.vue
component-id: html-ascii
config: HtmlAsciiConfig
demo-file: HtmlAsciiDemo.vue
---
Appuyez sur la surface pour afficher les glyphes en monochrome.

#api
## API

| Prop         | Type      | Défaut  | Description                                              |
| ------------ | --------- | ------- | -------------------------------------------------------- |
| `cellSize`   | `number`  | `8`     | Taille d'une cellule. Toute valeur sous `5` utilise `5`. |
| `frameRate`  | `number`  | `60`    | Fréquence maximale de rendu.                             |
| `pixelRatio` | `number`  | `1`     | Échelle de rendu, limitée entre `0.25` et `2`.           |
| `paused`     | `boolean` | `false` | Met la boucle de rendu en pause.                         |
| `autoPause`  | `boolean` | `true`  | Met en pause hors écran ou lorsque la page est masquée.  |
| `class`      | `string`  | —       | Classes supplémentaires fusionnées avec la surface.      |

### Slots

| Slot      | Description                             |
| --------- | --------------------------------------- |
| `default` | Contenu HTML rendu à travers cet effet. |

#credits
- Technique de caractères bitmap adaptée de [movAX13h](https://www.shadertoy.com/user/movAX13h){rel=""nofollow""}.
::


# HTML Blaze

::component-viewer
---
component-files:
  - HtmlBlaze.vue
component-id: html-blaze
config: HtmlBlazeConfig
demo-file: HtmlBlazeDemo.vue
---
#api
## API

| Prop         | Type      | Défaut  | Description                                             |
| ------------ | --------- | ------- | ------------------------------------------------------- |
| `strength`   | `number`  | `0.03`  | Intensité du déplacement thermique.                     |
| `scale`      | `number`  | `6`     | Échelle du champ de bruit des flammes.                  |
| `speed`      | `number`  | `1`     | Vitesse d'animation du feu.                             |
| `frameRate`  | `number`  | `60`    | Fréquence maximale de rendu.                            |
| `pixelRatio` | `number`  | `1`     | Échelle de rendu, limitée entre `0.25` et `2`.          |
| `paused`     | `boolean` | `false` | Met la boucle de rendu en pause.                        |
| `autoPause`  | `boolean` | `true`  | Met en pause hors écran ou lorsque la page est masquée. |
| `class`      | `string`  | —       | Classes supplémentaires fusionnées avec la surface.     |

### Slots

| Slot      | Description                             |
| --------- | --------------------------------------- |
| `default` | Contenu HTML rendu à travers cet effet. |

#credits
- Utilise l'implémentation Simplex Noise sous licence MIT d'[Ashima Arts](https://github.com/ashima/webgl-noise){rel=""nofollow""}.
::


# HTML Chromatic

::component-viewer
---
component-files:
  - HtmlChromatic.vue
component-id: html-chromatic
config: HtmlChromaticConfig
demo-file: HtmlChromaticDemo.vue
---
#api
## API

| Prop           | Type      | Défaut  | Description                                             |
| -------------- | --------- | ------- | ------------------------------------------------------- |
| `strength`     | `number`  | `0.03`  | Séparation maximale des canaux rouge et bleu.           |
| `mouseDamping` | `number`  | `0.9`   | Lissage appliqué au déplacement du pointeur.            |
| `frameRate`    | `number`  | `60`    | Fréquence maximale de rendu.                            |
| `pixelRatio`   | `number`  | `1`     | Échelle de rendu, limitée entre `0.25` et `2`.          |
| `paused`       | `boolean` | `false` | Met la boucle de rendu en pause.                        |
| `autoPause`    | `boolean` | `true`  | Met en pause hors écran ou lorsque la page est masquée. |
| `class`        | `string`  | —       | Classes supplémentaires fusionnées avec la surface.     |

### Slots

| Slot      | Description                             |
| --------- | --------------------------------------- |
| `default` | Contenu HTML rendu à travers cet effet. |
::


# HTML Cloth

::component-viewer
---
component-files:
  - HtmlCloth.vue
component-id: html-cloth
config: HtmlClothConfig
demo-file: HtmlClothDemo.vue
---
#api
## API

| Prop         | Type      | Défaut  | Description                                             |
| ------------ | --------- | ------- | ------------------------------------------------------- |
| `strength`   | `number`  | `0.03`  | Intensité du déplacement vectoriel.                     |
| `scale`      | `number`  | `6`     | Échelle du champ de tissu.                              |
| `speed`      | `number`  | `1`     | Vitesse d'animation du champ.                           |
| `frameRate`  | `number`  | `60`    | Fréquence maximale de rendu.                            |
| `pixelRatio` | `number`  | `1`     | Échelle de rendu, limitée entre `0.25` et `2`.          |
| `paused`     | `boolean` | `false` | Met la boucle de rendu en pause.                        |
| `autoPause`  | `boolean` | `true`  | Met en pause hors écran ou lorsque la page est masquée. |
| `class`      | `string`  | —       | Classes supplémentaires fusionnées avec la surface.     |

### Slots

| Slot      | Description                             |
| --------- | --------------------------------------- |
| `default` | Contenu HTML rendu à travers cet effet. |

#credits
- Champ vectoriel basé sur le travail de [MartinRGB](https://www.shadertoy.com/view/DttSRB){rel=""nofollow""}.
::


# HTML Drag

::component-viewer
---
component-files:
  - HtmlDrag.vue
component-id: html-drag
config: HtmlDragConfig
demo-file: HtmlDragDemo.vue
---
Faites défiler la surface pour courber son plan WebGL segmenté. Activez 

`mouseEnabled`

 pour ajouter la déformation au glisser ; laissez-le désactivé pour conserver la sélection du HTML.

#api
## API

| Prop           | Type      | Défaut  | Description                                              |
| -------------- | --------- | ------- | -------------------------------------------------------- |
| `strength`     | `number`  | `1.25`  | Intensité de la courbure verticale.                      |
| `mouseDamping` | `number`  | `0.9`   | Lissage appliqué au déplacement du pointeur.             |
| `mouseEnabled` | `boolean` | `false` | Active la déformation au glisser et bloque la sélection. |
| `frameRate`    | `number`  | `60`    | Fréquence maximale de rendu.                             |
| `pixelRatio`   | `number`  | `1`     | Échelle de rendu, limitée entre `0.25` et `2`.           |
| `paused`       | `boolean` | `false` | Met la boucle de rendu en pause.                         |
| `autoPause`    | `boolean` | `true`  | Met en pause hors écran ou lorsque la page est masquée.  |
| `class`        | `string`  | —       | Classes supplémentaires fusionnées avec la surface.      |

### Slots

| Slot      | Description                             |
| --------- | --------------------------------------- |
| `default` | Contenu HTML rendu à travers cet effet. |
::


# HTML in Canvas

::component-viewer
---
component-files:
  - HtmlInCanvas.vue
  - HtmlInCanvasRenderer.ts
  - captureElement.ts
  - index.ts
component-id: html-in-canvas
config: HtmlInCanvasConfig
demo-file: HtmlInCanvasDemo.vue
---
HTML in Canvas est une API expérimentale. Lorsqu'elle n'est pas disponible, le composant capture un instantané stylé du DOM et le traite avec le même shader WebGL. Le DOM original reste disponible pour les interactions et l'accessibilité.

Le fragment shader doit définir `mainImage(out vec4 fragColor, in vec2 fragCoord)`. Le HTML capturé est accessible via `iChannel0`.

Utilisez `HtmlLiquid`, `HtmlChromatic`, `HtmlAscii`, `HtmlCloth`, `HtmlBlaze` ou `HtmlDrag` pour une API d'effet ciblée et typée. Chaque composant confie le rendu et le mode de secours à ce moteur partagé.

Utilisez `vertexShaderCode` lorsque l'effet nécessite aussi une logique au niveau du vertex shader. Il doit définir `main()` sans directive `#version`. La surface segmentée expose les attributs intégrés `vec2 position` et `vec2 textureCoord`, et les mêmes uniforms sont disponibles dans les deux étapes.

#api
## API

| Prop               | Type             | Défaut  | Description                                                    |
| ------------------ | ---------------- | ------- | -------------------------------------------------------------- |
| `shaderCode`       | `string`         | —       | Code du fragment shader contenant une fonction `mainImage`.    |
| `vertexShaderCode` | `string`         | —       | Code optionnel du vertex shader contenant une fonction `main`. |
| `uniforms`         | `ShaderUniforms` | `{}`    | Uniforms numériques, booléens, vectoriels ou matriciels.       |
| `frameRate`        | `number`         | `60`    | Fréquence de rendu maximale.                                   |
| `pixelRatio`       | `number`         | `1`     | Échelle de rendu, limitée entre `0.25` et `2`.                 |
| `speed`            | `number`         | `1`     | Multiplicateur appliqué à `iTime`.                             |
| `mouseDamping`     | `number`         | `0.85`  | Lissage appliqué au déplacement du pointeur.                   |
| `paused`           | `boolean`        | `false` | Met la boucle de rendu en pause.                               |
| `autoPause`        | `boolean`        | `true`  | Met en pause hors écran ou lorsque le document est masqué.     |
| `interactive`      | `boolean`        | `true`  | Suit le pointeur pour alimenter `iMouse`.                      |
| `class`            | `string`         | —       | Classes supplémentaires fusionnées sur l'élément racine.       |

### Entrées du shader

`iResolution`, `iTime`, `iTimeDelta`, `iFrameRate`, `iFrame`, `iMouse`, `iDate`, `iHasContent`, `iChannel0` et `iChannelResolution` suivent les conventions ShaderToy. `iPointerVelocity`, `iPointerEnergy` et `iPointerAge` fournissent une impulsion amortie pour les effets qui doivent se stabiliser après le mouvement. `iPointerInside` évolue entre `0` et `1` lorsque le pointeur quitte ou entre dans la surface. `iScrollVelocity` fournit une vitesse verticale amortie pour déformer les sommets au défilement. `iHasContent` vaut `1` lorsque la texture HTML est disponible.

### Événements

| Événement | Charge utile | Description                                        |
| --------- | ------------ | -------------------------------------------------- |
| `ready`   | —            | Émis après le premier rendu de la texture HTML.    |
| `error`   | `string`     | Émis en cas d'échec de compilation ou de rendu.    |
| `support` | `boolean`    | Indique la disponibilité native de HTML-in-Canvas. |

### Slots

| Slot      | Description                                   |
| --------- | --------------------------------------------- |
| `default` | Contenu HTML capturé comme texture du shader. |

#credits
- Construit à partir de la [proposition WICG HTML-in-Canvas](https://github.com/WICG/html-in-canvas){rel=""nofollow""}.
::


# HTML Liquid

::component-viewer
---
component-files:
  - HtmlLiquid.vue
component-id: html-liquid
config: HtmlLiquidConfig
demo-file: HtmlLiquidDemo.vue
---
#api
## API

| Prop           | Type      | Défaut  | Description                                                  |
| -------------- | --------- | ------- | ------------------------------------------------------------ |
| `strength`     | `number`  | `0.03`  | Intensité du déplacement de la texture.                      |
| `frequency`    | `number`  | `18`    | Densité de la surface fluide et des ondulations du pointeur. |
| `speed`        | `number`  | `3`     | Vitesse du champ liquide.                                    |
| `mouseDamping` | `number`  | `0.9`   | Lissage appliqué au déplacement du pointeur.                 |
| `frameRate`    | `number`  | `60`    | Fréquence maximale de rendu.                                 |
| `pixelRatio`   | `number`  | `1`     | Échelle de rendu, limitée entre `0.25` et `2`.               |
| `paused`       | `boolean` | `false` | Met la boucle de rendu en pause.                             |
| `autoPause`    | `boolean` | `true`  | Met en pause hors écran ou lorsque la page est masquée.      |
| `class`        | `string`  | —       | Classes supplémentaires fusionnées avec la surface.          |

### Slots

| Slot      | Description                             |
| --------- | --------------------------------------- |
| `default` | Contenu HTML rendu à travers cet effet. |
::


# Tous les composants

:components-list


# Curseur d'équilibre

::component-viewer
---
component-files:
  - BalanceSlider.vue
component-id: balance-slider
config: BalanceSliderConfig
demo-file: BalanceSliderDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                                            |
| ---------------- | -------- | ----------------- | ---------------------------------------------------------------------- |
| `initialValue`   | `number` | `50`              | Position initiale du curseur (0-100).                                  |
| `leftColor`      | `string` | `"#e68a00"`       | Couleur de fond du côté gauche du curseur.                             |
| `rightColor`     | `string` | `"#ffffff"`       | Couleur de fond du côté droit du curseur.                              |
| `minShiftLimit`  | `number` | `40`              | Limite minimale à partir de laquelle l'animation de décalage s'active. |
| `maxShiftLimit`  | `number` | `68`              | Limite maximale au-delà de laquelle l'animation se désactive.          |
| `leftContent`    | `string` | `"LEFT"`          | Texte affiché dans l'info-bulle pour le côté gauche.                   |
| `rightContent`   | `string` | `"RIGHT"`         | Texte affiché dans l'info-bulle pour le côté droit.                    |
| `indicatorColor` | `string` | `"#FFFFFF"`       | Couleur de l'indicateur central du curseur.                            |

#credits
- Inspiré et porté depuis le code partagé dans [la version CSS only du Balance Slider par Jhey](https://x.com/jh3yy/status/1748809599598399792?s=46){rel=""nofollow""}
- Concept original par [Malay Vasa](https://x.com/MalayVasa/status/1748726374079381930){rel=""nofollow""}.
::


# Sélecteur de couleur

::component-viewer
---
component-files:
  - ColorPicker.vue
  - ObjectColorInput.vue
  - ContrastRatio.vue
  - index.ts
component-id: color-picker
config: ColorPickerConfig
demo-file: ColorPickerDemo.vue
dependencies: "@uiw/color-convert"
---
#api
## API

### Props de ColorPicker

| Nom de propriété      | Type                                         | Valeur par défaut | Description                                                           |
| --------------------- | -------------------------------------------- | ----------------- | --------------------------------------------------------------------- |
| `value`               | `string | HsvaColor | HslaColor | RgbaColor` | `undefined`       | Valeur de couleur actuelle dans n'importe quel format pris en charge. |
| `type`                | `'hsl' | 'hsla' | 'rgb' | 'rgba' | 'hex'`    | `'hsl'`           | Format de couleur par défaut affiché dans les champs.                 |
| `swatches`            | `HexColor[]`                                 | `[]`              | Tableau d'échantillons de couleur prédéfinis.                         |
| `hideContrastRatio`   | `boolean`                                    | `false`           | Masque la section du rapport de contraste (accessibilité).            |
| `hideDefaultSwatches` | `boolean`                                    | `false`           | Masque les échantillons de couleur par défaut.                        |
| `class`               | `string`                                     | `""`              | Classes CSS supplémentaires pour le contenu du popover.               |
| `open`                | `boolean`                                    | `false`           | Contrôle l'état ouvert/fermé du sélecteur de couleurs.                |

### Événements de ColorPicker

| Nom de l'événement | Type                                | Description                                        |
| ------------------ | ----------------------------------- | -------------------------------------------------- |
| `value-change`     | `(value: ColorPickerValue) => void` | Émis lorsque la couleur sélectionnée change.       |
| `update:open`      | `(value: boolean) => void`          | Émis lorsque l'état d'ouverture du popover change. |

### Type ColorPickerValue

```typescript
interface ColorPickerValue {
  hex: string; // Chaîne hexadécimale de couleur (ex. "#ff0000")
  hsl: HslaColor; // Objet couleur HSL avec propriétés h, s, l, a
  hsla: HslaColor; // Objet couleur HSLA avec propriétés h, s, l, a
  rgb: RgbaColor; // Objet couleur RGB avec propriétés r, g, b, a
  rgba: RgbaColor; // Objet couleur RGBA avec propriétés r, g, b, a
}
```

#credits
- Merci à [kalix127](https://github.com/kalix127){rel=""nofollow""} pour le portage de ce composant.
- Inspiré par [@uplusion23](https://21st.dev/uplusion23/color-picker/color-picker-with-swatches-and-onchange){rel=""nofollow""}.
::


# Téléversement de fichier

::component-viewer
---
component-files:
  - FileUpload.vue
  - FileUploadGrid.vue
component-id: file-upload
config: FileUploadConfig
demo-file: FileUploadDemo.vue
---
#api
## API

### `FileUpload`

Le composant `FileUpload` sert de conteneur pour l'effet d'upload. Il gère les événements souris pour créer une perspective 3D.

#### Props

| Nom de propriété | Type   | Valeur par défaut | Description                                                |
| ---------------- | ------ | ----------------- | ---------------------------------------------------------- |
| `class`          | String | -                 | Classes supplémentaires pour styliser l'élément conteneur. |

#### Événements émis

| Nom de l'événement | Type                      | Description                                                                 |
| ------------------ | ------------------------- | --------------------------------------------------------------------------- |
| `onChange`         | `(files: File[]) => void` | Fonction de rappel déclenchée lorsque des fichiers sont ajoutés/téléversés. |

### `FileUploadGrid`

Le composant `FileUploadGrid` fournit le motif de grille d'arrière-plan pour la zone d'upload. Il est destiné à être utilisé dans un composant `FileUpload` pour créer l'effet visuel derrière l'interface de téléversement.

#### Props

| Nom de propriété | Type   | Valeur par défaut | Description                                         |
| ---------------- | ------ | ----------------- | --------------------------------------------------- |
| `class`          | String | -                 | Classes supplémentaires pour un style personnalisé. |

#credits
- Merci à [kalix127](https://github.com/kalix127){rel=""nofollow""} pour le portage de ce composant.
- Inspiré par [AcernityUI](https://ui.aceternity.com/components/file-upload){rel=""nofollow""}.
::


# Recherche Halo

::component-viewer
---
component-files:
  - HaloSearch.vue
component-id: halo-search
config: HaloSearchConfig
demo-file: HaloSearchDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                           |
| ---------------- | -------- | ----------------- | ----------------------------------------------------- |
| `class`          | `string` | `""`              | Classes CSS supplémentaires pour le conteneur racine. |

#credits
- Design inspiré des concepts d'UI futuristes et des effets de lumière ambiante populaires dans le web moderne.
- Inspiré du défi UiVerse Search input.
::


# Champ de saisie

::component-viewer
---
component-files:
  - IInput.vue
component-id: input
config: InputConfig
demo-file: InputDemo.vue
---
#api
## API

| Nom de propriété | Type              | Valeur par défaut | Description                                             |
| ---------------- | ----------------- | ----------------- | ------------------------------------------------------- |
| `defaultValue`   | `string | number` | `""`              | Valeur par défaut du champ de saisie.                   |
| `class`          | `string`          | `""`              | Classes CSS supplémentaires pour un style personnalisé. |
| `containerClass` | `string`          | `""`              | Classes CSS supplémentaires pour styliser le conteneur. |

#credits
- Construit sur la base du composant Input de ShadCN Vue, avec des fonctionnalités étendues pour les besoins UI/UX modernes.
- Porté depuis le [Signup Form Input Component d'Aceternity UI](https://ui.aceternity.com/components/signup-form){rel=""nofollow""}
::


# Placeholders et saisie qui disparaît

::component-viewer
---
component-files:
  - VanishingInput.vue
component-id: vanishing-input
config: VanishingInputConfig
demo-file: VanishingInputDemo.vue
---
#api
## API

| Nom de propriété | Type            | Valeur par défaut                                     | Description                                                                |
| ---------------- | --------------- | ----------------------------------------------------- | -------------------------------------------------------------------------- |
| `placeholders`   | `Array<string>` | `["Placeholder 1", "Placeholder 2", "Placeholder 3"]` | Tableau de textes de placeholder qui défilent comme invites dans le champ. |

Ce composant écoute les événements suivants émis par le composant `VanishingInput` :

| Nom de l'événement | Paramètres | Description                                  |
| ------------------ | ---------- | -------------------------------------------- |
| `change`           | `Event`    | Déclenché lorsque la valeur du champ change. |
| `submit`           | `string`   | Déclenché lorsque le champ est soumis.       |

#credits
- Merci à [M Atif](https://github.com/atif0075){rel=""nofollow""} pour le portage de ce composant.
- Porté depuis [Placeholders And Vanish Input d'Aceternity UI](https://ui.aceternity.com/components/placeholders-and-vanish-input){rel=""nofollow""}.
::


# Grille animée

::component-viewer
---
component-files:
  - AnimateGrid.vue
component-id: animate-grid
config: AnimateGridConfig
demo-file: AnimateGridDemo.vue
---
#instructions
#### Ajouter un fichier SVG

Ajoutez au moins un fichier SVG dans le même dossier que votre composant et mettez à jour l'import dans le composant pour l'utiliser.

#api
## API

| Nom de propriété     | Type     | Valeur par défaut   | Description                                                  |
| -------------------- | -------- | ------------------- | ------------------------------------------------------------ |
| `textGlowStartColor` | `string` | `"#38ef7d80"`       | Couleur de départ de l'ombre portée.                         |
| `textGlowEndColor`   | `string` | `"#38ef7d"`         | Couleur de fin de l'ombre portée.                            |
| `perspective`        | `number` | `600`               | Perspective à appliquer à la propriété CSS transform.        |
| `rotateX`            | `number` | `-1`                | Valeur de rotation X pour la propriété transform.            |
| `rotateY`            | `number` | `-15`               | Valeur de rotation Y pour la propriété transform.            |
| `cards`              | `[]`     | `"[{logo: 'src'}]"` | Cartes à afficher dans la grille.                            |
| `class`              | `string` | `""`                | Classes Tailwind supplémentaires pour un style personnalisé. |

#credits
- Merci à [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} pour ce composant.
::


# Barre de progression circulaire animée

::component-viewer
---
component-files:
  - AnimatedCircularProgressBar.vue
component-id: animated-circular-progressbar
config: AnimatedCircularProgressBarConfig
demo-file: AnimatedCircularProgressBarDemo.vue
---
#api
## API

| Nom de propriété      | Type      | Valeur par défaut    | Description                                |
| --------------------- | --------- | -------------------- | ------------------------------------------ |
| `class`               | `string`  | `-`                  | Classe appliquée au composant.             |
| `max`                 | `number`  | `100`                | Valeur maximale de la jauge.               |
| `min`                 | `number`  | `0`                  | Valeur minimale de la jauge.               |
| `value`               | `number`  | `0`                  | Valeur actuelle de la jauge.               |
| `gaugePrimaryColor`   | `string`  | `rgb(79 70 229)`     | Couleur principale de la jauge.            |
| `gaugeSecondaryColor` | `string`  | `rgba(0, 0, 0, 0.1)` | Couleur secondaire de la jauge.            |
| `circleStrokeWidth`   | `number`  | `10`                 | Largeur du cercle de progression.          |
| `showPercentage`      | `boolean` | `true`               | Affiche la valeur à l'intérieur du cercle. |
| `duration`            | `number`  | `1`                  | Durée de l'animation (en secondes).        |

#credits
- Merci à [Magic UI](https://magicui.design/docs/components/animated-circular-progress-bar){rel=""nofollow""}.
- Merci à [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} pour le portage de ce composant.
::


# Liste animée

::component-viewer
---
component-files:
  - AnimatedList.vue
  - Notification.vue
component-id: animated-list
config: AnimatedListConfig
demo-file: AnimatedListDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                                       |
| ---------------- | -------- | ----------------- | ----------------------------------------------------------------- |
| `delay`          | `number` | `1`               | Délai en millisecondes avant d'ajouter chaque élément à la liste. |

#credits
- Inspiré par [Magic UI](https://magicui.design/docs/components/animated-list){rel=""nofollow""}.
::


# Animated Modal

::component-viewer
---
component-files:
  - AnimatedModal.vue
  - AnimatedModalBody.vue
  - AnimatedModalContent.vue
  - AnimatedModalFooter.vue
  - AnimatedModalTrigger.vue
  - AnimatedModalContext.ts
  - useAnimatedModal.ts
  - index.ts
component-id: animated-modal
config: AnimatedModalConfig
demo-file: AnimatedModalDemo.vue
dependencies: motion-v @vueuse/core
---
#api
## API

### `<AnimatedModal />`

#### Props

| Nom de prop   | Type      | Défaut  | Description                          |
| ------------- | --------- | ------- | ------------------------------------ |
| `open`        | `boolean` | `-`     | État contrôlé d’ouverture.           |
| `defaultOpen` | `boolean` | `false` | État initial en mode non contrôlé.   |
| `closeOnEsc`  | `boolean` | `true`  | Ferme la modale avec la touche `Esc` |

#### Événements

| Nom de l'événement | Charge utile | Description                           |
| ------------------ | ------------ | ------------------------------------- |
| `update:open`      | `boolean`    | Émis lorsque l'état change.           |
| `open`             | -            | Émis quand `openModal()` est appelé.  |
| `close`            | -            | Émis quand `closeModal()` est appelé. |

#### Slots

| Nom du slot | Props du slot                               |
| ----------- | ------------------------------------------- |
| `default`   | `open`, `openModal`, `closeModal`, `toggle` |

#### Composable

- `useAnimatedModal()` — accéder à l'état/méthodes depuis n'importe quel enfant (doit être utilisé dans `<AnimatedModal />`).

### `<AnimatedModalBody />`

#### Props

| Nom de prop      | Type                   | Défaut   | Description                               |
| ---------------- | ---------------------- | -------- | ----------------------------------------- |
| `class`          | `string`               | `""`     | Classes supplémentaires du panneau.       |
| `overlayClass`   | `string`               | `""`     | Classes supplémentaires de l'overlay.     |
| `contentClass`   | `string`               | `""`     | Classes supplémentaires du contenu.       |
| `showClose`      | `boolean`              | `true`   | Affiche le bouton de fermeture.           |
| `closeOnOutside` | `boolean`              | `true`   | Ferme au clic en dehors de la modale.     |
| `lockScroll`     | `boolean`              | `true`   | Bloque le scroll de la page quand ouvert. |
| `zIndex`         | `number`               | `10000`  | Z-index de la couche modale.              |
| `teleportTo`     | `string | HTMLElement` | `"body"` | Cible Teleport de la modale.              |

#credits
- Porté depuis [Animated Modal d'Aceternity UI](https://ui.aceternity.com/components/animated-modal){rel=""nofollow""}.
- Animations avec [motion-v](https://motion.dev/){rel=""nofollow""}.
::


# Animated Tabs

::component-viewer
---
component-files:
  - AnimatedTabs.vue
  - AnimatedTabsFadeInDiv.vue
  - types.ts
  - index.ts
component-id: animated-tabs
config: AnimatedTabsConfig
demo-file: AnimatedTabsDemo.vue
dependencies: motion-v
---
#api
## API

### `<AnimatedTabs />`

Astuce : donnez au conteneur une hauteur fixe (par ex. `h-[20rem] md:h-[40rem]`), car le contenu est empilé avec un positionnement `absolute`.

#### Props

| Nom                  | Type            | Défaut | Description                                                      |
| -------------------- | --------------- | ------ | ---------------------------------------------------------------- |
| `tabs`               | `AnimatedTab[]` | `-`    | Liste des métadonnées des onglets.                               |
| `modelValue`         | `string`        | `-`    | Valeur active de l'onglet en mode contrôlé.                      |
| `containerClassName` | `string`        | `""`   | Classes supplémentaires pour le conteneur de la liste d'onglets. |
| `tabClassName`       | `string`        | `""`   | Classes supplémentaires pour chaque bouton d'onglet.             |
| `activeTabClassName` | `string`        | `""`   | Classes supplémentaires pour le fond de l'indicateur actif.      |
| `contentClassName`   | `string`        | `""`   | Classes supplémentaires pour chaque carte de contenu empilée.    |

#### Events

| Nom                 | Payload  | Description                                         |
| ------------------- | -------- | --------------------------------------------------- |
| `update:modelValue` | `string` | Émis lorsque l'onglet actif change (mode contrôlé). |

#### Slots

| Nom       | Props du slot               | Description                                           |
| --------- | --------------------------- | ----------------------------------------------------- |
| `content` | `tab`, `active`, `hovering` | Permet de rendre le contenu de l'onglet (recommandé). |

#### Types

##### `AnimatedTab`

| Champ            | Type                  | Requis | Description                                                                     |
| ---------------- | --------------------- | ------ | ------------------------------------------------------------------------------- |
| `title`          | `string`              | oui    | Libellé de l'onglet (utilisé par l'interface par défaut).                       |
| `value`          | `string`              | oui    | Identifiant unique de l'onglet.                                                 |
| `panelClassName` | `string`              | non    | Classes d'arrière-plan du panneau (utilisées par la démo ou les consommateurs). |
| `content`        | `Component`           | non    | Composant de contenu de secours si le slot `#content` n'est pas fourni.         |
| `contentProps`   | `Record<string, any>` | non    | Props passées au composant `content`.                                           |

#credits
- Porté depuis [Aceternity UI Tabs](https://ui.aceternity.com/components/tabs){rel=""nofollow""}.
- Animations propulsées par [motion-v](https://motion.dev/docs/vue){rel=""nofollow""}.
::


# Infobulle animée

::component-viewer
---
component-files:
  - AnimatedTooltip.vue
component-id: animated-tooltip
config: AnimatedTooltipConfig
demo-file: AnimatedTooltipDemo.vue
---
#api
## API

| Nom de propriété | Type                                                                    | Valeur par défaut | Description                                                                                      |
| ---------------- | ----------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------ |
| `items`          | `Array<{id: number, name: string, designation: string, image: string}>` | `[]`              | Tableau d'objets représentant chaque élément avec les propriétés id, name, designation et image. |

#credits
- Merci à [M Atif](https://github.com/atif0075){rel=""nofollow""} pour ce composant.
- Inspiré par [Animated Tooltip d'Aceternity UI](https://ui.aceternity.com/components/animated-tooltip){rel=""nofollow""}.
::


# Grille bento

::component-viewer
---
component-files:
  - BentoGrid.vue
  - BentoGridCard.vue
  - BentoGridItem.vue
component-id: bento-grid
config: BentoGridConfig
demo-file: BentoGridDemo.vue
---
#api
## API

#### `BentoGridItem`

| Nom du slot   | Description                          |
| ------------- | ------------------------------------ |
| `title`       | Composant affiché comme titre.       |
| `description` | Composant affiché comme description. |
| `icon`        | Composant affiché comme icône.       |
| `header`      | Composant affiché comme en-tête.     |

#### `BentoGridCard`

| Nom du slot  | Description                        |
| ------------ | ---------------------------------- |
| `background` | Composant affiché en arrière-plan. |

| Nom de la prop | Type      | Description                        |
| -------------- | --------- | ---------------------------------- |
| `name`         | `string`  | Nom ou titre affiché sur la carte. |
| `icon`         | `?string` | Icône à afficher sur la carte.     |
| `description`  | `string`  | Description affichée sur la carte. |
| `href`         | `string`  | Lien URL pour l'appel à l'action.  |
| `cta`          | `string`  | Texte de l'appel à l'action.       |

#credits
- Merci à [Aceternity UI](https://ui.aceternity.com/components/bento-grid){rel=""nofollow""} et [Magic UI](https://magicui.design/docs/components/bento-grid){rel=""nofollow""} pour ce superbe composant.
::


# Livre

::component-viewer
---
component-files:
  - Book.vue
  - BookHeader.vue
  - BookTitle.vue
  - BookDescription.vue
  - index.ts
component-id: book
config: BookConfig
demo-file: BookDemo.vue
---
#api
## API

#### `Book`

| Nom de propriété | Type    | Valeur par défaut | Description                                         |
| ---------------- | ------- | ----------------- | --------------------------------------------------- |
| `class`          | String  | -                 | Classes supplémentaires pour styliser le composant. |
| `duration`       | Number  | 1000              | Durée de l'animation en millisecondes.              |
| `color`          | String  | "zinc"            | Palette de couleur pour le dégradé du livre.        |
| `isStatic`       | Boolean | false             | Désactive les animations au survol si `true`.       |
| `size`           | String  | "md"              | Variante de taille du livre.                        |
| `radius`         | String  | "md"              | Variante de rayon de bordure du livre.              |
| `shadowSize`     | String  | "lg"              | Variante de taille d'ombre du livre.                |

#### `BookHeader`

| Nom de propriété | Type   | Valeur par défaut | Description                                         |
| ---------------- | ------ | ----------------- | --------------------------------------------------- |
| `class`          | String | -                 | Classes supplémentaires pour un style personnalisé. |

#### `BookTitle`

| Nom de propriété | Type   | Valeur par défaut | Description                                         |
| ---------------- | ------ | ----------------- | --------------------------------------------------- |
| `class`          | String | -                 | Classes supplémentaires pour un style personnalisé. |

#### `BookDescription`

| Nom de propriété | Type   | Valeur par défaut | Description                                         |
| ---------------- | ------ | ----------------- | --------------------------------------------------- |
| `class`          | String | -                 | Classes supplémentaires pour un style personnalisé. |

#credits
- Merci à [x/UI](https://ui.3x.gl/docs/book){rel=""nofollow""} pour l'inspiration.
- Merci à [kalix127](https://github.com/kalix127){rel=""nofollow""} pour le portage de ce composant.
::


# Galerie circulaire

::component-viewer
---
component-files:
  - CircularGallery.vue
  - index.ts
component-id: circular-gallery
config: CircularGalleryConfig
demo-file: CircularGalleryDemo.vue
---
#api
## API

| Nom de prop    | Type                  | Valeur par défaut | Description                                             |
| -------------- | --------------------- | ----------------- | ------------------------------------------------------- |
| `radius`       | `number`              | `100`             | Distance en pixels entre le centre et chaque élément.   |
| `duration`     | `number`              | `10`              | Durée en secondes d’une rotation complète.              |
| `easing`       | `string`              | `linear`          | Fonction d’easing CSS utilisée pour la rotation.        |
| `direction`    | `normal` \| `reverse` | `normal`          | Sens de rotation.                                       |
| `class`        | `string`              | —                 | Classes supplémentaires pour la racine.                 |
| `pauseOnHover` | `boolean`             | `false`           | Met la rotation en pause lorsqu’un élément est survolé. |

## Utilisation

Passez les éléments à disposer autour du cercle via le slot par défaut :

```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
- Porté depuis [Fancy Components Circling Elements](https://fancycomponents.dev/docs/components/blocks/circling-elements){rel=""nofollow""}.
::


# Comparaison

::component-viewer
---
component-files:
  - Compare.vue
  - StarField.vue
component-id: compare
config: CompareConfig
demo-file: CompareDemo.vue
---
#api
## API

### Props

| Nom de propriété          | Type               | Valeur par défaut | Description                                       |
| ------------------------- | ------------------ | ----------------- | ------------------------------------------------- |
| `firstImage`              | `string`           | `""`              | URL de la première image.                         |
| `secondImage`             | `string`           | `""`              | URL de la seconde image.                          |
| `firstImageAlt`           | `string`           | `"First image"`   | Texte alternatif pour la première image.          |
| `secondImageAlt`          | `string`           | `"Second image"`  | Texte alternatif pour la seconde image.           |
| `class`                   | `string`           | `""`              | Classes supplémentaires pour le composant.        |
| `firstContentClass`       | `string`           | `""`              | Classes appliquées au wrapper du premier contenu. |
| `secondContentClass`      | `string`           | `""`              | Classes appliquées au wrapper du second contenu.  |
| `initialSliderPercentage` | `number`           | `50`              | Position initiale du curseur (0-100).             |
| `slideMode`               | `"hover" | "drag"` | `"hover"`         | Mode d'interaction du curseur.                    |
| `showHandlebar`           | `boolean`          | `true`            | Afficher/masquer la poignée.                      |
| `autoplay`                | `boolean`          | `false`           | Active/désactive la lecture automatique.          |
| `autoplayDuration`        | `number`           | `5000`            | Durée du cycle automatique en ms.                 |

### Événements

| Nom de l'événement  | Charge utile | Description                                         |
| ------------------- | ------------ | --------------------------------------------------- |
| `update:percentage` | `number`     | Émis lorsque la position du curseur change (0-100). |
| `drag:start`        | -            | Émis au début du glisser.                           |
| `drag:end`          | -            | Émis à la fin du glisser.                           |
| `hover:enter`       | -            | Émis quand la souris entre dans le composant.       |
| `hover:leave`       | -            | Émis quand la souris quitte le composant.           |

### Slots

| Nom du slot      | Contenu par défaut                                   | Description                                                                                                                    |
| ---------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `first-content`  | Élément `<img>` si la prop `firstImage` est fournie  | Contenu affiché sur le côté gauche/premier. Dispose de toute la largeur/hauteur du composant.                                  |
| `second-content` | Élément `<img>` si la prop `secondImage` est fournie | Contenu affiché sur le côté droit/deuxième. Dispose de toute la largeur/hauteur du composant.                                  |
| `handle`         | Poignée de curseur par défaut avec icône de points   | Poignée personnalisée du curseur. Positionnée automatiquement sur la ligne de séparation. Doit gérer le positionnement absolu. |

#credits
- Merci à [M Atif](https://github.com/atif0075){rel=""nofollow""} pour ce composant.
- Inspiré par [Compare d'Aceternity UI](https://ui.aceternity.com/components/compare){rel=""nofollow""}.
::


# Défilement conteneur

::component-viewer
---
component-files:
  - ContainerScroll.vue
  - ContainerScrollTitle.vue
  - ContainerScrollCard.vue
component-id: container-scroll
config: ContainerScrollConfig
demo-file: ContainerScrollDemo.vue
---
#api
## API

### `ContainerScroll`

Le composant `ContainerScroll` crée un effet de défilement 3D. À mesure que l'utilisateur fait défiler, le contenu interne est transformé par des effets d'échelle, de rotation et de translation.

| Nom de propriété | Type   | Valeur par défaut | Description                                                              |
| ---------------- | ------ | ----------------- | ------------------------------------------------------------------------ |
| `rotate`         | Number | `0`               | Contrôle la rotation du contenu interne selon le défilement.             |
| `scale`          | Number | `1`               | Contrôle la mise à l'échelle appliquée au contenu pendant le défilement. |
| `translateY`     | Number | `0`               | Contrôle la translation verticale du titre pendant le défilement.        |

### `ContainerScrollTitle`

Le composant `ContainerScrollTitle` gère la transformation du titre au défilement en appliquant une translation verticale.

| Nom de propriété | Type   | Valeur par défaut | Description                                 |
| ---------------- | ------ | ----------------- | ------------------------------------------- |
| `translate`      | Number | `0`               | Contrôle la translation verticale du titre. |

### `ContainerScrollCard`

Le composant `ContainerScrollCard` applique des effets d'échelle et de rotation au contenu de la carte lorsque l'utilisateur fait défiler la page.

| Nom de propriété | Type   | Valeur par défaut | Description                                       |
| ---------------- | ------ | ----------------- | ------------------------------------------------- |
| `rotate`         | Number | `0`               | Contrôle l'effet de rotation de la carte.         |
| `scale`          | Number | `1`               | Contrôle l'effet de mise à l'échelle de la carte. |

## Variables CSS

Pour personnaliser les animations de défilement et la réactivité, vous pouvez définir les variables CSS suivantes :

- **`--scale-start`** : Valeur d'échelle initiale pour la carte.
- **`--scale-end`** : Valeur d'échelle finale au fil du défilement.
- **`--rotate-start`** : Valeur de rotation initiale de la carte.
- **`--rotate-end`** : Valeur de rotation finale au fil du défilement.

#credits
- Inspiré par [Container Scroll Animation d'Aceternity UI](https://ui.aceternity.com/components/container-scroll-animation){rel=""nofollow""}.
::


# Dock

::component-viewer
---
component-files:
  - Dock.vue
  - DockIcon.vue
  - DockSeparator.vue
  - index.ts
  - types.ts
  - injectionKeys.ts
component-id: dock
config: DockConfig
demo-file: DockDemo.vue
---
#api
## API

### `Dock`

| Nom de propriété | Type     | Description                                                                  |
| ---------------- | -------- | ---------------------------------------------------------------------------- |
| `class`          | `string` | Classes supplémentaires à appliquer au conteneur du dock.                    |
| `magnification`  | `number` | Facteur d'agrandissement des icônes au survol (par défaut : 60).             |
| `distance`       | `number` | Distance depuis le centre de l'icône à laquelle l'agrandissement s'applique. |
| `direction`      | `string` | Alignement des icônes (`top`, `middle`, `bottom`) (par défaut : middle).     |
| `orientation`    | `string` | Orientation du dock (`vertical`, `horizontal`) (par défaut : horizontal).    |

| Nom du slot | Description                                             |
| ----------- | ------------------------------------------------------- |
| `default`   | Icônes du dock ou autres composants enfants à afficher. |

### `DockIcon`

| Nom du slot | Description                                                     |
| ----------- | --------------------------------------------------------------- |
| `default`   | Composant ou icône à afficher à l'intérieur de l'icône du dock. |

#credits
- Merci au dock macOS pour l'inspiration et son effet d'agrandissement iconique.
::


# Galerie extensible

::component-viewer
---
component-files:
  - ExpandableGallery.vue
component-id: expandable-gallery
config: ExpandableGalleryConfig
demo-file: ExpandableGalleryDemo.vue
---
#api
## API

| Nom de propriété | Type       | Valeur par défaut | Description                                        |
| ---------------- | ---------- | ----------------- | -------------------------------------------------- |
| `images`         | `string[]` | `[]`              | Tableau d'URL d'images à afficher dans la galerie. |

#credits
- Inspiré par le [Expandable Gallery Component de David Mráz](https://x.com/davidm_ml/status/1872319793124282653){rel=""nofollow""}
::


# Float

::component-viewer
---
component-files:
  - Float.vue
  - index.ts
component-id: float
config: FloatConfig
demo-file: FloatDemo.vue
---
#api
## API

| Nom de la prop  | Type                       | Valeur par défaut | Description                                             |
| --------------- | -------------------------- | ----------------- | ------------------------------------------------------- |
| `speed`         | `number`                   | `0.5`             | Progression du temps à chaque image.                    |
| `amplitude`     | `[number, number, number]` | `[10, 30, 30]`    | Amplitude de déplacement des axes X, Y et Z en pixels.  |
| `rotationRange` | `[number, number, number]` | `[15, 15, 7.5]`   | Plage de rotation des axes X, Y et Z en degrés.         |
| `timeOffset`    | `number`                   | `0`               | Décalage de phase pour désynchroniser plusieurs objets. |
| `class`         | `string`                   | —                 | Classes supplémentaires du wrapper animé.               |

Placez le contenu à animer dans le slot par défaut. Le composant conserve les transformations 3D et met à jour sa position à chaque image.

#credits
- Porté depuis [Fancy Components Float](https://fancycomponents.dev/docs/components/blocks/float){rel=""nofollow""}.
::


# Slider d'images

::component-viewer
---
component-files:
  - ImagesSlider.vue
component-id: images-slider
config: ImagesSliderConfig
demo-file: ImagesSliderDemo.vue
---
#api
## API

\| Nom de propriété | Type | Valeur par défaut | Description |
\| ------------------ | ------------- | ------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------- |
\| `images` | `string[]` | `[]` | Tableau d'URL d'images à afficher. |
\| `hideOverlay` | `boolean` | `false` | Ne pas créer de superposition pour le slider ; le slot ne sera pas rendu. |
\| `overlayClass` | `string` | `''` | Chaîne de classes à appliquer au conteneur de l'overlay. |
\| `imageClass` | `string` | `'bg-cover bg-center bg-no-repeat'` | Classes à appliquer à chaque image. |
\| `enterFromClass` | `string` | `'scale-0 origin-center'` | Classe appliquée à `enter-from-class` lors de la transition d'image. |
\| `enterActiveClass` | `string` | `'transition-transform duration-300 ease-in-out'` | Classe appliquée à `enter-active-class` lors de la transition. |
\| `leaveActiveClass` | `string` | `'transition-transform duration-300 ease-in-out'` | Classe appliquée à `leave-active-class` lors de la transition. |
\| `autoplay` | `boolean\\ | number` | `false` | Intervalle d'autoplay en ms, ou `false` pour désactiver. |
\| `direction` | `'vertical'\\ | 'horizontal'` | `'vertical'` | Axe sur lequel le slider doit fonctionner. |
\| `perspective` | `string` | `'1000px'` | Perspective appliquée au conteneur du slider. |
\| `modelValue` | `number` | `0` | Liaison bidirectionnelle pour l'index de l'image active. |

#credits
- Composant par [Craig Riley](https://github.com/craigrileyuk){rel=""nofollow""} pour le portage.
- Merci à [Aceternity UI](https://ui.aceternity.com/components/images-slider){rel=""nofollow""} pour l'inspiration.
::


# Loupe

::component-viewer
---
component-files:
  - Lens.vue
  - Rays.vue
  - Beams.vue
component-id: lens
config: LensConfig
demo-file: LensDemo.vue
---
#api
## API

| Nom de propriété | Type                       | Valeur par défaut    | Description                                                  |
| ---------------- | -------------------------- | -------------------- | ------------------------------------------------------------ |
| `zoomFactor`     | `number`                   | `1.5`                | Facteur d'agrandissement de la loupe.                        |
| `lensSize`       | `number`                   | `170`                | Diamètre de la loupe en pixels.                              |
| `position`       | `{ x: number, y: number }` | `{ x: 200, y: 150 }` | Position statique de la loupe (quand `isStatic` est `true`). |
| `isStatic`       | `boolean`                  | `false`              | Si `true`, la loupe reste fixe ; sinon, elle suit la souris. |
| `hovering`       | `boolean`                  | `"false"`            | Contrôle externe de l'état de survol.                        |

#credits
- Merci à [Aceternity UI](https://ui.aceternity.com/components/lens){rel=""nofollow""}.
- Merci à [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} pour le portage de ce composant.
::


# Aperçu de lien

::component-viewer
---
component-files:
  - LinkPreview.vue
component-id: link-preview
config: LinkPreviewConfig
demo-file: LinkPreviewDemo.vue
dependencies: qss
---
#api
## API

| Nom de propriété | Type      | Valeur par défaut | Description                                                                                   |
| ---------------- | --------- | ----------------- | --------------------------------------------------------------------------------------------- |
| `class`          | `string`  | `""`              | Classe personnalisée appliquée à l'élément principal.                                         |
| `linkClass`      | `string`  | `""`              | Classe personnalisée appliquée à l'élément lien.                                              |
| `width`          | `number`  | `200`             | Largeur de l'image d'aperçu.                                                                  |
| `height`         | `number`  | `125`             | Hauteur de l'image d'aperçu.                                                                  |
| `isStatic`       | `boolean` | `false`           | Définit si l'image d'aperçu est statique ou générée depuis l'URL (`true` pour mode statique). |
| `imageSrc`       | `string`  | `""`              | Source de l'image à afficher (requis si `isStatic` vaut `true`).                              |
| `url`            | `string`  | `""`              | URL du lien et pour générer l'aperçu (requis si `isStatic` vaut `false`).                     |

#credits
- Merci à [M Atif](https://github.com/atif0075){rel=""nofollow""} pour le portage de ce composant.
- Porté depuis [Link Preview d'Aceternity UI](https://ui.aceternity.com/components/link-preview){rel=""nofollow""}.
::


# Marquee

::component-viewer
---
component-files:
  - Marquee.vue
  - ReviewCard.vue
component-id: marquee
config: MarqueeConfig
demo-file: MarqueeDemo.vue
---
#api
## API

| Nom de propriété | Type      | Valeur par défaut | Description                                                          |
| ---------------- | --------- | ----------------- | -------------------------------------------------------------------- |
| `class`          | `string`  | `''`              | Classes CSS personnalisées pour le conteneur externe du marquee.     |
| `reverse`        | `boolean` | `false`           | Inverse le sens de défilement (droite vers gauche ou bas vers haut). |
| `pauseOnHover`   | `boolean` | `false`           | Met en pause l'animation au survol.                                  |
| `vertical`       | `boolean` | `false`           | Définit un défilement vertical au lieu d'horizontal.                 |
| `repeat`         | `number`  | `4`               | Nombre de répétitions du contenu dans le marquee.                    |

## Variables CSS

Vous pouvez personnaliser la vitesse et l'espacement des éléments via les variables suivantes :

- **`--duration`** : Contrôle la vitesse de l'animation du marquee.
- **`--gap`** : Définit l'espacement entre les éléments répétés.

#credits
- Inspiré par [Magic UI](https://magicui.design/docs/components/marquee){rel=""nofollow""}.
::


# Texte média

::component-viewer
---
component-files:
  - MediaText.vue
  - index.ts
component-id: media-text
config: MediaTextConfig
demo-file: MediaTextDemo.vue
---
#api
## API

| Nom de la prop        | Type                         | Valeur par défaut                  | Description                                        |
| --------------------- | ---------------------------- | ---------------------------------- | -------------------------------------------------- |
| `firstText`           | `string`                     | —                                  | Texte affiché avant le média.                      |
| `secondText`          | `string`                     | —                                  | Texte affiché après le média.                      |
| `mediaUrl`            | `string`                     | —                                  | URL de l’image ou de la vidéo.                     |
| `mediaType`           | `"image" | "video"`          | —                                  | Type de média à afficher.                          |
| `mediaContainerClass` | `string`                     | —                                  | Classes du conteneur média animé.                  |
| `fallbackUrl`         | `string`                     | —                                  | Affiche utilisée comme poster pour les vidéos.     |
| `as`                  | `string`                     | `p`                                | Élément HTML utilisé pour les fragments de texte.  |
| `autoPlay`            | `boolean`                    | `true`                             | Lance automatiquement la vidéo.                    |
| `loop`                | `boolean`                    | `true`                             | Boucle la vidéo.                                   |
| `muted`               | `boolean`                    | `true`                             | Coupe le son de la vidéo.                          |
| `playsInline`         | `boolean`                    | `true`                             | Conserve la lecture vidéo dans la page sur mobile. |
| `alt`                 | `string`                     | Généré                             | Texte alternatif de l’image.                       |
| `triggerType`         | `"hover" | "ref" | "inView"` | `hover`                            | Déclencheur utilisé pour révéler le média.         |
| `useInViewOptions`    | `UseInViewOptions`           | `{ once: true, amount: 0.5 }`      | Options du déclencheur de visibilité.              |
| `animationVariants`   | `object`                     | Révélation avec ressort de largeur | Variants Motion du conteneur média.                |
| `class`               | `string`                     | —                                  | Classes fusionnées sur la racine.                  |
| `leftTextClass`       | `string`                     | —                                  | Classes du premier fragment de texte.              |
| `rightTextClass`      | `string`                     | —                                  | Classes du second fragment de texte.               |

Le composant expose `animate()` et `reset()` avec le déclencheur `ref`.

#credits
- Porté depuis [Fancy Components Media Between Text](https://fancycomponents.dev/docs/components/blocks/media-between-text){rel=""nofollow""}.
::


# Onglets morphing

::component-viewer
---
component-files:
  - MorphingTabs.vue
component-id: morphing-tabs
config: MorphingTabsConfig
demo-file: MorphingTabsDemo.vue
---
#api
## API

| Nom de propriété   | Type       | Valeur par défaut | Description                                                      |
| ------------------ | ---------- | ----------------- | ---------------------------------------------------------------- |
| `class`            | `string`   | `""`              | Classes supplémentaires pour styliser le composant.              |
| `tabs`             | `string[]` | `[]`              | Onglets.                                                         |
| `activeTab`        | `string`   | `""`              | Onglet actif actuel.                                             |
| `margin`           | `number`   | `20`              | Marge gauche et droite de l'onglet actif.                        |
| `blurStdDeviation` | `number`   | `6`               | Valeur `stdDeviation` du flou SVG, utile pour arrondir l'onglet. |

#credits
- Merci à [Whbbit1999](https://github.com/Whbbit1999){rel=""nofollow""} pour ce composant.
- Inspiré et porté depuis [@Preet "Exclusion tabs"](https://x.com/wickedmishra/status/1823026659894940124){rel=""nofollow""}.
::


# Loader multi-étapes

::component-viewer
---
component-files:
  - MultiStepLoader.vue
component-id: multi-step-loader
config: MultiStepLoaderConfig
demo-file: MultiStepLoaderDemo.vue
---
#api
## API

| Nom de propriété  | Type      | Valeur par défaut | Description                                                      |
| ----------------- | --------- | ----------------- | ---------------------------------------------------------------- |
| `loading`         | `boolean` | `false`           | Contrôle la visibilité du loader. À `true`, le loader s'affiche. |
| `steps`           | `Step[]`  | `[]`              | Tableau d'objets étapes définissant la séquence de chargement.   |
| `defaultDuration` | `number`  | `1500`            | Durée de chaque étape en millisecondes.                          |
| `preventClose`    | `boolean` | `false`           | Si `true`, le bouton de fermeture n'est pas affiché.             |

| Nom de l'événement | Type de charge | Description                                                    |
| ------------------ | -------------- | -------------------------------------------------------------- |
| `state-change`     | `number`       | Émis lorsque l'étape courante change, fournit le nouvel index. |
| `complete`         | `void`         | Émis lorsque toutes les étapes sont terminées.                 |
| `close`            | `void`         | Émis lorsque le loader est fermé via le bouton.                |

#credits
- Merci à [M Atif](https://github.com/atif0075){rel=""nofollow""} pour ce composant.
- Inspiré par [Multi Step Loader d'Aceternity UI](https://ui.aceternity.com/components/multi-step-loader){rel=""nofollow""}.
::


# Parallax Float

::component-viewer
---
component-files:
  - ParallaxFloat.vue
  - ParallaxFloatElement.vue
  - ParallaxFloatContext.ts
  - index.ts
component-id: parallax-float
config: ParallaxFloatConfig
demo-file: ParallaxFloatDemo.vue
---
#api
## API

### ParallaxFloat

| Nom de prop    | Type     | Valeur par défaut | Description                              |
| -------------- | -------- | ----------------- | ---------------------------------------- |
| `sensitivity`  | `number` | `1`               | Multiplicateur appliqué à la profondeur. |
| `easingFactor` | `number` | `0.05`            | Interpolation effectuée à chaque image.  |
| `class`        | `string` | —                 | Classes supplémentaires du conteneur.    |

### ParallaxFloatElement

| Nom de prop | Type     | Valeur par défaut | Description                             |
| ----------- | -------- | ----------------- | --------------------------------------- |
| `depth`     | `number` | `1`               | Profondeur de déplacement de l'élément. |
| `class`     | `string` | —                 | Classes de positionnement et de style.  |

## Utilisation

Utilisez `ParallaxFloat` comme conteneur et placez chaque calque indépendant dans `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
- Porté depuis [Fancy Components Parallax Floating](https://fancycomponents.dev/docs/components/image/parallax-floating){rel=""nofollow""}.
::


# Marquee sur chemin

::component-viewer
---
component-files:
  - PathMarquee.vue
  - index.ts
component-id: path-marquee
config: PathMarqueeConfig
demo-file: PathMarqueeDemo.vue
---
#api
## API

| Prop                       | Type                        | Valeur par défaut                 | Description                                        |
| -------------------------- | --------------------------- | --------------------------------- | -------------------------------------------------- |
| `path`                     | `string`                    | —                                 | Données du chemin SVG utilisé pour les éléments.   |
| `pathId`                   | `string`                    | Généré                            | ID attribué au chemin SVG.                         |
| `showPath`                 | `boolean`                   | `false`                           | Afficher le tracé du chemin.                       |
| `width`                    | `string | number`           | `"100%"`                          | Largeur du SVG.                                    |
| `height`                   | `string | number`           | `"100%"`                          | Hauteur du SVG.                                    |
| `viewBox`                  | `string`                    | `"0 0 100 100"`                   | Système de coordonnées SVG.                        |
| `preserveAspectRatio`      | `string`                    | `"xMidYMid meet"`                 | Comportement du ratio SVG.                         |
| `baseVelocity`             | `number`                    | `5`                               | Vitesse du mouvement automatique.                  |
| `direction`                | `"normal" | "reverse"`      | `"normal"`                        | Direction initiale du mouvement.                   |
| `easing`                   | `(value: number) => number` | —                                 | Fonction d’assouplissement de la progression.      |
| `slowdownOnHover`          | `boolean`                   | `false`                           | Ralentir le mouvement au survol.                   |
| `slowDownFactor`           | `number`                    | `0.3`                             | Multiplicateur de vitesse au survol.               |
| `slowDownSpringConfig`     | `object`                    | `{ damping: 50, stiffness: 400 }` | Ressort du ralentissement au survol.               |
| `useScrollVelocity`        | `boolean`                   | `false`                           | Ajouter la vitesse de défilement au mouvement.     |
| `scrollAwareDirection`     | `boolean`                   | `false`                           | Suivre la direction du dernier défilement.         |
| `scrollSpringConfig`       | `object`                    | `{ damping: 50, stiffness: 400 }` | Ressort de la vitesse de défilement.               |
| `repeat`                   | `number`                    | `3`                               | Nombre de répétitions du contenu du slot.          |
| `draggable`                | `boolean`                   | `false`                           | Autoriser le glissement le long du chemin.         |
| `dragSensitivity`          | `number`                    | `0.2`                             | Multiplicateur appliqué à la vitesse de drag.      |
| `dragVelocityDecay`        | `number`                    | `0.96`                            | Décroissance de l’inertie après le drag.           |
| `dragAwareDirection`       | `boolean`                   | `false`                           | Suivre automatiquement la dernière direction.      |
| `grabCursor`               | `boolean`                   | `false`                           | Utiliser les curseurs grab avec le drag.           |
| `enableRollingZIndex`      | `boolean`                   | `true`                            | Empiler les éléments selon leur position.          |
| `zIndexBase`               | `number`                    | `1`                               | Valeur de z-index initiale.                        |
| `zIndexRange`              | `number`                    | `10`                              | Plage de z-index utilisée.                         |
| `cssVariableInterpolation` | `object[]`                  | `[]`                              | Interpoler des variables CSS selon la progression. |
| `responsive`               | `boolean`                   | `false`                           | Adapter l’espace de coordonnées au conteneur.      |
| `class`                    | `string`                    | —                                 | Classes supplémentaires fusionnées sur la racine.  |

Passez un ou plusieurs éléments via le slot par défaut. Chaque élément est répété et positionné sur le chemin.

#credits
- Porté depuis [Fancy Components Marquee Along SVG Path](https://fancycomponents.dev/docs/components/blocks/marquee-along-svg-path){rel=""nofollow""}.
::


# Galerie photo

::component-viewer
---
component-files:
  - PhotoGallery.vue
component-id: photo-gallery
config: PhotoGalleryConfig
demo-file: PhotoGalleryDemo.vue
---
#api
## API

| Nom de propriété | Type                | Valeur par défaut | Description                                                  |
| ---------------- | ------------------- | ----------------- | ------------------------------------------------------------ |
| `items`          | `"[{src: string}]"` | `[]`              | Éléments / sources d'images à animer.                        |
| `containerClass` | `string`            | `""`              | Classes Tailwind supplémentaires pour styliser le conteneur. |
| `class`          | `string`            | `""`              | Classes Tailwind supplémentaires pour un style personnalisé. |

#credits
- Toutes les images proviennent de [Pexels](https://www.pexels.com/@soldiervip/){rel=""nofollow""}
- Merci à [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} pour ce composant.
::


# Scroll Island

::component-viewer
---
component-files:
  - ScrollIsland.vue
component-id: scroll-island
config: ScrollIslandConfig
demo-file: ScrollIslandDemo.vue
dependencies: "@number-flow/vue"
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                             |
| ---------------- | -------- | ----------------- | ------------------------------------------------------- |
| `class`          | `string` | `""`              | Classes CSS supplémentaires pour un style personnalisé. |
| `title`          | `string` | `"Progress"`      | Titre affiché dans l'en-tête du composant.              |
| `height`         | `string` | `44`              | Hauteur du composant.                                   |

#credits
- Inspiré par le travail de [Ali Samadi](https://x.com/alisamadi__/status/1854312982559502556){rel=""nofollow""} & [Nitish Khagwal](https://x.com/nitishkmrk){rel=""nofollow""}
- [NumberFlow par Maxwell Barvian](https://number-flow.barvian.me/vue){rel=""nofollow""} pour le formatage et les animations numériques.
::


# Visionneuse Shader Toy

::component-viewer
---
component-files:
  - ShaderToy.vue
  - InspiraShaderToy.ts
component-id: shader-toy
config: ShaderToyConfig
demo-file: ShaderToyDemo.vue
dependencies: ogl
---
#api
## API

| Nom de propriété | Type                                | Valeur par défaut | Description                                                |
| ---------------- | ----------------------------------- | ----------------- | ---------------------------------------------------------- |
| `shaderCode`     | `string`                            | `-`               | Code source du fragment shader GLSL depuis ShaderToy.      |
| `uniforms`       | `Record<string, number | number[]>` | `{}`              | Valeurs des uniforms personnalisés déclarés par le shader. |
| `mouseMode`      | `'click' | 'hover'`                 | `'click'`         | Mode de suivi souris : au clic ou en survol continu.       |
| `hue`            | `number`                            | `0`               | Ajuste la teinte du rendu du shader.                       |
| `saturation`     | `number`                            | `1`               | Ajuste la saturation du rendu du shader.                   |
| `brightness`     | `number`                            | `1`               | Ajuste la luminosité du rendu du shader.                   |
| `speed`          | `number`                            | `1`               | Ajuste la vitesse d'animation du shader.                   |
| `frameRate`      | `number`                            | `60`              | Limite la fréquence de rendu des shaders plus lourds.      |
| `pixelRatio`     | `number`                            | `1`               | Règle l'échelle du canvas entre qualité et performance.    |
| `paused`         | `boolean`                           | `false`           | Met la lecture en pause manuellement.                      |
| `autoPause`      | `boolean`                           | `true`            | Pause le rendu hors écran ou quand l'onglet est caché.     |
| `class`          | `string`                            | `-`               | Classes personnalisées à appliquer au conteneur.           |

#credits
- Construit avec [OGL](https://github.com/oframe/ogl){rel=""nofollow""}.
- Inspiré par [Shadertoy](https://shadertoy.com/){rel=""nofollow""} et adapté pour la compatibilité Vue.
::


# Masque SVG

::component-viewer
---
component-files:
  - SVGMask.vue
component-id: svg-mask
config: SvgMaskConfig
demo-file: SvgMaskDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                             |
| ---------------- | -------- | ----------------- | ------------------------------------------------------- |
| `class`          | `string` | `""`              | Classes CSS supplémentaires pour un style personnalisé. |
| `size`           | `number` | `10`              | Taille initiale du masque en pixels.                    |
| `revealSize`     | `number` | `600`             | Taille du masque au survol, en pixels.                  |

#credits
- Porté depuis [l'effet SVG Mask d'Aceternity UI](https://ui.aceternity.com/components/text-generate-effect){rel=""nofollow""}.
::


# Chronologie

::component-viewer
---
component-files:
  - Timeline.vue
component-id: timeline
config: TimelineConfig
demo-file: TimelineDemo.vue
---
#api
## API

| Nom de propriété | Type                               | Valeur par défaut | Description                                                    |
| ---------------- | ---------------------------------- | ----------------- | -------------------------------------------------------------- |
| `containerClass` | `string`                           | `""`              | Classes CSS supplémentaires pour le conteneur de la timeline.  |
| `class`          | `string`                           | `""`              | Classes CSS supplémentaires pour le style.                     |
| `items`          | `{ id: string; label: string; }[]` | `[]`              | Liste des éléments de timeline, chacun avec un ID et un label. |
| `title`          | `string`                           | `""`              | Titre de la section timeline.                                  |
| `description`    | `string`                           | `""`              | Description affichée sous le titre.                            |

#credits
- Inspiré et porté depuis [Timeline d'Aceternity UI](https://ui.aceternity.com/components/timeline){rel=""nofollow""}.
::


# Faisceau traçant

::component-viewer
---
component-files:
  - TracingBeam.vue
component-id: tracing-beam
config: TracingBeamConfig
demo-file: TracingBeamDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                             |
| ---------------- | -------- | ----------------- | ------------------------------------------------------- |
| `class`          | `string` | `""`              | Classes CSS supplémentaires pour un style personnalisé. |

#credits
- Porté depuis [Aceternity UI](https://ui.aceternity.com/components/tracing-beam){rel=""nofollow""};
::


# Rayon animé

::component-viewer
---
component-files:
  - AnimatedBeam.vue
component-id: animated-beam
config: AnimatedBeamConfig
demo-file: AnimatedBeamDemo.vue
---
#api
## API

| Nom de propriété     | Type          | Valeur par défaut        | Description                                                                        |
| -------------------- | ------------- | ------------------------ | ---------------------------------------------------------------------------------- |
| `class`              | `string`      | `""`                     | Classes CSS supplémentaires à appliquer au composant pour le personnaliser.        |
| `containerRef`       | `HTMLElement` | N/A                      | Référence au conteneur dans lequel le rayon est rendu.                             |
| `fromRef`            | `HTMLElement` | N/A                      | Référence à l'élément de départ d'où part le rayon.                                |
| `toRef`              | `HTMLElement` | N/A                      | Référence à l'élément d'arrivée vers lequel pointe le rayon.                       |
| `curvature`          | `number`      | `0`                      | Contrôle la courbure du rayon ; une valeur plus élevée crée un chemin plus courbé. |
| `reverse`            | `boolean`     | `false`                  | Inverse le sens de l'animation du rayon si défini à `true`.                        |
| `pathColor`          | `string`      | `"gray"`                 | Couleur du tracé du rayon.                                                         |
| `pathWidth`          | `number`      | `2`                      | Largeur du tracé du rayon.                                                         |
| `pathOpacity`        | `number`      | `0.2`                    | Opacité du tracé du rayon.                                                         |
| `gradientStartColor` | `string`      | `"#FFAA40"`              | Couleur de départ de l'animation de dégradé du rayon.                              |
| `gradientStopColor`  | `string`      | `"#9C40FF"`              | Couleur de fin de l'animation de dégradé du rayon.                                 |
| `delay`              | `number`      | `0`                      | Délai avant le début de l'animation du rayon, en secondes.                         |
| `duration`           | `number`      | Aléatoire entre 4 et 7 s | Durée du cycle d'animation du rayon, en secondes.                                  |
| `startXOffset`       | `number`      | `0`                      | Décalage horizontal du point de départ du rayon.                                   |
| `startYOffset`       | `number`      | `0`                      | Décalage vertical du point de départ du rayon.                                     |
| `endXOffset`         | `number`      | `0`                      | Décalage horizontal du point d'arrivée du rayon.                                   |
| `endYOffset`         | `number`      | `0`                      | Décalage vertical du point d'arrivée du rayon.                                     |

#credits
- Inspiré et porté depuis [Magic UI Animated Beam](https://magicui.design/docs/components/animated-beam){rel=""nofollow""}.
::


# Rayon de bordure

::component-viewer
---
component-files:
  - BorderBeam.vue
component-id: border-beam
config: BorderBeamConfig
demo-file: BorderBeamDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                                          |
| ---------------- | -------- | ----------------- | -------------------------------------------------------------------- |
| `class`          | `string` | `""`              | Classes CSS supplémentaires pour un style personnalisé.              |
| `size`           | `number` | `200`             | Taille de l'effet de rayon sur la bordure.                           |
| `duration`       | `number` | `15`              | Durée de l'animation en secondes.                                    |
| `borderWidth`    | `number` | `1.5`             | Largeur de la bordure entourant l'effet.                             |
| `anchor`         | `number` | `90`              | Point d'ancrage du rayon, définit sa position le long de la bordure. |
| `colorFrom`      | `string` | `"#ffaa40"`       | Couleur de départ du dégradé du rayon.                               |
| `colorTo`        | `string` | `"#9c40ff"`       | Couleur de fin du dégradé du rayon.                                  |
| `delay`          | `number` | `0`               | Délai avant le démarrage de l'animation, en secondes.                |

#credits
- Porté depuis [Magic UI](https://magicui.design/docs/components/border-beam){rel=""nofollow""}.
::


# Confettis

::component-viewer
---
component-files:
  - Confetti.vue
  - ConfettiButton.vue
component-id: confetti
config: ConfettiConfig
demo-file: ConfettiDemo.vue
dependencies: canvas-confetti
dev-dependencies: "@types/canvas-confetti"
---
#api
## API

### Props

#### `Confetti`

| Nom de propriété | Type                    | Valeur par défaut | Description                                                                            |
| ---------------- | ----------------------- | ----------------- | -------------------------------------------------------------------------------------- |
| `options`        | `ConfettiOptions`       | `{}`              | Options pour chaque salve de confettis.                                                |
| `globalOptions`  | `ConfettiGlobalOptions` | `{}`              | Options globales pour l'instance de confettis (ex. comportement au redimensionnement). |
| `manualstart`    | `boolean`               | `false`           | Si `true`, les confettis ne démarrent pas automatiquement au montage.                  |

#### `ConfettiOptions`

| Propriété                 | Type                       | Valeur par défaut                                                               | Description                                                                       |
| ------------------------- | -------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `particleCount`           | `number`                   | `50`                                                                            | Nombre de particules de confettis à lancer.                                       |
| `angle`                   | `number`                   | `90`                                                                            | Angle de lancement des confettis, en degrés.                                      |
| `spread`                  | `number`                   | `45`                                                                            | Dispersion des confettis, en degrés.                                              |
| `startVelocity`           | `number`                   | `45`                                                                            | Vélocité initiale des particules de confettis.                                    |
| `decay`                   | `number`                   | `0.9`                                                                           | Taux auquel les particules ralentissent.                                          |
| `gravity`                 | `number`                   | `1`                                                                             | Gravité appliquée aux particules.                                                 |
| `drift`                   | `number`                   | `0`                                                                             | Dérive horizontale appliquée aux particules.                                      |
| `ticks`                   | `number`                   | `200`                                                                           | Nombre d'images d'animation pendant lesquelles les confettis restent.             |
| `origin`                  | `{ x: number, y: number }` | `{ x: 0.5, y: 0.5 }`                                                            | Point d'origine (0 à 1) de l'émission des confettis.                              |
| `colors`                  | `string[]`                 | `['#26ccff', '#a25afd', '#ff5e7e', '#88ff5a', '#fcff42', '#ffa62d', '#ff36ff']` | Tableau de couleurs hexadécimales pour les particules.                            |
| `shapes`                  | `string[]`                 | `['square', 'circle']`                                                          | Tableau des formes de particules.                                                 |
| `scalar`                  | `number`                   | `1`                                                                             | Facteur d'échelle pour la taille des particules.                                  |
| `zIndex`                  | `number`                   | `100`                                                                           | Valeur de z-index pour le canvas des confettis.                                   |
| `disableForReducedMotion` | `boolean`                  | `false`                                                                         | Désactive les confettis pour les utilisateurs préférant réduire les animations.   |
| `useWorker`               | `boolean`                  | `true`                                                                          | Utilise un Web Worker pour de meilleures performances.                            |
| `resize`                  | `boolean`                  | `true`                                                                          | Redimensionner automatiquement le canvas lors du redimensionnement de la fenêtre. |
| `canvas`                  | `HTMLCanvasElement | null` | `null`                                                                          | Canvas personnalisé sur lequel dessiner les confettis.                            |
| `gravity`                 | `number`                   | `1`                                                                             | Gravité appliquée aux particules de confettis.                                    |
| `drift`                   | `number`                   | `0`                                                                             | Dérive horizontale appliquée aux particules.                                      |
| `flat`                    | `boolean`                  | `false`                                                                         | Si `true`, les particules sont plates (sans rotation ni effet 3D).                |

#### `ConfettiButton`

| Nom de propriété | Type                                               | Valeur par défaut | Description                                             |
| ---------------- | -------------------------------------------------- | ----------------- | ------------------------------------------------------- |
| `options`        | `ConfettiOptions & { canvas?: HTMLCanvasElement }` | `{}`              | Options des confettis déclenchés au clic sur le bouton. |

#credits
- Construit avec la bibliothèque [canvas-confetti](https://www.npmjs.com/package/canvas-confetti){rel=""nofollow""}.
- Porté depuis [Magic UI Confetti](https://magicui.design/docs/components/confetti){rel=""nofollow""}.
::


# Shader de tramage

::component-viewer
---
component-files:
  - DitherShader.vue
component-id: dither-shader
config: DitherShaderConfig
demo-file: DitherShaderDemo.vue
---
#api
## API

| Nom de propriété  | Type                                              | Valeur par défaut        | Description                                                                                     |
| ----------------- | ------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------- |
| `src`             | `string`                                          | `-`                      | URL de l'image source.                                                                          |
| `gridSize`        | `number`                                          | `4`                      | Taille des cellules de la grille de tramage.                                                    |
| `ditherMode`      | `"bayer" | "halftone" | "noise" | "crosshatch"`   | `"bayer"`                | Type de motif de tramage.                                                                       |
| `colorMode`       | `"original" | "grayscale" | "duotone" | "custom"` | `"original"`             | Mode de traitement des couleurs.                                                                |
| `invert`          | `boolean`                                         | `false`                  | Inverse les couleurs du rendu tramé.                                                            |
| `pixelRatio`      | `number`                                          | `1`                      | Multiplicateur de pixelisation (1 = pas de pixelisation, plus haut = plus pixelisé).            |
| `primaryColor`    | `string`                                          | `"#000000"`              | Couleur primaire pour le mode duo.                                                              |
| `secondaryColor`  | `string`                                          | `"#ffffff"`              | Couleur secondaire pour le mode duo.                                                            |
| `customPalette`   | `string[]`                                        | `["#000000", "#ffffff"]` | Palette personnalisée pour le mode personnalisé.                                                |
| `brightness`      | `number`                                          | `0`                      | Ajustement de la luminosité (-1 à 1).                                                           |
| `contrast`        | `number`                                          | `1`                      | Ajustement du contraste (0 à 2, 1 = normal).                                                    |
| `backgroundColor` | `string`                                          | `"transparent"`          | Couleur de fond derrière l'image tramée.                                                        |
| `objectFit`       | `"cover" | "contain" | "fill" | "none"`           | `"cover"`                | Comportement d'ajustement de l'image.                                                           |
| `threshold`       | `number`                                          | `0.5`                    | Biais de seuil pour le tramage (0 à 1).                                                         |
| `animated`        | `boolean`                                         | `false`                  | Active l'effet animé.                                                                           |
| `animationSpeed`  | `number`                                          | `0.02`                   | Vitesse de l'animation (plus bas = plus lent).                                                  |
| `class`           | `string`                                          | `-`                      | Classes CSS supplémentaires pour le conteneur (à utiliser pour définir la taille via Tailwind). |

#credits
- Inspiré et porté depuis [Aceternity UI Dither Shader](https://ui.aceternity.com/components/dither-shader){rel=""nofollow""}.
::


# Bordure lumineuse

::component-viewer
---
component-files:
  - GlowBorder.vue
component-id: glow-border
config: GlowBorderConfig
demo-file: GlowBorderDemo.vue
---
#api
## API

| Nom de propriété | Type                | Valeur par défaut | Description                                            |
| ---------------- | ------------------- | ----------------- | ------------------------------------------------------ |
| `duration`       | `number`            | `10`              | Durée de l'animation de la bordure lumineuse.          |
| `color`          | `string | string[]` | `#FFF`            | Couleur ou tableau de couleurs appliqués à la bordure. |
| `borderRadius`   | `number`            | `10`              | Rayon de la bordure.                                   |
| `borderWidth`    | `number`            | `2`               | Largeur de la bordure.                                 |

#instructions
Ajoutez l'entrée suivante au thème inline dans votre fichier `main.css`.

```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
- Merci à [Magic UI](https://magicui.design/docs/components/shine-border){rel=""nofollow""} pour ce superbe composant.
::


# Effet lumineux

::component-viewer
---
component-files:
  - GlowingEffect.vue
component-id: glowing-effect
config: GlowingEffectConfig
demo-file: GlowingEffectDemo.vue
---
#api
## API

| Nom de propriété   | Type                  | Valeur par défaut | Description                                                                                                  |
| ------------------ | --------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------ |
| `blur`             | `number`              | `0`               | Rayon de flou appliqué à la couche lumineuse.                                                                |
| `inactiveZone`     | `number`              | `0.7`             | Définit le rayon interne (en fraction de la plus petite dimension) dans lequel l'effet lumineux est inactif. |
| `proximity`        | `number`              | `0`               | Distance supplémentaire (en pixels) déclenchant l'effet lorsque le curseur est proche de l'élément.          |
| `spread`           | `number`              | `20`              | Amplitude de diffusion de l'effet lumineux autour de l'élément.                                              |
| `variant`          | `"default" | "white"` | `"default"`       | Variante de style du halo (par exemple une version claire).                                                  |
| `glow`             | `boolean`             | `false`           | Contrôle la visibilité de la bordure lumineuse statique.                                                     |
| `class`            | `string`              | `""`              | Classes CSS supplémentaires pour un style personnalisé.                                                      |
| `disabled`         | `boolean`             | `true`            | Désactive la détection de proximité et les animations si `true`.                                             |
| `movementDuration` | `number`              | `2`               | Durée (en secondes) de l'animation de rotation fluide.                                                       |
| `borderWidth`      | `number`              | `1`               | Largeur (en pixels) de la bordure appliquée à l'effet lumineux.                                              |

#credits
- Porté depuis (Aceternity UI Glowing Effect) [<https://ui.aceternity.com/components/glowing-effect>{rel=""nofollow""}]
::


# Badge d'images

::component-viewer
---
component-files:
  - ImagesBadge.vue
component-id: images-badge
config: ImagesBadgeConfig
demo-file: ImagesBadgeDemo.vue
---
#api
## API

| Nom de la prop    | Type                                | Défaut                      | Description                                                                    |
| ----------------- | ----------------------------------- | --------------------------- | ------------------------------------------------------------------------------ |
| `text`            | `string`                            | —                           | Étiquette texte affichée à côté du badge dossier.                              |
| `images`          | `string[]`                          | —                           | Tableau d'URLs d'images à afficher (jusqu'à 3 sont montrées).                  |
| `class`           | `string`                            | —                           | Classes CSS supplémentaires pour l'élément racine.                             |
| `href`            | `string`                            | —                           | URL de lien optionnelle ; rend une balise `<a>` au lieu de `<div>` si fournie. |
| `target`          | `string`                            | —                           | Attribut target du lien (ex. `_blank` pour un nouvel onglet).                  |
| `folderSize`      | `{ width: number; height: number }` | `{ width: 32, height: 24 }` | Dimensions de l'icône dossier en pixels.                                       |
| `teaserImageSize` | `{ width: number; height: number }` | `{ width: 20, height: 14 }` | Dimensions des images en état d'aperçu (état inactif) en pixels.               |
| `hoverImageSize`  | `{ width: number; height: number }` | `{ width: 48, height: 32 }` | Dimensions des images au survol en pixels.                                     |
| `hoverTranslateY` | `number`                            | `-35`                       | Distance de déplacement vers le haut des images au survol en pixels.           |
| `hoverSpread`     | `number`                            | `20`                        | Écart horizontal entre les images au survol en pixels.                         |
| `hoverRotation`   | `number`                            | `15`                        | Angle de rotation en éventail des images au survol en degrés.                  |

#credits
- Porté depuis [Aceternity UI Images Badge](https://ui.aceternity.com/components/images-badge){rel=""nofollow""}
::


# Pluie de météores

::component-viewer
---
component-files:
  - Meteors.vue
component-id: meteors
config: MeteorsConfig
demo-file: MeteorsDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                                              |
| ---------------- | -------- | ----------------- | ------------------------------------------------------------------------ |
| `count`          | `number` | `20`              | Nombre de météores affichés dans l'animation.                            |
| `class`          | `string` | `""`              | Classes CSS supplémentaires à appliquer pour personnaliser les météores. |

#instructions
Ajoutez l'entrée suivante au thème inline dans votre fichier `main.css`.

```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
- Porté depuis [l'effet Meteor d'Aceternity UI](https://ui.aceternity.com/components/meteors){rel=""nofollow""}
::


# Bordure néon

::component-viewer
---
component-files:
  - NeonBorder.vue
component-id: neon-border
config: NeonBorderConfig
demo-file: NeonBorderDemo.vue
---
#api
## API

| Nom de propriété | Type                       | Valeur par défaut | Description                                |
| ---------------- | -------------------------- | ----------------- | ------------------------------------------ |
| `color1`         | `string`                   | `"#0496ff"`       | Couleur principale de la bordure néon.     |
| `color2`         | `string`                   | `"#ff0a54"`       | Couleur secondaire de la bordure néon.     |
| `animationType`  | `"none" | "half" | "full"` | `"half"`          | Type d'animation appliquée à la bordure.   |
| `duration`       | `number`                   | `6`               | Durée de l'effet d'animation en secondes.  |
| `class`          | `string`                   | `""`              | Classes CSS supplémentaires pour le style. |

#instructions
Ajoutez l'entrée suivante au thème inline dans votre fichier `main.css`.

```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
- Inspiré par les effets modernes de bordure néon.
::


# Image en particules

::component-viewer
---
component-files:
  - ParticleImage.vue
  - inspiraImageParticles.js
  - inspiraImageParticles.d.ts
component-id: particle-image
config: ParticleImageConfig
demo-file: ParticleImageDemo.vue
---
#api
## API

| Nom de propriété  | Type                                                                    | Valeur par défaut | Description                                                               |
| ----------------- | ----------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------- |
| `imageSrc`        | `string`                                                                | `null`            | URL source de l'image à laquelle appliquer l'effet de particules.         |
| `class`           | `string`                                                                | `null`            | Classes CSS supplémentaires à appliquer à l'élément image.                |
| `canvasWidth`     | `string`                                                                | `null`            | Largeur du canvas de l'effet de particules.                               |
| `canvasHeight`    | `string`                                                                | `null`            | Hauteur du canvas de l'effet de particules.                               |
| `gravity`         | `string`                                                                | `null`            | Force de gravité influençant le mouvement des particules.                 |
| `particleSize`    | `string`                                                                | `null`            | Taille des particules.                                                    |
| `particleGap`     | `string`                                                                | `null`            | Espace entre les particules.                                              |
| `mouseForce`      | `string`                                                                | `null`            | Force appliquée aux particules selon les mouvements de la souris.         |
| `renderer`        | `"default" | "webgl"`                                                   | `null`            | Moteur de rendu des particules, par défaut ou WebGL.                      |
| `color`           | `string`                                                                | `#FFF`            | Code couleur hexadécimal utilisé pour les particules (3 ou 6 caractères). |
| `colorArr`        | `number[]`                                                              | `null`            | Tableau de nombres définissant plusieurs couleurs de particules.          |
| `initPosition`    | `"random" | "top" | "left" | "bottom" | "right" | "misplaced" | "none"` | `random`          | Position initiale des particules au démarrage de l'animation.             |
| `initDirection`   | `"random" | "top" | "left" | "bottom" | "right" | "none"`               | `random`          | Direction initiale des particules au démarrage.                           |
| `fadePosition`    | `"explode" | "top" | "left" | "bottom" | "right" | "random" | "none"`   | `none`            | Position où les particules se dissipent.                                  |
| `fadeDirection`   | `"random" | "top" | "left" | "bottom" | "right" | "none"`               | `none`            | Direction dans laquelle les particules se dissipent.                      |
| `noise`           | `number`                                                                | `null`            | Niveau de bruit appliqué aux particules.                                  |
| `responsiveWidth` | `boolean`                                                               | `false`           | Indique si le canvas doit être responsive.                                |

#credits
- Merci à [Nuxt Labs](https://nuxtlabs.com){rel=""nofollow""} pour l'inspiration.
- Merci à [NextParticles](https://nextparticle.nextco.de){rel=""nofollow""} pour la base de la librairie d'animation.
::


# Flou progressif

::component-viewer
---
component-files:
  - ProgressiveBlur.vue
component-id: progressive-blur
config: ProgressiveBlurConfig
demo-file: ProgressiveBlurDemo.vue
---
#api
## API

| Nom de propriété | Type                                  | Valeur par défaut | Description                                                        |
| ---------------- | ------------------------------------- | ----------------- | ------------------------------------------------------------------ |
| `direction`      | `"top" | "right" | "bottom" | "left"` | `"bottom"`        | Direction dans laquelle le flou augmente progressivement.          |
| `blurLayers`     | `number`                              | `8`               | Nombre de couches de flou utilisées pour créer l'effet progressif. |
| `blurIntensity`  | `number`                              | `0.25`            | Multiplicateur d'intensité du flou par couche (en pixels).         |
| `class`          | `string`                              | `""`              | Classe optionnelle appliquée au conteneur englobant.               |

> Ce composant accepte aussi toutes les props `motion-v` valides pour un `div`.

#credits
- Porté depuis [Motion Primitives Progressive Blur](https://motion-primitives.com/docs/progressive-blur){rel=""nofollow""}.
- Propulsé par `motion-v`.
::


# Écailles

::component-viewer
---
component-files:
  - Scales.vue
component-id: scales
config: ScalesConfig
demo-file: ScalesDemo.vue
---
#api
## API

| Nom de la prop   | Type                                     | Défaut       | Description                                                     |
| ---------------- | ---------------------------------------- | ------------ | --------------------------------------------------------------- |
| `orientation`    | `"horizontal" | "vertical" | "diagonal"` | `"diagonal"` | Direction du motif de lignes répétées.                          |
| `size`           | `number`                                 | `10`         | Taille de chaque tuile répétée en pixels.                       |
| `color`          | `string`                                 | —            | Valeur de couleur CSS pour les lignes du motif.                 |
| `class`          | `string`                                 | —            | Classes CSS supplémentaires pour la superposition du motif.     |
| `containerClass` | `string`                                 | —            | Classes CSS supplémentaires pour l'élément conteneur extérieur. |

#credits
- Porté depuis [Aceternity UI Scales](https://ui.aceternity.com/components/scales){rel=""nofollow""}.
::


# Gratter pour révéler

::component-viewer
---
component-files:
  - ScratchToReveal.vue
component-id: scratch-to-reveal
config: ScratchToRevealConfig
demo-file: ScratchToRevealDemo.vue
---
#api
## API

| Nom de propriété       | Type                     | Valeur par défaut | Description                                                                             |
| ---------------------- | ------------------------ | ----------------- | --------------------------------------------------------------------------------------- |
| `class`                | `string`                 | `""`              | Nom de classe à appliquer au composant.                                                 |
| `width`                | `number`                 | `""`              | Largeur du conteneur à gratter.                                                         |
| `height`               | `number`                 | `""`              | Hauteur du conteneur à gratter.                                                         |
| `minScratchPercentage` | `number`                 | `50`              | Pourcentage minimal de surface grattée considéré comme terminé (valeur entre 0 et 100). |
| `gradientColors`       | `[string,string,string]` | `-`               | Couleurs de dégradé pour l'effet à gratter.                                             |

| Nom de l'événement | Charge utile | Description                                       |
| ------------------ | ------------ | ------------------------------------------------- |
| `complete`         | `-`          | Fonction appelée lorsque le grattage est terminé. |

| Nom du slot | Contenu par défaut | Description                        |
| ----------- | ------------------ | ---------------------------------- |
| `default`   | `-`                | Le texte sous le ticket à gratter. |

#credits
- Merci à [Whbbit1999](https://github.com/Whbbit1999){rel=""nofollow""} pour ce composant.
- Inspiré par [MagicUI Scratch To Reveal](https://magicui.design/docs/components/scratch-to-reveal){rel=""nofollow""}.
::


# Calendrier à ressorts

::component-viewer
---
component-files:
  - SpringCalendar.vue
  - TextMorph.vue
component-id: spring-calendar
config: SpringCalendarConfig
demo-file: SpringCalendarDemo.vue
---
#api
## API

| Nom de propriété | Type                                                                                                           | Valeur par défaut | Description                                                                               |
| ---------------- | -------------------------------------------------------------------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------- |
| `calendarData`   | `Array<{ month: string; date: number; day: string; events?: { title: string; day: string; time: string }[] }>` | **—**             | Tableau définissant chaque jour du calendrier et ses éventuels événements. *Requis.* |
| `initialIndex`   | `number`                                                                                                       | `0`               | Index du jour sélectionné au départ.                                                      |

### Événements émis

| Nom de l'événement   | Charge utile | Description                                                             |
| -------------------- | ------------ | ----------------------------------------------------------------------- |
| `update:activeIndex` | `number`     | Déclenché lorsqu'un jour est cliqué, en émettant le nouvel index actif. |

#credits
- Inspiré par le travail de [sekachov](https://x.com/sekachov){rel=""nofollow""}
::


# Témoignages animés

::component-viewer
---
component-files:
  - AnimatedTestimonials.vue
component-id: animated-testimonials
config: AnimatedTestimonialsConfig
demo-file: AnimatedTestimonialsDemo.vue
---
#api
## API

| Nom de propriété | Type            | Valeur par défaut | Description                                                                     |
| ---------------- | --------------- | ----------------- | ------------------------------------------------------------------------------- |
| `testimonials`   | `Testimonial[]` | `[]`              | Tableau d'objets témoignages contenant citation, nom, image et fonction.        |
| `autoplay`       | `boolean`       | `false`           | Indique si les témoignages doivent défiler automatiquement.                     |
| `duration`       | `number`        | `5000`            | Durée (en millisecondes) avant de passer automatiquement au témoignage suivant. |

### Objet Testimonial

Chaque objet de témoignage doit contenir les champs suivants :

| Propriété     | Type     | Description                                                     |
| ------------- | -------- | --------------------------------------------------------------- |
| `quote`       | `string` | Texte du témoignage.                                            |
| `name`        | `string` | Nom de la personne ou entité donnant le témoignage.             |
| `designation` | `string` | Poste ou rôle de l'auteur du témoignage (ex. CEO, utilisateur). |
| `image`       | `string` | URL de l'image ou de l'avatar de l'auteur du témoignage.        |

#credits
- Porté depuis (Aceternity UI Animated Testimonials) [<https://ui.aceternity.com/components/animated-testimonials>{rel=""nofollow""}].
::


# Témoignages design

::component-viewer
---
component-files:
  - DesignTestimonials.vue
component-id: design-testimonials
config: DesignTestimonialsConfig
demo-file: DesignTestimonialsDemo.vue
---
#api
## API

| Nom de propriété | Type                | Valeur par défaut | Description                                                          |
| ---------------- | ------------------- | ----------------- | -------------------------------------------------------------------- |
| `title`          | `string`            | `"Testimonials"`  | Libellé vertical affiché sur le côté gauche de la mise en page.      |
| `duration`       | `number`            | `6000`            | Durée (en ms) avant de passer automatiquement au témoignage suivant. |
| `testimonials`   | `TestimonialItem[]` | **requis**        | Liste des témoignages à afficher et animer.                          |

### Objet `TestimonialItem`

Chaque témoignage doit suivre cette structure :

| Propriété | Type     | Description                                                               |
| --------- | -------- | ------------------------------------------------------------------------- |
| `quote`   | `string` | Texte du témoignage, animé mot à mot.                                     |
| `author`  | `string` | Nom de l'auteur du témoignage.                                            |
| `role`    | `string` | Rôle ou fonction de l'auteur.                                             |
| `company` | `string` | Nom de l'entreprise ou organisation (utilisé dans le badge et le ticker). |

#credits
- Animations propulsées par `motion-v`
- Porté depuis [Design Testimonials par Jatin Yadav](https://21st.dev/community/components/jatin-yadav05/design-testimonial/default){rel=""nofollow""}
::


# Slider de témoignages

::component-viewer
---
component-files:
  - TestimonialSlider.vue
component-id: testimonial-slider
config: TestimonialSliderConfig
demo-file: TestimonialSliderDemo.vue
---
#api
## API

| Nom de propriété | Type                                                                | Valeur par défaut | Description                                                                 |
| ---------------- | ------------------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------- |
| `testimonials`   | `Array<{ img: string; quote: string; name: string; role: string }>` | `[]`              | Tableau d'objets témoignages affichés par le slider.                        |
| `autoRotate`     | `boolean`                                                           | `true`            | Si `true`, le slider avance automatiquement toutes les `duration` secondes. |
| `duration`       | `number`                                                            | `5`               | Intervalle en secondes entre les slides lorsque l'auto-rotation est active. |
::


# Texte 3D

::component-viewer
---
component-files:
  - Text3d.vue
component-id: text-3d
config: Text3dConfig
demo-file: Text3dDemo.vue
---
#api
## API

| Nom de propriété    | Type      | Valeur par défaut | Description                                             |
| ------------------- | --------- | ----------------- | ------------------------------------------------------- |
| `textColor`         | `string`  | `"white"`         | Couleur du texte principal.                             |
| `letterSpacing`     | `number`  | `-0.1`            | Ajuste l'espacement des lettres en unités `ch`.         |
| `strokeColor`       | `string`  | `"black"`         | Couleur du contour du texte.                            |
| `shadowColor`       | `string`  | `"yellow"`        | Couleur de l'ombre du texte.                            |
| `strokeSize`        | `number`  | `20`              | Épaisseur du contour en pixels.                         |
| `shadow1Size`       | `number`  | `7`               | Taille de la première couche d'ombre, en pixels.        |
| `shadow2Size`       | `number`  | `10`              | Taille de la seconde couche d'ombre, en pixels.         |
| `class`             | `string`  | `""`              | Classes CSS supplémentaires pour un style personnalisé. |
| `animate`           | `boolean` | `true`            | Active l'animation de balancement lorsqu'à `true`.      |
| `animationDuration` | `number`  | `1500`            | Durée de l'animation en millisecondes.                  |
::


# Révélation floutée

::component-viewer
---
component-files:
  - BlurReveal.vue
component-id: blur-reveal
config: BlurRevealConfig
demo-file: BlurRevealDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                              |
| ---------------- | -------- | ----------------- | -------------------------------------------------------- |
| `duration`       | `number` | `1`               | Durée de l'animation de révélation par flou.             |
| `delay`          | `number` | `1`               | Délai entre les composants enfants à révéler.            |
| `blur`           | `string` | `10px`            | Intensité du flou appliqué aux éléments enfants.         |
| `yOffset`        | `number` | `20`              | Décalage vertical appliqué lors de l'animation d'entrée. |

#credits
- Merci à [Magic UI](https://magicui.design/docs/components/blur-fade){rel=""nofollow""} pour ce superbe composant.
::


# Révélation en boîte

::component-viewer
---
component-files:
  - BoxReveal.vue
component-id: box-reveal
config: BoxRevealConfig
demo-file: BoxRevealDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                             |
| ---------------- | -------- | ----------------- | ------------------------------------------------------- |
| `color`          | `string` | `"#5046e6"`       | Couleur de fond de la boîte de révélation.              |
| `duration`       | `number` | `0.5`             | Durée de l'animation en secondes.                       |
| `delay`          | `number` | `0.25`            | Délai avant le début de l'animation, en secondes.       |
| `class`          | `string` | `""`              | Classes CSS supplémentaires pour un style personnalisé. |

#credits
- Porté depuis [Magic UI Box Reveal](https://magicui.design/docs/components/box-reveal){rel=""nofollow""}.
::


# Texte respirant

::component-viewer
---
component-files:
  - BreathingText.vue
  - index.ts
component-id: breathing-text
config: BreathingTextConfig
demo-file: BreathingTextDemo.vue
---
#api
## API

| Prop                        | Type                                   | Valeur par défaut                      | Description                                              |
| --------------------------- | -------------------------------------- | -------------------------------------- | -------------------------------------------------------- |
| `text`                      | `string`                               | Contenu du slot                        | Texte à diviser en lettres animées séparément.           |
| `as`                        | `string`                               | `"span"`                               | Élément HTML utilisé pour le texte racine.               |
| `fromFontVariationSettings` | `string`                               | —                                      | Axes de police utilisés au début de chaque cycle.        |
| `toFontVariationSettings`   | `string`                               | —                                      | Axes de police utilisés à la fin de chaque cycle.        |
| `transition`                | `Transition`                           | `{ duration: 1.5, ease: "easeInOut" }` | Transition Motion de chaque lettre.                      |
| `staggerDuration`           | `number`                               | `0.1`                                  | Délai entre les animations de chaque lettre.             |
| `staggerFrom`               | `"first" | "last" | "center" | number` | `"first"`                              | Origine utilisée pour calculer l’ordre du décalage.      |
| `repeatDelay`               | `number`                               | `0.1`                                  | Délai entre les cycles de respiration.                   |
| `class`                     | `string`                               | —                                      | Classes supplémentaires fusionnées sur l’élément racine. |

Utilisez une police variable et transmettez les axes qu’elle prend en charge. Par exemple, Roboto Flex accepte `wght` et `wdth`.

#credits
- Porté depuis [Fancy Components Breathing Text](https://fancycomponents.dev/docs/components/text/breathing-text){rel=""nofollow""}.
::


# Texte coloré

::component-viewer
---
component-files:
  - ColourfulText.vue
component-id: colourful-text
config: ColourfulTextConfig
demo-file: ColourfulTextDemo.vue
---
#api
## API

| Nom de propriété | Type       | Valeur par défaut                                                                                                                                                                                                  | Description                                                                                                                                          |
| ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`           | `string`   | `"black"`                                                                                                                                                                                                          | Chaîne de texte à afficher avec des caractères animés et colorés. Chaque caractère est animé individuellement (transitions de couleur et mouvement). |
| `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)", ]` | Palette de couleurs appliquée au texte.                                                                                                              |
| `startColor`     | `string`   | `"rgb(255,255,255)"`                                                                                                                                                                                               | Couleur de départ des caractères.                                                                                                                    |
| `duration`       | `number`   | `5`                                                                                                                                                                                                                | Durée de l'animation en secondes.                                                                                                                    |

#credits
- Merci à [Whbbit1999](https://github.com/Whbbit1999){rel=""nofollow""} pour ce composant.
- Porté depuis [Colourful Text d'Aceternity UI](https://ui.aceternity.com/components/colourful-text){rel=""nofollow""}
::


# Conteneur de mots pivotants

::component-viewer
---
component-files:
  - ContainerTextFlip.vue
component-id: container-text-flip
config: ContainerTextFlipConfig
demo-file: ContainerTextFlipDemo.vue
---
#api
## API

| Nom de propriété    | Type       | Valeur par défaut                              | Description                                           |
| ------------------- | ---------- | ---------------------------------------------- | ----------------------------------------------------- |
| `words`             | `string[]` | `["better", "modern", "beautiful", "awesome"]` | Tableau de mots à faire défiler dans l'animation.     |
| `interval`          | `number`   | `3000`                                         | Temps en millisecondes entre chaque transition.       |
| `animationDuration` | `number`   | `700`                                          | Durée de l'animation de transition, en millisecondes. |
| `class`             | `string`   | \`\`                                           | Classes CSS supplémentaires à appliquer au conteneur. |
| `textClass`         | `string`   | \`\`                                           | Classes CSS supplémentaires à appliquer au texte.     |

#credits
- Merci à [Whbbit1999](https://github.com/Whbbit1999){rel=""nofollow""} pour ce composant.
- Porté depuis [Container Text Flip d'Aceternity UI](https://ui.aceternity.com/components/container-text-flip){rel=""nofollow""}.
::


# Texte chiffré

::component-viewer
---
component-files:
  - EncryptedText.vue
component-id: encrypted-text
config: EncryptedTextConfig
demo-file: EncryptedTextDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut                        | Description                                                            |
| ---------------- | -------- | ---------------------------------------- | ---------------------------------------------------------------------- |
| `text`           | `string` | **required**                             | Le texte à afficher et à révéler.                                      |
| `class`          | `string` | `""`                                     | Classe de base appliquée à l'élément conteneur.                        |
| `revealDelayMs`  | `number` | `50`                                     | Délai (en ms) entre la révélation de chaque caractère suivant.         |
| `flipDelayMs`    | `number` | `50`                                     | Délai (en ms) entre chaque ré-embrouillage des caractères non révélés. |
| `charset`        | `string` | `A–Z a–z 0–9 !@#$%^&*()_+-={}[];:,.<>/?` | Jeu de caractères utilisé pour les glyphes brouillés.                  |
| `encryptedClass` | `string` | `""`                                     | Classe appliquée aux caractères encore chiffrés/brouillés.             |
| `revealedClass`  | `string` | `""`                                     | Classe appliquée aux caractères une fois révélés.                      |

#credits
- Porté depuis [Aceternity UI Encrypted Text](https://ui.aceternity.com/components/encrypted-text){rel=""nofollow""}.
- Animation propulsée par `motion-v`.
::


# Mots pivotants

::component-viewer
---
component-files:
  - FlipWords.vue
component-id: flip-words
config: FlipWordsConfig
demo-file: FlipWordsDemo.vue
---
#api
## API

| Nom de propriété | Type     | Description                                                                    |
| ---------------- | -------- | ------------------------------------------------------------------------------ |
| `words`          | `Array`  | Tableau de mots à afficher et animer.                                          |
| `duration`       | `number` | Durée (en millisecondes) d'affichage de chaque mot avant de passer au suivant. |
| `class`          | `string` | Classes CSS supplémentaires à appliquer au composant.                          |

#credits
- Merci à [M Atif](https://github.com/atif0075){rel=""nofollow""} pour le portage de ce composant.
- Porté depuis [Flip Words d'Aceternity UI](https://ui.aceternity.com/components/flip-words){rel=""nofollow""}
::


# Focus

::component-viewer
---
component-files:
  - Focus.vue
component-id: focus
config: FocusConfig
demo-file: FocusDemo.vue
---
#api
## API

| Nom de propriété         | Type      | Valeur par défaut | Description                                                       |
| ------------------------ | --------- | ----------------- | ----------------------------------------------------------------- |
| `sentence`               | `string`  | `"Inspira Focus"` | Phrase à afficher et animer mot par mot.                          |
| `manualMode`             | `boolean` | `false`           | Si `true`, le focus se fait au survol ; sinon il défile auto.     |
| `blurAmount`             | `number`  | `5`               | Rayon de flou en pixels pour les mots inactifs.                   |
| `borderColor`            | `string`  | `"green"`         | Couleur de la bordure du cadre de focus animé.                    |
| `animationDuration`      | `number`  | `0.5`             | Durée, en secondes, des transitions d'animation du cadre.         |
| `pauseBetweenAnimations` | `number`  | `1`               | Pause, en secondes, entre deux transitions de focus automatiques. |

#credits
- Inspiré par [l'effet Focus Text Hover sur CodePen](https://codepen.io/CameronFitzwilliam/pen/JJRjMa){rel=""nofollow""}.
::


# Texte surligné

::component-viewer
---
component-files:
  - HighlightText.vue
  - index.ts
component-id: highlight-text
config: HighlightTextConfig
demo-file: HighlightTextDemo.vue
---
#api
## API

| Prop               | Type                                   | Valeur par défaut                             | Description                                  |
| ------------------ | -------------------------------------- | --------------------------------------------- | -------------------------------------------- |
| `as`               | `string`                               | `span`                                        | Élément utilisé pour le conteneur externe.   |
| `triggerType`      | `hover` \| `ref` \| `inView` \| `auto` | `inView`                                      | Déclencheur de l'animation.                  |
| `transition`       | `Record<string, unknown>`              | transition spring                             | Transition Motion du balayage.               |
| `useInViewOptions` | `Record<string, unknown>`              | `{ once: true, initial: false, amount: 0.1 }` | Options du déclencheur d'entrée dans la vue. |
| `class`            | `string`                               | `-`                                           | Classes fusionnées avec le texte surligné.   |
| `highlightColor`   | `string`                               | `hsl(25 90% 80%)`                             | Couleur du surlignage.                       |
| `direction`        | `ltr` \| `rtl` \| `ttb` \| `btt`       | `ltr`                                         | Direction du balayage.                       |

Avec le déclencheur `ref`, le composant expose `animate(direction?)` et `reset()`.

#credits
- Inspiré par [Fancy Components](https://fancycomponents.dev/docs/components/text/text-highlighter){rel=""nofollow""}.
::


# Hyper texte

::component-viewer
---
component-files:
  - HyperText.vue
component-id: hyper-text
config: HyperTextConfig
demo-file: HyperTextDemo.vue
---
#api
## API

| Nom de propriété | Type      | Valeur par défaut | Description                                           |
| ---------------- | --------- | ----------------- | ----------------------------------------------------- |
| `class`          | `string`  | `""`              | Classes CSS supplémentaires à appliquer au composant. |
| `text`           | `string`  | Requise           | Texte à animer.                                       |
| `duration`       | `number`  | `0.8`             | Durée totale de l'animation, en secondes.             |
| `animateOnLoad`  | `boolean` | `true`            | Lance l'animation au chargement.                      |

#credits
- Inspiré du composant [Hyper Text de Magic UI](https://magicui.design/docs/components/hyper-text){rel=""nofollow""}.
- Merci à [Prem](https://github.com/premdasvm){rel=""nofollow""} pour le portage de ce composant.
::


# Lettres en soulèvement

::component-viewer
---
component-files:
  - LetterPullup.vue
component-id: letter-pullup
config: LetterPullupConfig
demo-file: LetterPullupDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut          | Description                                                |
| ---------------- | -------- | -------------------------- | ---------------------------------------------------------- |
| `class`          | `string` | `-`                        | Classe appliquée au composant.                             |
| `words`          | `string` | `Staggered Letter Pull Up` | Texte à animer.                                            |
| `delay`          | `number` | `0.05`                     | Délai en secondes appliqué à l'animation de chaque lettre. |

#credits
- Merci à [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} pour ce composant.
- Inspiré par [Magic UI](https://magicui.design/docs/components/letter-pullup){rel=""nofollow""}.
::


# Letter Swap

::component-viewer
---
component-files:
  - LetterSwap.vue
  - index.ts
component-id: letter-swap
config: LetterSwapConfig
demo-file: LetterSwapDemo.vue
dependencies: motion-v
---
#api
| Prop              | Type                                   | Valeur par défaut                   | Description                                               |
| ----------------- | -------------------------------------- | ----------------------------------- | --------------------------------------------------------- |
| `label`           | `string`                               | —                                   | Texte à afficher et à animer.                             |
| `animation`       | `"forward" | "pingpong"`               | `"forward"`                         | Joue une fois ou s'inverse lorsque le pointeur sort.      |
| `random`          | `boolean`                              | `false`                             | Anime les lettres dans un ordre mélangé.                  |
| `reverse`         | `boolean`                              | `true`                              | Définit la direction verticale de l'échange.              |
| `transition`      | `Transition`                           | `{ type: "spring", duration: 0.7 }` | Transition Motion utilisée pour chaque lettre.            |
| `staggerDuration` | `number`                               | `0.03`                              | Délai entre le début de l'animation de chaque lettre.     |
| `staggerFrom`     | `"first" | "last" | "center" | number` | `"first"`                           | Origine utilisée pour calculer l'ordre décalé.            |
| `class`           | `string`                               | `-`                                 | Classes supplémentaires fusionnées avec l'élément racine. |

#credits
- Inspiré par [Fancy Components](https://fancycomponents.dev/docs/components/text/letter-swap.md){rel=""nofollow""}.
- Œuvre originale de [Daniel Petho](https://github.com/danielpetho/fancy){rel=""nofollow""}.
::


# Texte à ombre linéaire

::component-viewer
---
component-files:
  - LineShadowText.vue
component-id: line-shadow-text
config: LineShadowTextConfig
demo-file: LineShadowTextDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                             |
| ---------------- | -------- | ----------------- | ------------------------------------------------------- |
| `shadowColor`    | `string` | `"black"`         | Couleur de l'effet d'ombre.                             |
| `class`          | `string` | `""`              | Classes CSS supplémentaires pour un style personnalisé. |
| `as`             | `string` | `"span"`          | Élément HTML utilisé pour rendre le texte.              |

#credits
- Merci à [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} pour ce composant.
- Porté depuis [Line Shadow Text de Magic UI](https://magicui.design/docs/components/line-shadow-text){rel=""nofollow""}
::


# Texte morphing

::component-viewer
---
component-files:
  - MorphingText.vue
component-id: morphing-text
config: MorphingTextConfig
demo-file: MorphingTextDemo.vue
---
#api
## API

| Nom de propriété | Type       | Valeur par défaut | Description                                |
| ---------------- | ---------- | ----------------- | ------------------------------------------ |
| `texts`          | `string[]` | `[]`              | Tableau de textes entre lesquels alterner. |
| `class`          | `string`   | `""`              | Classes supplémentaires pour le conteneur. |
| `morphTime`      | `number`   | `1.5`             | Durée d'exécution de l'animation.          |
| `coolDownTime`   | `number`   | `0.5`             | Temps de pause de l'animation.             |

#credits
- Merci à [Whbbit1999](https://github.com/Whbbit1999){rel=""nofollow""} pour ce composant.
- Inspiré et porté depuis [Magic UI Morphing Text](https://magicui.design/docs/components/morphing-text){rel=""nofollow""}.
::


# Compteur numérique

::component-viewer
---
component-files:
  - NumberTicker.vue
component-id: number-ticker
config: NumberTickerConfig
demo-file: NumberTickerDemo.vue
---
#api
## API

| Nom de propriété | Type                | Valeur par défaut | Description                                                                                        |
| ---------------- | ------------------- | ----------------- | -------------------------------------------------------------------------------------------------- |
| `value`          | `int`               | `0`               | Valeur cible.                                                                                      |
| `direction`      | `up | down`         | `up`              | Direction du comptage.                                                                             |
| `decimalPlaces`  | `number`            | `0`               | Nombre de décimales à afficher.                                                                    |
| `delay`          | `number`            | `0`               | Délai avant le démarrage du comptage (en millisecondes).                                           |
| `duration`       | `number`            | `1000`            | Durée totale de l'animation (en millisecondes).                                                    |
| `transition`     | `TransitionPresets` | `easeOutCubic`    | Nom du preset de transition (<https://vueuse.org/core/useTransition>{rel=""nofollow""}). |

#credits
- Merci à [Grzegorz Krol](https://github.com/Grzechu335){rel=""nofollow""} pour le portage de ce composant.
- Porté depuis [Magic UI NumberTicker](https://magicui.design/docs/components/number-ticker){rel=""nofollow""}.
::


# Texte rayonnant

::component-viewer
---
component-files:
  - RadiantText.vue
component-id: radiant-text
config: RadiantTextConfig
demo-file: RadiantTextDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                        |
| ---------------- | -------- | ----------------- | ---------------------------------- |
| `duration`       | `number` | `10`              | Durée de l'animation en secondes.  |
| `radiantWidth`   | `number` | `100`             | Largeur de l'animation rayonnante. |

#credits
- Merci à [Magic UI](https://magicui.design/docs/components/animated-shiny-text){rel=""nofollow""} pour ce superbe composant.
::


# Screw Text

::component-viewer
---
component-files:
  - ScrewText.vue
  - index.ts
component-id: screw-text
config: ScrewTextConfig
demo-file: ScrewTextDemo.vue
---
#api
## API

| Prop              | Type                                   | Valeur par défaut  | Description                                  |
| ----------------- | -------------------------------------- | ------------------ | -------------------------------------------- |
| `label`           | `string`                               | —                  | Texte séparé en lettres animées.             |
| `as`              | `string`                               | `"p"`              | Élément HTML utilisé pour le texte racine.   |
| `rotateDirection` | `"top" | "right" | "bottom" | "left"`  | `"right"`          | Axe et direction de la transition 3D.        |
| `staggerDuration` | `number`                               | `0.05`             | Délai entre les animations des lettres.      |
| `staggerFrom`     | `"first" | "last" | "center" | number` | `"first"`          | Origine utilisée pour l'ordre décalé.        |
| `transition`      | `Transition`                           | Transition ressort | Transition Motion utilisée pour les lettres. |
| `class`           | `string`                               | —                  | Classes supplémentaires de l'élément racine. |
| `frontFaceClass`  | `string`                               | —                  | Classes de la face avant des lettres.        |
| `secondFaceClass` | `string`                               | —                  | Classes de la seconde face des lettres.      |

#credits
- Porté depuis [Fancy Components Letter 3D Swap](https://fancycomponents.dev/docs/components/text/letter-3d-swap){rel=""nofollow""}.
- Travail original de [Daniel Petho](https://github.com/danielpetho/fancy){rel=""nofollow""}.
::


# Texte à défilement

::component-viewer
---
component-files:
  - ScrollSwapText.vue
  - index.ts
component-id: scroll-swap-text
config: ScrollSwapTextConfig
demo-file: ScrollSwapTextDemo.vue
---
#api
## API

| Prop           | Type                      | Valeur par défaut                 | Description                                                   |
| -------------- | ------------------------- | --------------------------------- | ------------------------------------------------------------- |
| `as`           | `string`                  | `span`                            | Élément utilisé pour le conteneur du texte.                   |
| `containerRef` | `MaybeComputedElementRef` | —                                 | Conteneur de défilement utilisé pour calculer la progression. |
| `offset`       | `[string, string]`        | `["0 0", "0 1"]`                  | Décalages qui définissent la plage de l'animation.            |
| `class`        | `string`                  | `-`                               | Classes supplémentaires fusionnées avec le conteneur.         |
| `springConfig` | `object`                  | `{ stiffness: 200, damping: 30 }` | Configuration spring qui lisse la progression.                |

Le composant rend deux fois le texte du slot. Pendant le défilement, le premier texte sort tandis que le second entre.

#credits
- Inspiré par [Fancy Components](https://fancycomponents.dev/docs/components/text/scroll-and-swap){rel=""nofollow""}.
::


# Texte étincelant

::component-viewer
---
component-files:
  - SparklesText.vue
component-id: sparkles-text
config: SparklesTextConfig
demo-file: SparklesTextDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut                        | Description                                 |
| ---------------- | -------- | ---------------------------------------- | ------------------------------------------- |
| `class`          | `string` | `-`                                      | Classe appliquée au texte étincelant.       |
| `text`           | `string` | \`\`                                     | Texte à afficher.                           |
| `sparklesCount`  | `number` | `10`                                     | Nombre d'étincelles affichées sur le texte. |
| `colors`         | `object` | `{first: '#A07CFE'; second: '#FE8FB5';}` | Couleurs des étincelles.                    |

#credits
- Merci à [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} pour ce composant.
- Inspiré par [Magic UI](https://magicui.design/docs/components/sparkles-text){rel=""nofollow""}.
- Merci à [M Atif](https://github.com/atif0075){rel=""nofollow""} pour la mise à jour de ce composant.
::


# Texte rotatif

::component-viewer
---
component-files:
  - SpinningText.vue
component-id: spinning-text
config: SpinningTextConfig
demo-file: SpinningTextDemo.vue
---
#api
## API

| Nom de propriété | Type                                                    | Valeur par défaut | Description                                             |
| ---------------- | ------------------------------------------------------- | ----------------- | ------------------------------------------------------- |
| `duration`       | `number`                                                | `10`              | Durée de la rotation circulaire complète.               |
| `reverse`        | `boolean`                                               | `false`           | Indique si l'animation tourne en sens inverse.          |
| `radius`         | `number`                                                | `5`               | Rayon du trajet circulaire pour l'animation du texte.   |
| `transition`     | `motion-v Transition`                                   | \`\`              | Effets de transition personnalisés pour l'animation.    |
| `variants`       | `{container: motion-v Variant, item: motion-v Variant}` | \`\`              | Variants pour les animations du conteneur et des items. |
| `class`          | `string`                                                | `""`              | Classe personnalisée pour le conteneur de texte.        |

#credits
- Merci à [Whbbit1999](https://github.com/Whbbit1999){rel=""nofollow""} pour ce composant.
- Porté depuis [Magic UI Spinning Text](https://magicui.design/docs/components/spinning-text){rel=""nofollow""}.
::


# Effet de génération de texte

::component-viewer
---
component-files:
  - TextGenerateEffect.vue
component-id: text-generate-effect
config: TextGenerateConfig
demo-file: TextGenerateDemo.vue
---
#api
## API

| Nom de propriété | Type      | Valeur par défaut | Description                                                |
| ---------------- | --------- | ----------------- | ---------------------------------------------------------- |
| `words`          | `string`  | Requise           | Texte à afficher avec l'effet de génération.               |
| `duration`       | `number`  | `0.7`             | Durée de l'animation de génération, en secondes.           |
| `delay`          | `number`  | `0`               | Délai avant le démarrage de l'animation, en millisecondes. |
| `filter`         | `boolean` | `true`            | Intensité du flou appliqué au texte.                       |

#credits
- Merci à [M Atif](https://github.com/atif0075){rel=""nofollow""} pour le portage de ce composant.
- Porté depuis [Text Generate Effect d'Aceternity UI](https://ui.aceternity.com/components/text-generate-effect){rel=""nofollow""}.
::


# Texte glitch

::component-viewer
---
component-files:
  - TextGlitch.vue
component-id: text-glitch
config: TextGlitchConfig
demo-file: TextGlitchDemo.vue
---
#api
## API

| Nom de propriété | Type      | Valeur par défaut | Description                                               |
| ---------------- | --------- | ----------------- | --------------------------------------------------------- |
| `text`           | `string`  | `""`              | Texte à afficher avec l'effet glitch.                     |
| `speed`          | `number`  | `0.5`             | Vitesse de l'animation glitch, en secondes.               |
| `enableShadows`  | `boolean` | `true`            | Active les ombres colorées qui renforcent l'effet glitch. |
| `enableOnHover`  | `boolean` | `false`           | Si `true`, l'animation glitch ne s'active qu'au survol.   |
| `class`          | `string`  | `undefined`       | Classes CSS supplémentaires pour la div conteneur.        |

#credits
- Inspiré et développé à partir des ressources des vidéos YouTube suivantes.
  - <https://www.youtube.com/watch?v=7Xyg8Ja7dyY>{rel=""nofollow""}
  - <https://www.youtube.com/watch?v=9CCkp_El1So>{rel=""nofollow""}
::


# Surlignage de texte

::component-viewer
---
component-files:
  - TextHighlight.vue
component-id: text-highlight
config: TextHighlightConfig
demo-file: TextHighlightDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                                                   |
| ---------------- | -------- | ----------------- | ----------------------------------------------------------------------------- |
| `delay`          | `number` | `0`               | Délai avant le début de l'animation, en `ms`.                                 |
| `duration`       | `number` | `2000`            | Durée de l'animation, en `ms`.                                                |
| `text-end-color` | `string` | `inherit`         | Couleur du texte à la fin de l'animation. Respectez les recommandations WCAG. |

#credits
- Inspiré par [Aceternity UI](https://ui.aceternity.com/components/hero-highlight){rel=""nofollow""}
- Merci à [Nathan De Pachtere](https://nathandepachtere.com){rel=""nofollow""} pour le portage de ce composant.
::


# Effet de texte au survol

::component-viewer
---
component-files:
  - TextHoverEffect.vue
component-id: text-hover-effect
config: TextHoverEffectConfig
demo-file: TextHoverEffectDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                                |
| ---------------- | -------- | ----------------- | ---------------------------------------------------------- |
| `text`           | `string` | Requise           | Texte à afficher avec l'effet de survol.                   |
| `duration`       | `number` | `200`             | Durée de l'animation de transition du masque, en secondes. |
| `strokeWidth`    | `number` | `0.75`            | Largeur du contour du texte.                               |
| `opacity`        | `number` | `null`            | Opacité du texte.                                          |
::


# Révélation de texte

::component-viewer
---
component-files:
  - TextReveal.vue
component-id: text-reveal
config: TextRevealConfig
demo-file: TextRevealDemo.vue
dependencies: gsap
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                        |
| ---------------- | -------- | ----------------- | -------------------------------------------------- |
| `class`          | `string` | `-`               | Classes supplémentaires pour le conteneur interne. |
| `containerClass` | `string` | `-`               | Classes supplémentaires pour le conteneur externe. |
| `duration`       | `number` | `0.6`             | Durée de l'animation de révélation des lignes.     |
| `delay`          | `number` | `0.2`             | Délai initial avant le début de l'animation.       |
| `stagger`        | `number` | `0.1`             | Décalage de l'animation entre chaque ligne.        |

#credits
- Propulsé par [GSAP](https://gsap.com/){rel=""nofollow""} et [GSAP SplitText](https://gsap.com/docs/v3/Plugins/SplitText/){rel=""nofollow""}.
::


# Carte texte dévoilé

::component-viewer
---
component-files:
  - TextRevealCard.vue
  - TextRevealStars.vue
component-id: text-reveal-card
config: TextRevealCardConfig
demo-file: TextRevealCardDemo.vue
---
#api
## API

| Nom de propriété | Type     | Description                                                            |
| ---------------- | -------- | ---------------------------------------------------------------------- |
| class            | `String` | Classes supplémentaires à ajouter à la carte.                          |
| starsCount       | `Number` | Contrôle le nombre d'étoiles générées.                                 |
| starsClass       | `String` | Classes supplémentaires à ajouter aux étoiles flottant sur le contenu. |

| Nom du slot | Description                                                   |
| ----------- | ------------------------------------------------------------- |
| header      | `String`                                                      |
| text        | Texte affiché par défaut lorsque la carte n'est pas survolée. |
| revealText  | Texte révélé au survol de la carte.                           |

#credits
- Merci à [M Atif](https://github.com/atif0075){rel=""nofollow""} pour le portage de ce composant.
- Porté depuis [Text Reveal Card d'Aceternity UI](https://ui.aceternity.com/components/text-reveal-card){rel=""nofollow""}.
::


# Révélation au défilement

::component-viewer
---
component-files:
  - TextScrollReveal.vue
  - ScrollWord.vue
component-id: text-scroll-reveal
config: TextScrollRevealConfig
demo-file: TextScrollRevealDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                                              |
| ---------------- | -------- | ----------------- | ------------------------------------------------------------------------ |
| `text`           | `string` | N/A               | Texte à afficher et révéler mot par mot pendant le défilement.           |
| `class`          | `string` | `""`              | Classes CSS supplémentaires à appliquer pour personnaliser le composant. |

#credits
- Porté depuis [Magic UI Text Reveal](https://magicui.design/docs/components/text-reveal){rel=""nofollow""}.
::


# Texte machine à écrire

::component-viewer
---
component-files:
  - TypewriterText.vue
  - index.ts
component-id: typewriter-text
config: TypewriterTextConfig
demo-file: TypewriterTextDemo.vue
---
#api
## API

| Prop                      | Type                                             | Valeur par défaut         | Description                                              |
| ------------------------- | ------------------------------------------------ | ------------------------- | -------------------------------------------------------- |
| `text`                    | `string | string[]`                              | —                         | Texte ou séquence de textes à écrire.                    |
| `as`                      | `string`                                         | `"div"`                   | Élément HTML utilisé pour le texte racine.               |
| `speed`                   | `number`                                         | `50`                      | Délai entre les caractères écrits, en millisecondes.     |
| `initialDelay`            | `number`                                         | `0`                       | Délai avant le début de l’écriture, en millisecondes.    |
| `waitTime`                | `number`                                         | `2000`                    | Pause avant la suppression ou le texte suivant.          |
| `deleteSpeed`             | `number`                                         | `30`                      | Délai entre les caractères supprimés, en millisecondes.  |
| `loop`                    | `boolean`                                        | `true`                    | Revenir au premier texte après le dernier.               |
| `showCursor`              | `boolean`                                        | `true`                    | Afficher le curseur animé.                               |
| `hideCursorOnType`        | `boolean`                                        | `false`                   | Masquer le curseur pendant l’écriture ou la suppression. |
| `cursorChar`              | `string`                                         | `"|"`                     | Caractère utilisé comme curseur.                         |
| `cursorAnimationVariants` | `{ initial: VariantType; animate: VariantType }` | Voir la valeur par défaut | Variants Motion utilisés pour le clignotement.           |
| `cursorClass`             | `string`                                         | `"ml-1"`                  | Classes supplémentaires appliquées au curseur.           |
| `class`                   | `string`                                         | —                         | Classes supplémentaires fusionnées sur l’élément racine. |

#credits
- Porté depuis [Fancy Components Typewriter](https://fancycomponents.dev/docs/components/text/typewriter){rel=""nofollow""}.
::


# Texte souligné

::component-viewer
---
component-files:
  - UnderlineText.vue
  - index.ts
component-id: underline-text
config: UnderlineTextConfig
demo-file: UnderlineTextDemo.vue
---
#api
## API

| Nom de la prop          | Type                                                   | Valeur par défaut | Description                                            |
| ----------------------- | ------------------------------------------------------ | ----------------- | ------------------------------------------------------ |
| `as`                    | `string`                                               | `span`            | Élément HTML utilisé pour le texte.                    |
| `variant`               | `"center" | "comes-in-goes-out" | "goes-out-comes-in"` | `center`          | Style de l’animation du soulignement.                  |
| `direction`             | `"left" | "right"`                                     | `left`            | Direction des variantes latérales.                     |
| `transition`            | `Record<string, unknown>`                              | Voir le défaut    | Transition Motion du soulignement.                     |
| `underlineHeightRatio`  | `number`                                               | `0.1`             | Hauteur du soulignement relative à la taille du texte. |
| `underlinePaddingRatio` | `number`                                               | `0.01`            | Espace sous le texte relatif à sa taille.              |
| `class`                 | `string`                                               | —                 | Classes supplémentaires fusionnées sur le texte.       |

Utilisez le slot par défaut pour le contenu texte. Le composant utilise la couleur courante du texte pour le soulignement.

#credits
- Porté depuis [Fancy Components Underline Animation](https://fancycomponents.dev/docs/components/text/underline-animation){rel=""nofollow""}.
::


# Texte à lettres variables

::component-viewer
---
component-files:
  - VariableLetterText.vue
  - index.ts
component-id: variable-letter-text
config: VariableLetterTextConfig
demo-file: VariableLetterTextDemo.vue
---
#api
## API

| Prop                        | Type                                   | Valeur par défaut | Description                                       |
| --------------------------- | -------------------------------------- | ----------------- | ------------------------------------------------- |
| `label`                     | `string`                               | —                 | Texte séparé en lettres animées individuellement. |
| `fromFontVariationSettings` | `string`                               | `"'wght' 400"`    | Axes utilisés au repos.                           |
| `toFontVariationSettings`   | `string`                               | `"'wght' 900"`    | Axes appliqués au survol.                         |
| `transition`                | `Transition`                           | Transition spring | Transition Motion utilisée pour chaque lettre.    |
| `staggerDuration`           | `number`                               | `0.03`            | Délai entre le début de chaque animation.         |
| `staggerFrom`               | `"first" | "last" | "center" | number` | `"first"`         | Origine du calcul de l’ordre progressif.          |
| `class`                     | `string`                               | —                 | Classes supplémentaires fusionnées sur la racine. |

Utilisez une police variable et les axes qu’elle prend en charge. Roboto Flex accepte par exemple `wght` et `wdth`.

#credits
- Porté depuis [Fancy Components Variable Font Hover By Letter](https://fancycomponents.dev/docs/components/text/variable-font-hover-by-letter){rel=""nofollow""}.
::


# Texte variable

::component-viewer
---
component-files:
  - VariableText.vue
  - index.ts
component-id: variable-text
config: VariableTextConfig
demo-file: VariableTextDemo.vue
---
#api
## API

| Prop                        | Type                                    | Valeur par défaut | Description                                               |
| --------------------------- | --------------------------------------- | ----------------- | --------------------------------------------------------- |
| `label`                     | `string`                                | —                 | Texte séparé en lettres animées individuellement.         |
| `fromFontVariationSettings` | `string`                                | —                 | Réglages des axes au repos et hors du rayon de proximité. |
| `toFontVariationSettings`   | `string`                                | —                 | Réglages des axes au centre de l’effet de proximité.      |
| `containerRef`              | `MaybeComputedElementRef`               | —                 | Élément utilisé pour calculer la position du pointeur.    |
| `radius`                    | `number`                                | `50`              | Rayon en pixels dans lequel les lettres réagissent.       |
| `falloff`                   | `"linear" | "exponential" | "gaussian"` | `"linear"`        | Contrôle la diminution de l’effet avec la distance.       |
| `random`                    | `boolean`                               | `false`           | Anime les lettres dans un ordre aléatoire au survol.      |
| `transition`                | `Transition`                            | Transition spring | Transition Motion utilisée en mode aléatoire.             |
| `staggerDuration`           | `number`                                | `0.03`            | Délai entre les lettres en mode aléatoire.                |
| `as`                        | `string`                                | `"span"`          | Élément HTML utilisé pour le texte racine.                |
| `class`                     | `string`                                | —                 | Classes supplémentaires fusionnées sur l’élément racine.  |

#credits
- Porté depuis [Fancy Components Variable Font Cursor Proximity](https://fancycomponents.dev/docs/components/text/variable-font-cursor-proximity){rel=""nofollow""}.
- Le comportement aléatoire est basé sur [Fancy Components Variable Font Hover By Random Letter](https://fancycomponents.dev/docs/components/text/variable-font-hover-by-random-letter){rel=""nofollow""}.
::


# Galerie courbée

::component-viewer
---
component-files:
  - BendingGallery.vue
component-id: bending-gallery
config: BendingGalleryConfig
demo-file: BendingGalleryDemo.vue
dependencies: ogl
---
#api
## API

| Nom de propriété | Type                                | Valeur par défaut     | Description                                                                 |
| ---------------- | ----------------------------------- | --------------------- | --------------------------------------------------------------------------- |
| `items`          | `{ image: string; text: string }[]` | `[]`                  | Tableau d'objets contenant les URL d'image et le texte associé.             |
| `bend`           | `number`                            | `3`                   | Contrôle la courbure de la galerie. Une valeur plus haute courbe davantage. |
| `textColor`      | `string`                            | `"#ffffff"`           | Couleur du texte affiché sous chaque image.                                 |
| `borderRadius`   | `number`                            | `0.05`                | Rayon des coins des cartes (en espace UV).                                  |
| `font`           | `string`                            | `"bold 30px DM Sans"` | Police utilisée pour le texte sous chaque image.                            |

#credits
- Inspiré par [Infinite Circular Gallery de Codrops](https://tympanus.net/Tutorials/InfiniteCircularGallery/){rel=""nofollow""}.
::


# Carrousel 3D

::component-viewer
---
component-files:
  - Carousel3D.vue
component-id: carousel-3d
config: Carousel3dConfig
demo-file: Carousel3dDemo.vue
---
#api
## API

| Nom de propriété | Type        | Valeur par défaut | Description                                                |
| ---------------- | ----------- | ----------------- | ---------------------------------------------------------- |
| `items`          | `unknown[]` | `[]`              | Liste d'images ou d'éléments à afficher dans le carrousel. |
| `class`          | `string`    | `""`              | Classes CSS supplémentaires pour l'overlay du carrousel.   |
| `containerClass` | `string`    | `""`              | Classes CSS pour styliser le conteneur du carrousel.       |
| `width`          | `number`    | `450`             | Largeur des éléments individuels.                          |
| `height`         | `number`    | `600`             | Hauteur des éléments individuels.                          |

#credits
- Construit avec Three.js pour le rendu 3D.
- Utilise Motion-V pour des animations fluides.
- Merci à [@safakdinc](https://github.com/safakdinc){rel=""nofollow""} pour le partage de ce composant.
::


# Arborescence de fichiers

::component-viewer
---
component-files:
  - Tree.vue
  - Folder.vue
  - File.vue
  - TreeIndicator.vue
  - index.ts
component-id: file-tree
config: FileTreeConfig
demo-file: FileTreeDemo.vue
---
#api
## API

### `Tree`

Le composant `Tree` sert de conteneur pour afficher une structure hiérarchique de fichiers/dossiers.

#### Props

| Nom de propriété       | Type                | Valeur par défaut      | Description                                             |
| ---------------------- | ------------------- | ---------------------- | ------------------------------------------------------- |
| `class`                | `string`            | -                      | Classes supplémentaires pour styliser le conteneur.     |
| `initialSelectedId`    | `string`            | -                      | ID de l'élément sélectionné au chargement.              |
| `indicator`            | `boolean`           | `true`                 | Affiche ou non la ligne d'indicateur de l'arborescence. |
| `elements`             | `TreeViewElement[]` | -                      | Tableau des éléments de l'arbre à afficher.             |
| `initialExpandedItems` | `string[]`          | -                      | IDs des dossiers ouverts initialement.                  |
| `openIcon`             | `string`            | `"lucide:folder-open"` | Icône pour les dossiers ouverts.                        |
| `closeIcon`            | `string`            | `"lucide:folder"`      | Icône pour les dossiers fermés.                         |
| `fileIcon`             | `string`            | `"lucide:file"`        | Icône pour les fichiers.                                |
| `direction`            | `"rtl" | "ltr"`     | `"ltr"`                | Sens d'écriture de l'arborescence.                      |

### `Folder` et `File`

Les composants `Folder` et `File` représentent les dossiers et fichiers. Les dossiers peuvent contenir d'autres `Folder` et `File`.

#### Props

| Nom de propriété | Type      | Valeur par défaut | Description                                         |
| ---------------- | --------- | ----------------- | --------------------------------------------------- |
| `class`          | `string`  | -                 | Classes supplémentaires pour un style personnalisé. |
| `id`             | `string`  | -                 | Identifiant unique de l'élément.                    |
| `name`           | `string`  | -                 | Nom affiché du dossier/fichier.                     |
| `isSelectable`   | `boolean` | `true`            | Indique si l'élément peut être sélectionné.         |
| `isSelect`       | `boolean` | `false`           | Indique si l'élément est actuellement sélectionné.  |

#credits
- Inspiré par [Magic UI](https://magicui.design/docs/components/file-tree){rel=""nofollow""}.
- Merci à [kalix127](https://github.com/kalix127){rel=""nofollow""} pour le portage de ce composant.
::


# Globe Github

::component-viewer
---
component-files:
  - GithubGlobe.vue
component-id: github-globe
config: GithubGlobeConfig
demo-file: GithubGlobeDemo.vue
dependencies: three postprocessing three-globe
dev-dependencies: "@types/three"
---
#api
#### Télécharger le fichier GeoJSON

Téléchargez un fichier GeoJSON contenant les données géographiques du globe depuis [GeoJSON Maps](https://geojson-maps.kyd.au/){rel=""nofollow""} en personnalisant les continents et le niveau de détail. Enregistrez le fichier téléchargé sous le nom `globe.json` dans le même dossier que votre composant.

## API

| Nom de propriété | Type         | Valeur par défaut | Description                                                                                    |
| ---------------- | ------------ | ----------------- | ---------------------------------------------------------------------------------------------- |
| `globeConfig`    | `object`     | `{}`              | Options de configuration du globe : couleurs, atmosphère, vitesse de rotation, éclairage, etc. |
| `data`           | `Position[]` | `[]`              | Tableau de positions représentant arcs et points (latitude, longitude, couleur, etc.).         |
| `class`          | `string`     | `""`              | Classes CSS supplémentaires pour un style personnalisé.                                        |

### Propriétés `globeConfig`

| Propriété            | Type      | Valeur par défaut       | Description                                              |
| -------------------- | --------- | ----------------------- | -------------------------------------------------------- |
| `pointSize`          | `number`  | `1`                     | Taille des points sur le globe.                          |
| `globeColor`         | `string`  | `"#1d072e"`             | Couleur de la surface du globe.                          |
| `showAtmosphere`     | `boolean` | `true`                  | Affiche ou non l'atmosphère autour du globe.             |
| `atmosphereColor`    | `string`  | `"#ffffff"`             | Couleur de l'atmosphère.                                 |
| `atmosphereAltitude` | `number`  | `0.1`                   | Altitude de la couche atmosphérique.                     |
| `emissive`           | `string`  | `"#000000"`             | Couleur émissive du matériau du globe.                   |
| `emissiveIntensity`  | `number`  | `0.1`                   | Intensité de la couleur émissive.                        |
| `shininess`          | `number`  | `0.9`                   | Brillance du matériau du globe.                          |
| `polygonColor`       | `string`  | `rgba(255,255,255,0.7)` | Couleur des frontières des polygones sur le globe.       |
| `arcTime`            | `number`  | `2000`                  | Durée de l'animation des arcs.                           |
| `arcLength`          | `number`  | `0.9`                   | Longueur des arcs sur le globe.                          |
| `rings`              | `number`  | `1`                     | Nombre d'anneaux affichés par point.                     |
| `maxRings`           | `number`  | `3`                     | Nombre maximal d'anneaux autour de chaque point.         |
| `initialPosition`    | `object`  | `{ lat: 0, lng: 0 }`    | Latitude et longitude initiales du globe.                |
| `autoRotate`         | `boolean` | `false`                 | Active la rotation automatique du globe.                 |
| `autoRotateSpeed`    | `number`  | `0.8`                   | Vitesse de rotation automatique lorsqu'elle est activée. |

### Structure `data` (Position)

| Champ      | Type     | Description                                      |
| ---------- | -------- | ------------------------------------------------ |
| `order`    | `number` | Ordre du point ou de l'arc pour le séquencement. |
| `startLat` | `number` | Latitude de départ d'un arc.                     |
| `startLng` | `number` | Longitude de départ d'un arc.                    |
| `endLat`   | `number` | Latitude d'arrivée d'un arc.                     |
| `endLng`   | `number` | Longitude d'arrivée d'un arc.                    |
| `arcAlt`   | `number` | Altitude de l'arc (détermine sa hauteur).        |
| `color`    | `string` | Couleur de l'arc ou du point (hex ou RGB).       |

#credits
- Construit avec Three.js et Three Globe, conçu pour des visualisations globales et effets dynamiques.
- Porté depuis [Aceternity UI](https://ui.aceternity.com/components/github-globe){rel=""nofollow""}.
::


# Globe

::component-viewer
---
component-files:
  - Globe.vue
component-id: globe
config: GlobeConfig
demo-file: GlobeDemo.vue
dependencies: cobe vue-use-spring
---
#api
## API

| Nom de propriété | Type          | Valeur par défaut | Description                                                                                                                                              |
| ---------------- | ------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `class`          | `string`      | `""`              | Classes CSS supplémentaires pour un style personnalisé.                                                                                                  |
| `config`         | `COBEOptions` | N/A               | Objet de configuration du globe, suivant les options de la bibliothèque **[COBE]**(<https://cobe.vercel.app/docs/api>{rel=""nofollow""}). |
| `mass`           | `number`      | `1`               | Paramètre de masse pour l'animation à ressort contrôlant l'inertie de rotation.                                                                          |
| `tension`        | `number`      | `280`             | Tension du ressort pour l'animation, influence la réactivité.                                                                                            |
| `friction`       | `number`      | `100`             | Friction du ressort, influence l'amortissement.                                                                                                          |
| `precision`      | `number`      | `0.001`           | Précision pour les calculs de l'animation à ressort.                                                                                                     |

#credits
- Construit avec la bibliothèque [cobe](https://github.com/shuding/cobe){rel=""nofollow""} pour la visualisation WebGL du globe.
- Porté depuis [Magic UI](https://magicui.design/docs/components/globe){rel=""nofollow""}.
::


# Nuage d'icônes

::component-viewer
---
component-files:
  - IconCloud.vue
  - index.ts
component-id: icon-cloud
config: IconCloudConfig
demo-file: IconCloudDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                         |
| ---------------- | -------- | ----------------- | --------------------------------------------------- |
| `class`          | `string` | -                 | Classes supplémentaires pour styliser le composant. |
| `images`         | `array`  | `[]`              | Tableau d'URL d'images à rendre dans le nuage.      |

#credits
- Inspiré par [MagicUI](https://magicui.design/docs/components/icon-cloud){rel=""nofollow""}.
- Merci à [kalix127](https://github.com/kalix127){rel=""nofollow""} pour le portage de ce composant.
::


# Grille infinie

::component-viewer
---
component-files:
  - InfiniteGrid.vue
  - InfiniteGridClass.ts
  - DisposalManager.ts
  - EventHandler.ts
  - GridManager.ts
  - PostProcessShader.ts
  - createTexture.ts
  - shaders.ts
  - types.ts
component-id: infinite-grid
config: InfiniteGridConfig
demo-file: InfiniteGridDemo.vue
dependencies: ogl gsap
---
#api
## API

| Nom de propriété | Type                           | Valeur par défaut | Description                                                                                        |
| ---------------- | ------------------------------ | ----------------- | -------------------------------------------------------------------------------------------------- |
| `cardData`       | `CardData[]`                   | `[]`              | Données pour chaque tuile affichée dans la grille. **Requis**.                                     |
| `options`        | `Partial<InfiniteGridOptions>` | `{}`              | Surcharges facultatives pour le layout, la caméra et le post-traitement (voir tableau ci-dessous). |

### `InfiniteGridOptions`

| Option                                  | Type      | Valeur par défaut | Description                                                  |
| --------------------------------------- | --------- | ----------------- | ------------------------------------------------------------ |
| `gridCols`                              | `number`  | `4`               | Nombre de colonnes.                                          |
| `gridRows`                              | `number`  | `4`               | Nombre de lignes.                                            |
| `gridGap`                               | `number`  | `0`               | Espacement entre les cases.                                  |
| `tileSize`                              | `number`  | `2.4`             | Taille des tuiles (en unités OGL).                           |
| `baseCameraZ`                           | `number`  | `10`              | Distance Z initiale de la caméra.                            |
| `enablePostProcessing`                  | `boolean` | `true`            | Active la pipeline de post-traitement.                       |
| `postProcessParams.distortionIntensity` | `number`  | `-0.2`            | Intensité de distorsion barillet/coussin (0 = aucune).       |
| `postProcessParams.vignetteOffset`      | `number`  | `0.0`             | Offset du vignetage ; plus élevé ⇒ zone claire plus réduite. |
| `postProcessParams.vignetteDarkness`    | `number`  | `0.0`             | Obscurité du vignetage ; plus élevé ⇒ bords plus sombres.    |

---

### `CardData`

| Champ         | Type       | Obligatoire | Description                                |
| ------------- | ---------- | ----------- | ------------------------------------------ |
| `title`       | `string`   | ✓           | Titre principal.                           |
| `badge`       | `string`   | ✓           | Libellé du badge (rendu personnalisable).  |
| `description` | `string`   | –           | Texte descriptif.                          |
| `tags`        | `string[]` | ✓           | Tags affichés en bas.                      |
| `date`        | `string`   | ✓           | Date affichée en bas à droite.             |
| `image`       | `string`   | –           | URL de l'image d'arrière-plan de la tuile. |

---

## Événements émis

| Nom de l'événement | Charge utile                        | Description                                                                                                              |
| ------------------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `tileClicked`      | `{ card: CardData, index: number }` | Déclenché lorsqu'une tuile est cliquée/appuyée. La charge contient l'objet `CardData` cliqué et son `index` (base zéro). |
| `onTileLoaded`     | -                                   | Déclenché lorsque toutes les images d'une tuile sont chargées.                                                           |

#credits
- Inspiré par [Phantom Land](https://phantom.land){rel=""nofollow""}
- Un grand merci à [Safak Dinc](https://github.com/safakdinc){rel=""nofollow""} pour l'idée et l'autorisation de l'inclure ici. Le dépôt original est [infinite-grid](https://github.com/safakdinc/infinite-grid){rel=""nofollow""}. Votre contribution est très appréciée !
- Merci à [kalix127](https://github.com/kalix127){rel=""nofollow""} pour le portage de ce composant.
::


# Vitesse lumière

::component-viewer
---
component-files:
  - LightSpeed.vue
  - LightSpeedApp.ts
  - presets.ts
  - shaders.ts
component-id: light-speed
config: LightSpeedConfig
demo-file: LightSpeedDemo.vue
dependencies: three postprocessing
---
#api
## API

| Nom de propriété | Type                         | Valeur par défaut     | Description                                                                                                  |
| ---------------- | ---------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------ |
| `effectOptions`  | `Partial<LightSpeedOptions>` | Voir `defaultOptions` | Objet de configuration pour personnaliser la route, les lumières, la distorsion, la vitesse et les couleurs. |

#credits
- Porté vers Vue depuis [l'article Codrops](https://tympanus.net/codrops/2019/11/13/high-speed-light-trails-in-three-js/){rel=""nofollow""}
::


# Effet verre liquide

::component-viewer
---
component-files:
  - LiquidGlass.vue
component-id: liquid-glass
config: LiquidGlassConfig
demo-file: LiquidGlassDemo.vue
---
#api
## API

| Nom de propriété | Type              | Valeur par défaut | Description                                                                               |
| ---------------- | ----------------- | ----------------- | ----------------------------------------------------------------------------------------- |
| `radius`         | `number`          | `16`              | Rayon des coins du conteneur en verre (en pixels).                                        |
| `border`         | `number`          | `0.07`            | Épaisseur relative de la bordure influençant la marge interne du filtre de déplacement.   |
| `lightness`      | `number`          | `50`              | Luminosité (0-100) de la couleur de superposition en HSL.                                 |
| `blend`          | `string`          | `"difference"`    | Mode de fusion CSS entre les couches de déplacement rouges et bleues pour la distorsion.  |
| `xChannel`       | `"R" | "G" | "B"` | `"R"`             | Canal de l'image de déplacement utilisé pour le décalage horizontal.                      |
| `yChannel`       | `"R" | "G" | "B"` | `"B"`             | Canal de l'image de déplacement utilisé pour le décalage vertical.                        |
| `alpha`          | `number`          | `0.93`            | Transparence alpha de la couleur de superposition (0-1).                                  |
| `blur`           | `number`          | `11`              | Rayon de flou gaussien appliqué à la superposition.                                       |
| `rOffset`        | `number`          | `0`               | Décalage d'échelle supplémentaire pour la carte de déplacement rouge.                     |
| `gOffset`        | `number`          | `10`              | Décalage d'échelle supplémentaire pour la carte de déplacement verte.                     |
| `bOffset`        | `number`          | `20`              | Décalage d'échelle supplémentaire pour la carte de déplacement bleue.                     |
| `scale`          | `number`          | `-180`            | Facteur d'échelle de base pour les effets de déplacement, combiné aux décalages de canal. |
| `frost`          | `number`          | `0.05`            | Facteur d'opacité contrôlant la force de l'arrière-plan givré.                            |
| `class`          | `string`          | `""`              | Classes CSS supplémentaires appliquées au slot interne qui enveloppe le contenu.          |
| `containerClass` | `string`          | `""`              | Classes CSS supplémentaires appliquées à la div conteneur externe.                        |

#credits
- Inspiré par Apple Liquid Glass.
::

::warning
Ce composant utilise des filtres SVG pour le flou d'arrière-plan. Ceux-ci ne sont pas pris en charge par Safari et sont très limités sur Firefox.

Il est recommandé d'utiliser ce composant uniquement si vous ciblez des navigateurs basés sur Chromium, et de prévoir un fallback si l'utilisateur est sur Safari ou Firefox.

Par exemple, la page d'accueil d'Inspira UI utilise le composant Liquid Glass sur les navigateurs Chromium, mais bascule vers un effet de verre dépoli sur Safari et Mozilla.
::


# Logo liquide

::component-viewer
---
component-files:
  - LiquidLogo.vue
  - parseLogoImage.ts
  - shader.ts
component-id: liquid-logo
config: LiquidLogoConfig
demo-file: LiquidLogoDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                             |
| ---------------- | -------- | ----------------- | ------------------------------------------------------- |
| `class`          | `string` | `""`              | Classes CSS supplémentaires pour un style personnalisé. |
| `imageUrl`       | `string` | `""`              | URL de l'image sur laquelle appliquer l'effet liquide.  |
| `patternScale`   | `number` | `2`               | Échelle du motif de distorsion.                         |
| `refraction`     | `number` | `0.015`           | Niveau de réfraction appliqué à l'image.                |
| `edge`           | `number` | `0.4`             | Netteté de l'effet de bord.                             |
| `patternBlur`    | `number` | `0.005`           | Flou appliqué au motif.                                 |
| `liquid`         | `number` | `0.07`            | Intensité de l'animation liquide.                       |
| `speed`          | `number` | `0.3`             | Vitesse d'animation de l'effet liquide.                 |

#credits
- Inspiré par le design Fluid Motion d'Apple.
- Porté et amélioré depuis [Paper Design Concept](https://github.com/paper-design/liquid-logo){rel=""nofollow""}.
::


# Nuage de logos animé

::component-viewer
---
component-files:
  - AnimatedLogoCloud.vue
  - IconLogoCloud.vue
  - StaticLogoCloud.vue
  - index.ts
component-id: logo-cloud
config: IconLogoCloudConfig
demo-file: IconLogoCloudDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut           | Description                                                        |
| ---------------- | -------- | --------------------------- | ------------------------------------------------------------------ |
| `class`          | `string` | `-`                         | Délai en millisecondes avant l'ajout de chaque élément à la liste. |
| `title`          | `string` | `Trusted by Companies like` | Titre du nuage animé.                                              |
| `logos`          | `[]`     | `[{name: "", path: ""}]`    | Tableau d'éléments (logos) avec les champs `name` et `path`.       |

#credits
- Merci à [SivaReddy Uppathi](https://github.com/sivareddyuppathi){rel=""nofollow""} pour ce composant.
::


# Logo origami

::component-viewer
---
component-files:
  - LogoOrigami.vue
  - LogoOrigamiItem.vue
component-id: logo-origami
config: LogoOrigamiConfig
demo-file: LogoOrigamiDemo.vue
---
#api
## API

| Nom de propriété | Type     | Valeur par défaut | Description                                             |
| ---------------- | -------- | ----------------- | ------------------------------------------------------- |
| `class`          | `string` | `""`              | Classes CSS supplémentaires pour un style personnalisé. |
| `duration`       | `number` | `1.5`             | Durée de l'animation de flip, en secondes.              |
| `delay`          | `number` | `2.5`             | Délai entre chaque animation de flip, en secondes.      |

#credits
- Inspiré par les animations origami et effets de flip sur [hover.dev](https://www.hover.dev/components/other#logo-origami){rel=""nofollow""}
::


# Orbite

::component-viewer
---
component-files:
  - Orbit.vue
  - index.ts
component-id: orbit
config: OrbitConfig
demo-file: OrbitDemo.vue
---
#api
## API

| Nom de propriété | Type                  | Valeur par défaut | Description                                                           |
| ---------------- | --------------------- | ----------------- | --------------------------------------------------------------------- |
| `direction`      | `normal` \| `reverse` | `normal`          | Sens de l'orbite. Vous pouvez utiliser la constante ORBIT\_DIRECTION. |
| `duration`       | `?number`             | `20`              | Durée de l'animation d'orbite en secondes.                            |
| `delay`          | `?number`             | `10`              | Délai avant le début de l'animation, en secondes.                     |
| `radius`         | `?number`             | `50`              | Rayon du parcours orbital, en pixels.                                 |
| `path`           | `?boolean`            | `false`           | Affiche un cercle de trajectoire si `true`.                           |

#credits
- Inspiré par [Magic UI](https://magicui.design/docs/components/orbiting-circles){rel=""nofollow""}.
- Merci à [Nathan De Pachtere](https://nathandepachtere.com/){rel=""nofollow""} pour la mise à jour de ce composant.
::


# Spline

::component-viewer
---
component-files:
  - Spline.vue
  - ParentSize.vue
component-id: spline
config: SplineConfig
demo-file: SplineDemo.vue
dependencies: "@splinetool/runtime"
---
#api
## API

| Nom de propriété | Type       | Valeur par défaut | Description                                                         |
| ---------------- | ---------- | ----------------- | ------------------------------------------------------------------- |
| `scene`          | `string`   | —                 | URL ou chemin du fichier de scène Spline. **Requis**.               |
| `onLoad`         | `Function` | `undefined`       | Callback déclenché lorsque la scène Spline est chargée avec succès. |
| `renderOnDemand` | `boolean`  | `true`            | Active ou désactive l'optimisation de rendu à la demande de Spline. |
| `style`          | `object`   | `{}`              | Styles CSS personnalisés appliqués au conteneur du canvas.          |

**Événements émis**

| Nom de l'événement   | Charge utile | Description                                                     |
| -------------------- | ------------ | --------------------------------------------------------------- |
| `error`              | `Error`      | Émis s'il y a une erreur lors du chargement de la scène Spline. |
| `spline-mouse-down`  | `any`        | Émis lorsqu'un événement mouseDown est détecté dans la scène.   |
| `spline-mouse-up`    | `any`        | Émis lorsqu'un événement mouseUp est détecté.                   |
| `spline-mouse-hover` | `any`        | Émis lorsque l'événement mouseHover est déclenché.              |
| `spline-key-down`    | `any`        | Émis lors d'un keyDown dans la scène Spline.                    |
| `spline-key-up`      | `any`        | Émis lors d'un keyUp dans la scène.                             |
| `spline-start`       | `any`        | Émis lorsque la scène Spline démarre.                           |
| `spline-look-at`     | `any`        | Émis lorsqu'un événement lookAt se produit.                     |
| `spline-follow`      | `any`        | Émis lorsqu'un événement follow se produit.                     |
| `spline-scroll`      | `any`        | Émis lors des interactions de défilement.                       |

#credits
- Utilise le runtime de Spline en coulisse.
- Inspiré par diverses expériences web 3D réalisées avec Spline.
::


# Carte du monde

::component-viewer
---
component-files:
  - WorldMap.vue
component-id: world-map
config: WorldMapConfig
demo-file: WorldMapDemo.vue
dependencies: dotted-map
---
#api
## API

| Nom de propriété | Type                                                                                                                | Valeur par défaut | Description                                                                          |
| ---------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------ |
| `dots`           | `Array<{ start: { lat: number; lng: number; label?: string }, end: { lat: number; lng: number; label?: string } }>` | `[]`              | Tableau d'objets contenant coordonnées de départ et d'arrivée (latitude, longitude). |
| `class`          | `string`                                                                                                            | `""`              | Classes CSS supplémentaires pour un style personnalisé.                              |
| `lineColor`      | `string`                                                                                                            | `"#0EA5E9"`       | Couleur des arcs et des bordures des points.                                         |
| `mapColor`       | `string`                                                                                                            | —                 | Couleur principale de la carte en points. (**Requise**)                              |
| `mapBgColor`     | `string`                                                                                                            | —                 | Couleur de fond de la carte. (**Requise**)                                           |

#credits
- Porté depuis (World Map by Aceternity UI) [<https://ui.aceternity.com/components/world-map>{rel=""nofollow""}].
::




# Journal des modifications

:inspira-changelog