# astro-reveal

> Scroll reveal animations for Astro. Two engines, one API. Zero runtime JS by default.

## What it is

`astro-reveal` is an Astro integration that adds scroll-triggered reveal animations to any Astro project. It has two engines that share the same API:

- **Purist** (`mode: "scroll"`, default): Uses native CSS `animation-timeline: view()`. Ships **zero JavaScript** to the client. Animations scrub with the scroll position (reverse on scroll-up). Requires modern browser support.
- **Observer** (`mode: "observer"`): Uses IntersectionObserver. ~0.6 KB gzipped runtime. Plays once and stays. Full browser support.
- **Auto** (`mode: "auto"`): Uses native where supported, falls back to observer where it isn't.

The mode is a **global config per build** — you cannot mix engines on the same site.

## Installation

```sh
npm install astro-reveal
```

```ts
// astro.config.ts
import { defineConfig } from "astro/config";
import reveal from "astro-reveal";

export default defineConfig({
  integrations: [reveal()],           // default: purist (zero JS)
  // integrations: [reveal({ mode: "observer" })],
  // integrations: [reveal({ mode: "auto" })],
});
```

No CSS import needed — the integration injects everything automatically.

## API

### Component

```astro
---
import Reveal from "astro-reveal/Reveal.astro";
---

<Reveal animation="up">
  <p>Animates on scroll.</p>
</Reveal>

<!-- With options -->
<Reveal animation="fade" distance="3rem" duration="600ms" index={2}>
  <Card />
</Reveal>
```

**Props:**
- `animation` — `"up"` | `"down"` | `"left"` | `"right"` | `"fade"` | `"scale"` | `"blur"` (default: `"up"`)
- `distance` — travel distance for directional animations, e.g. `"2rem"` (CSS length)
- `index` — stagger position within a group (0, 1, 2…)
- `duration` — transition duration in observer mode, e.g. `"500ms"`
- `as` — HTML tag to render (default: `"div"`)

### Raw attribute

Works on any HTML element, including output from React, Vue, Svelte, or plain HTML:

```html
<div data-reveal="fade">
  <!-- any content -->
</div>

<article data-reveal="up">...</article>
```

The `data-reveal` value is the animation name. Both the component and the attribute are equivalent — the component just sets the attribute and inline CSS vars for you.

## Animation names

The name is the **direction the element travels as it appears** (AOS convention):
- `up` — starts below, rises into place
- `down` — starts above, descends into place
- `left` — starts to the right, slides left into place
- `right` — starts to the left, slides right into place
- `fade` — opacity only, no movement
- `scale` — grows from slightly smaller
- `blur` — sharpens into focus

## CSS custom properties

Fine-tune per element via inline `style` on the **same element** that has `data-reveal` (not a parent):

```html
<div
  data-reveal="up"
  style="--reveal-distance: 3rem; --reveal-stagger: 120ms;"
>
  content
</div>
```

| Variable | Default | Description |
|---|---|---|
| `--reveal-distance` | `1.5rem` | Travel distance (directional animations) |
| `--reveal-scale` | `0.94` | Starting scale (scale animation) |
| `--reveal-blur` | `8px` | Starting blur (blur animation) |
| `--reveal-duration` | `700ms` | Duration (observer mode) |
| `--reveal-easing` | `cubic-bezier(0.16,1,0.3,1)` | Easing function |
| `--reveal-index` | `0` | Stagger position (set via `index` prop) |
| `--reveal-stagger` | `90ms` | Delay per stagger step |

**Important:** CSS vars must be set on the same element as `data-reveal`. astro-reveal declares defaults directly on `[data-reveal]`, so a value on a parent/ancestor is shadowed and has no effect.

## Stagger

Pass an incrementing `index` to create a cascade effect:

```astro
{items.map((item, i) => (
  <Reveal animation="up" index={i}>
    <Card {...item} />
  </Reveal>
))}
```

## Best practices

- Animate **sections and blocks** (hero, cards, features), not every paragraph of body text.
- The `"scroll"` (purist) mode **reverses** as you scroll back up — this is intentional, not a bug.
- If you need "appear once and stay", use `mode: "observer"`.
- Accessibility is built-in: `prefers-reduced-motion` is respected at the CSS level — content is always visible regardless.
- Do not re-implement animations by hand; use the package's API.

## Links

- npm: https://www.npmjs.com/package/astro-reveal
- GitHub: https://github.com/NicoPicotto/astro-reveal
- README / full docs: https://github.com/NicoPicotto/astro-reveal#readme
- Live demo (scroll / purist mode): https://astro-reveal.dev
- Live demo (observer mode): https://astro-reveal.dev/observer
- Interactive playground: https://astro-reveal.dev/playground
- Changelog: https://github.com/NicoPicotto/astro-reveal/releases

## Author

Nicolás Picotto — https://github.com/NicoPicotto

## License

MIT