@awesome-reveal/vue

@awesome-reveal/vue

Reveal-on-scroll animations for Vue. Wrap content in <Reveal>, or add v-reveal to an element, and it fades and slides in when it enters the viewport.

Release candidate: This is a release candidate of version 1.0. The API is frozen, so only fixes go in before the stable release. Tell us what works and what does not in GitHub Discussions.

• Simple. Two components, two directives, and a few options.
• Native. Built on IntersectionObserver and the Web Animations API, with no animation library.
• SSR-ready. Server-rendered content stays hidden until it reveals, with no flash.
• Accessible. Obeys the reduced-motion preference, and shows waiting content on focus and in print.
• CSP-friendly. Writes no inline styles and no inline scripts.

Works with Vue 3.5 and later.

Install

npm install @awesome-reveal/vue

The package loads its stylesheet automatically. Only an Astro island needs a step.

Quick start

<script setup lang="ts">
import { Reveal, vReveal } from "@awesome-reveal/vue";
</script>

<template>
  <Reveal><h1>Hello</h1></Reveal>
  <p v-reveal>No wrapper element</p>
</template>

The content fades in and moves up one time, when it enters the viewport.

Usage

Reveal and v-reveal accept the same options. Reveal renders a div around its slot, and as changes the tag. v-reveal animates an element that you already render.

Choose the entrance

from sets where the element starts. A side gives a fade and a 24 px movement. The default is "bottom".

<template>
  <Reveal from="left">From the left</Reveal>
  <p v-reveal="{ from: 'right' }">From the right</p>
</template>

For a different entrance, give a start state. The element animates from this state to neutral values: full opacity, no offset, a scale of 1, no rotation and no blur. The element's own value of an animated property applies only after the entrance ends. A start state replaces the default, so add opacity: 0 if you want a fade.

<template>
  <Reveal :from="{ opacity: 0 }">Fade only</Reveal>
  <Reveal :from="{ scale: 0.9 }">Scale only</Reveal>
  <Reveal :from="{ opacity: 0, x: '-100%', rotate: '-5deg', blur: 8 }">All together</Reveal>
</template>

A start state has the properties opacity, x, y, scale, rotate and blur. A number for x, y or blur is in pixels, and a number for rotate is in degrees. A string can contain a CSS value with its unit.

Use your own keyframes

For full control, such as a custom easing, give native keyframes instead of from. End them at the resting style of the element.

<template>
  <Reveal
    :keyframes="[
      { opacity: 0, transform: 'scale(.8)', easing: 'cubic-bezier(.34,1.56,.64,1)' },
      { opacity: 1, transform: 'scale(1)' },
    ]"
  >
    Bounce in
  </Reveal>
</template>

Change the timing

<template>
  <Reveal as="h2" from="left" :duration="800">Title</Reveal>
  <Reveal :from="{ opacity: 0 }" :delay="200">Starts after the title</Reveal>
  <Reveal :threshold="0.5">Reveals when half of it is visible</Reveal>
</template>

Keep delay below about 300 ms. A long delay makes content appear late when the user scrolls quickly.

Reveal a list

Cascade and v-cascade reveal the direct children one after the other, when the container enters the viewport. interval sets the time between two children, and the default is 80 ms.

<script setup lang="ts">
import { Cascade, vCascade } from "@awesome-reveal/vue";
</script>

<template>
  <Cascade as="ul" from="left" :interval="120">
    <li>Fast</li>
    <li>Small</li>
  </Cascade>
  <ol v-cascade>
    <li>Install</li>
    <li>Import</li>
  </ol>
</template>

For a long list, a virtualized list, or a grid that is taller than the viewport, use Reveal or v-reveal on each item instead. A cascade schedules all children at the same time, so the last children start late or out of view.

Control the reveal

when controls the entrance from your state. true plays it, and false resets it with no exit animation. With null or no value, the viewport controls it. A change from true to null keeps the element revealed.

when does not show or hide content. With when: false, the element is transparent, but screen readers read it and the keyboard can focus it. inert does not hide content: it only blocks focus, clicks and assistive technology. To hide content, also set hidden, or use v-if:

<script setup lang="ts">
import { ref } from "vue";
import { Reveal } from "@awesome-reveal/vue";

const open = ref(false);
</script>

<template>
  <button :aria-expanded="open" @click="open = !open">Toggle</button>
  <Reveal :when="open" :hidden="!open" :from="{ opacity: 0 }">Details</Reveal>
</template>

To play the entrance again, set when to false, then to true.

Run code at the reveal

Reveal emits reveal with the element when the reveal starts, and gives revealed to its default slot. v-reveal accepts an onReveal option. To wait for the end of the entrance, wait for the finished promises of the animations:

<script setup lang="ts">
import { Reveal } from "@awesome-reveal/vue";

function entered(element: Element) {
  Promise.all(element.getAnimations().map((animation) => animation.finished))
    .then(() => element.classList.add("entered"))
    .catch(() => {});
}
</script>

<template>
  <Reveal v-slot="{ revealed }" @reveal="entered">
    {{ revealed ? "Hello" : "Waiting" }}
  </Reveal>
</template>

The promise rejects when the entrance stops early, for example after when: false or an unmount. Catch the rejection. It resolves at once when no entrance plays, for example with reduced motion. It also waits for your own animations of the element. For a cascade, use getAnimations({ subtree: true }), because the children animate. An animation that repeats forever never finishes, so the promise does not resolve.

API

<Reveal>, <Cascade>, v-reveal and v-cascade

The components emit reveal with the element, give revealed to the default slot, and pass the other attributes to the rendered element.

Behavior

• The entrance plays one time. The observation stops at the reveal.
• The reveal event and onReveal also run when no entrance plays, for example with reduced motion or focus. After when: false, the next reveal runs them again.
• A change to when or threshold applies immediately. A change to the other options applies at the next reveal.
• when: false during the delay resets the entrance, and the entrance does not play.

Stylesheet setup

The package stylesheet hides server-rendered content until it reveals. The package modules import it, and your bundler adds it to the page. An Astro island needs a step: Astro does not get the CSS of an island, so import it in the page or in the layout.

---
import "@awesome-reveal/vue/reveal.css";
---

Server-side rendering

The server markup is hidden until the element reveals. If the script fails, the content shows after 5 seconds. Hydrate reveal content eagerly: with lazy hydration, such as hydrateOnVisible() or a Nuxt hydrate-on-visible component, the content can show, then hide again until it reveals.

Accessibility

• With prefers-reduced-motion: reduce, all the content shows immediately, with no animation. Reduced motion has priority over the entrance and over when: false, so the reveal event and onReveal do not run again.
• Focus in a waiting element shows it at once, so a keyboard user does not focus invisible content. This does not apply with when: false.
• Focus during the delay or the entrance finishes the entrance at once.
• Before the script loads, server markup shows while it has focus.
• Waiting content shows in print and when JavaScript is off.
• Hidden content stays in the accessibility tree. Do not make important content depend on decorative motion.

Good to know

Agent skills

The package includes the adding-reveal-animations skill, which teaches a coding agent this API. pnpm can link it into your project after you approve it.

License

MIT