# Kinetic Text Reveal

> A kinetic text reveal that segments text into words, characters, or lines and animates each into place with configurable direction, stagger, and blur.

<demo-kinetic-text-reveal>



</demo-kinetic-text-reveal>

## Installation

```bash
npx shadcn-vue@latest add "https://nxui.geoql.in/r/kinetic-text-reveal.json"
```

## Usage

```vue
<script setup lang="ts">
  import KineticTextReveal from '~/components/ui/kinetic-text-reveal/KineticTextReveal.vue';
</script>

<template>
  <KineticTextReveal
    text="Animate every word"
    split-by="words"
    direction="up"
    :stagger="0.08"
    :distance="20"
    :blur="true"
    class="text-3xl font-bold text-foreground"
  />
</template>
```

## Props

<table>
<thead>
  <tr>
    <th>
      Prop
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        text
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      The text content to animate
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        split-by
      </code>
    </td>
    
    <td>
      <code>
        'words' | 'characters' | 'lines'
      </code>
    </td>
    
    <td>
      <code>
        'words'
      </code>
    </td>
    
    <td>
      How to segment the text before animating
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        direction
      </code>
    </td>
    
    <td>
      <code>
        'up' | 'down' | 'left' | 'right'
      </code>
    </td>
    
    <td>
      <code>
        'up'
      </code>
    </td>
    
    <td>
      Direction the segments enter from
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        distance
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        20
      </code>
    </td>
    
    <td>
      Distance each segment travels in pixels
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        stagger
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        0.075
      </code>
    </td>
    
    <td>
      Delay between segment animations in seconds
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        stagger-from
      </code>
    </td>
    
    <td>
      <code>
        'start' | 'end' | 'center' | 'edges' | 'random' | number
      </code>
    </td>
    
    <td>
      <code>
        'start'
      </code>
    </td>
    
    <td>
      Origin point used to calculate stagger delay
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        transition
      </code>
    </td>
    
    <td>
      <code>
        Transition
      </code>
    </td>
    
    <td>
      <code>
        { duration: 0.72, ease: [0.22, 1, 0.36, 1] }
      </code>
    </td>
    
    <td>
      Animation transition configuration
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blur
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Whether segments animate from a blurred state
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        auto-play
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Whether the reveal plays automatically on mount
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        delay
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        0
      </code>
    </td>
    
    <td>
      Delay before autoplay in seconds
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        class
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      Additional CSS classes for the root element
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        segment-class
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      Additional CSS classes for each animated segment
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mask-class
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      Additional CSS classes for each segment mask wrapper
    </td>
  </tr>
</tbody>
</table>

## Events

<table>
<thead>
  <tr>
    <th>
      Event
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        reveal-start
      </code>
    </td>
    
    <td>
      Emitted when the reveal animation begins
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reveal-complete
      </code>
    </td>
    
    <td>
      Emitted when the last segment finishes animating
    </td>
  </tr>
</tbody>
</table>

## Methods

Expose `play()` and `reset()` via a template ref to replay or clear the animation.

```vue
<script setup lang="ts">
  import { ref } from 'vue';
  import KineticTextReveal from '~/components/ui/KineticTextReveal/KineticTextReveal.vue';
  import type { KineticTextRevealRef } from '~/components/ui/KineticTextReveal/KineticTextReveal.vue';

  const reveal = ref<KineticTextRevealRef | null>(null);
</script>

<template>
  <KineticTextReveal ref="reveal" text="Replay me" />
  <button @click="reveal?.play()">Replay</button>
</template>
```