Skip to content

Staggered list animations with Cascade

A cascade reveals the children of a container one after the other, when the container enters the viewport. Each package has a cascade API:

  • React: Cascade and useCascade.
  • Vue: Cascade and v-cascade.
  • Astro: Cascade.
  • JavaScript: cascade().

The cascade APIs accept all the options of a reveal, and also interval.

Put the items in a cascade. Select an interval to see the effect:

interval

Your device asks for reduced motion, so the content shows with no animation.

import { Cascade } from "@awesome-reveal/react";
export function CardList({ cards }) {
return (
<Cascade as="ul" className="cards" interval={0}>
{cards.map((card) => (
<li key={card.id}>{card.title}</li>
))}
</Cascade>
);
}
import { Cascade } from "@awesome-reveal/react";
export function CardList({ cards }) {
return (
<Cascade as="ul" className="cards" interval={80}>
{cards.map((card) => (
<li key={card.id}>{card.title}</li>
))}
</Cascade>
);
}
import { Cascade } from "@awesome-reveal/react";
export function CardList({ cards }) {
return (
<Cascade as="ul" className="cards" interval={160}>
{cards.map((card) => (
<li key={card.id}>{card.title}</li>
))}
</Cascade>
);
}
import { Cascade } from "@awesome-reveal/react";
export function CardList({ cards }) {
return (
<Cascade as="ul" className="cards" interval={320}>
{cards.map((card) => (
<li key={card.id}>{card.title}</li>
))}
</Cascade>
);
}

Only the direct element children animate. Text and deeper descendants do not animate. In React, Vue and Astro, a child with display: contents shows immediately.

interval sets the time between the entrances of two children, in milliseconds. The default is 80. The child at position index waits delay + index * interval. So delay moves the start of the whole sequence.

A negative interval gives negative delays. Each later child then starts further into its entrance.

A cascade does not split text. To reveal each word, wrap each word in an element:

import { Cascade } from "@awesome-reveal/react";
export function HeadingWords() {
return (
<Cascade as="h2" className="words" interval={60}>
<span>Reveal</span> <span>each</span> <span>word</span>
</Cascade>
);
}

The entrance moves the element with a transform, and an inline element cannot have a transform. So give the words display: inline-block. Select inline to see the words fade in with no movement:

Reveal each word

Reveal each word

display

Your device asks for reduced motion, so the content shows with no animation.

.words span {
display: inline-block;
}
.words span {
display: inline;
}

A cascade schedules all its children at the same time. In a long list, or in a grid that is taller than the viewport, the last children start late or out of view. Reveal each item instead:

import { Reveal } from "@awesome-reveal/react";
export function PostList({ posts }) {
return (
<ul className="posts">
{posts.map((post) => (
<Reveal as="li" key={post.id}>
{post.title}
</Reveal>
))}
</ul>
);
}

Also reveal each item of a virtualized list.

  • Add the children before the reveal. In React, Vue and Astro, the cascade reads its children when it reveals. A child that you add after the reveal shows with no animation. For JavaScript, see Targets.
  • Do not put a reveal directly inside a cascade. In React and Vue, the two entrances combine on the same element. In Astro, the host of a nested Reveal has display: contents, so the cascade does not animate it, and the nested Reveal plays only its own entrance.
  • Wrap an Astro island in an element. An island has display: contents, so the cascade does not animate it.
  • A Vue <TransitionGroup> adds its own animations. As a direct child of a cascade, it animates the children too.
  • A React fragment gives one child for each element. A component that returns a fragment gives one cascade child for each element of the fragment.
  • The reveal event comes from the container. onReveal and the reveal event get the container, not each child.