# Text Animate

`{% textAnimate %}` animates a run of text — revealing it (or looping it)
with an effect, broken up by character, word, or line. Reach for it on a hero headline, a
tagline, or anywhere a little motion earns its keep.

> **A Community Component** — wraps [TextAnimate](https://gfazioli.github.io/mantine-text-animate/)
> by **gfazioli**, **MIT** licensed, npm `@gfazioli/mantine-text-animate`.

Use it as `{% textAnimate %}` in Markdown, or call it from Python logic
(loops, snippets) via `component('aardvark', 'textAnimate', …)`. The text is the block body or
the plain-text `text` param.

## Demonstrations

### Basic reveal

`animate='in'` reveals the text once; `animation` picks the effect (fade, blur, scale, slideUp,
slideDown, slideLeft, slideRight, …); `by` sets the granularity (text, word, character, line).

Documentation that moves with you

<br>

Source: Markdown

```aardvark
{% textAnimate animate='in' animation='fade' by='word' %}
Documentation that moves with you
{% endTextAnimate %}
```


Source: Python

```python
component('aardvark', 'textAnimate',
          animate='in', animation='fade', by='word',
          children='Documentation that moves with you')
```



### Looping animation

`animate='loop'` runs the effect continuously; `loopDelay` (ms) is the pause between cycles.
Per-character blur makes a nice attention-getter.

Always shipping

<br>

Source: Markdown

```aardvark
{% textAnimate animate='loop' animation='blur' by='character' loopDelay=1200 %}
Always shipping
{% endTextAnimate %}
```



### Trigger on scroll

`trigger='inView'` holds the animation until the text scrolls into the viewport, so the reveal
plays as the reader reaches it. `duration` and `delay` (seconds) tune the timing.

This line slides up the moment it enters the viewport.

<br>

Source: Markdown

```aardvark
{% textAnimate animate='in' animation='slideUp' by='line' trigger='inView' duration=0.6 %}
This line slides up the moment it enters the viewport.
{% endTextAnimate %}
```



## With other components

Drop an animated headline inside a [Paper](/components/layout/paper/) surface to build a hero
card — the animation runs on the text while the surface stays put.




Build. Document. Ship.




<br>

Source: Markdown

```aardvark
{% paper withBorder=true p='xl' radius='md' %}
{% textAnimate animate='in' animation='scale' by='word' %}
Build. Document. Ship.
{% endTextAnimate %}
{% endPaper %}
```



## Attributes

Omit any attribute to take its default.

| Attribute | Valid values | Description |
| --- | --- | --- |
| `animate` | `in` / `out` / `loop` / `static` / `none` | Animation mode. `in` reveals once, `loop` runs continuously, `static` shows the text without motion. |
| `animation` | `fade` / `blur` / `scale` / `slideUp` / `slideDown` / `slideLeft` / `slideRight` (plus `*Elastic`, `blurUp`, `blurDown`) | The effect applied to each segment. |
| `by` | `text` / `word` / `character` / `line` | Granularity the text is split into for the animation. |
| `duration` | Number (seconds) | Length of the animation. |
| `delay` | Number (seconds) | Delay before the animation starts. |
| `segmentDelay` | Number (seconds) | Stagger between consecutive segments. |
| `loopDelay` | Integer (ms) | Pause between loop cycles (`animate='loop'`). |
| `trigger` | `inView` | Start when the text scrolls into view, instead of immediately. |
| `text` | string | Plain-text alternative to the block body (HTML-escaped). The block body wins when both are set. |
| `attr={…}` | An object of HTML attributes | Forwards raw HTML attributes onto the rendered element (see [Injecting Attributes](#injecting-attributes)). |

## CSS Selector

The mounted island is wrapped in an element carrying `data-aardvark-island="TextAnimate"`, so
you can target it from your own CSS:

```css
[data-aardvark-island='TextAnimate'] {
  font-size: 1.5rem;
}
```

The package drives the animation through its own data-attribute selectors
(`[data-text-animate]`, `[data-text-animate-animation]`, `[data-animating]`, …) and CSS
variables; the stylesheet ships from `@gfazioli/mantine-text-animate/styles.css`, imported
automatically by the island.

## Injecting Attributes

Pass `attr={…}` to forward raw HTML attributes onto the rendered element — useful for `id`,
`data-*` hooks, ARIA, or analytics attributes that aren't component props:

Tagged headline

<br>

Source: Markdown

```aardvark
{% textAnimate animate='in' animation='fade' by='word' attr={'id': 'hero-headline', 'data-role': 'headline'} %}
Tagged headline
{% endTextAnimate %}
```


Source: Python

```python
component('aardvark', 'textAnimate',
          animate='in', animation='fade', by='word',
          attr={'id': 'hero-headline', 'data-role': 'headline'},
          children='Tagged headline')
```