# Astro reveal API: Reveal and Cascade

> API reference of @awesome-reveal/astro: the Reveal and Cascade components, the getReveal function for client scripts, the reveal event and the RevealTag type.

`@awesome-reveal/astro` exports two components and the [`getReveal`](#getreveal) function. The components take the same [options](/reference/options/) as props. For the supported versions, see [Requirements](/getting-started/#requirements).

```js
import { Cascade, getReveal, Reveal } from "@awesome-reveal/astro";
```

## Reveal

Renders a tag around its children, and reveals the tag when it enters the viewport.

```astro
<Reveal as="section" from="left" class="hero">
  Hello
</Reveal>
```

* **Props**: `as`, `from`, `keyframes`, `duration`, `delay`, `threshold` and `when`. See [Options](/reference/options/).
* **Other attributes**: the component gives them to the rendered tag, for example `class` and `id`.
* **`as`**: a [`RevealTag`](#types). The default is `"div"`.

The props go into the server HTML, so they must be values that JSON can serialize. To run code at the reveal, listen to the [`reveal` event](#the-reveal-event).

## Cascade

Renders a tag around its children. When the tag enters the viewport, it reveals the direct element children one after the other. See [Animate a list](/guides/lists/).

`Cascade` accepts the props of `Reveal`, and [`interval`](/reference/options/#interval).

## getReveal

Gives the control of the reveal of a tag that `Reveal` or `Cascade` rendered. Call it in a [processed `<script>`](https://docs.astro.build/en/guides/client-side-scripts/#script-processing). A `<script is:inline>` cannot import the package:

```astro
---
import { Reveal } from "@awesome-reveal/astro";
---

<button id="show">Show</button>
<Reveal id="details" when={false}>
  Details
</Reveal>

<script>
  import { getReveal } from "@awesome-reveal/astro";

  const reveal = getReveal(document.querySelector("#details")!);

  document.querySelector("#show")!.addEventListener("click", () => {
    reveal.when = true;
  });
</script>
```

* **Argument**: the rendered tag, for example the element with the `id` of the component.
* **Return value**: a `RevealControl` object with the members in the table below.
* **Errors**: `getReveal` throws an `Error` for any other element. The HTML parser can move the tag out of its place, for example out of a `<p>`. See [Where to place a reveal](/frameworks/astro/#where-to-place-a-reveal).
* **Navigations**: with the `<ClientRouter />`, call `getReveal` again after each navigation, because the new page has new elements. See [View transitions](/frameworks/astro/#view-transitions).

| Member     | Type              | Description                                                                                                                                 |
| ---------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `when`     | `boolean \| null` | Gets or sets the [manual control](/guides/manual-control/). `null` gives the control to the viewport and keeps a revealed element revealed. |
| `revealed` | `boolean`         | `true` after the reveal. Read only. It is `false` until the client script attaches the element.                                             |

## The reveal event

The rendered tag dispatches a `reveal` event when the reveal starts. The event [bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles), so you can listen on an ancestor or on `document`. See [Run code when the reveal starts](/guides/reveal-events/#run-code-when-the-reveal-starts).

## Types

| Type             | Description                                                     |
| ---------------- | --------------------------------------------------------------- |
| `RevealProps`    | The props of `Reveal`.                                          |
| `CascadeProps`   | The props of `Cascade`.                                         |
| `RevealTag`      | The tags that `as` accepts. See [`as`](/reference/options/#as). |
| `RevealControl`  | The object that [`getReveal`](#getreveal) returns.              |
| `RevealOptions`  | The reveal options.                                             |
| `CascadeOptions` | The cascade options.                                            |
| `Side`           | The sides of [`from`](/reference/options/#from).                |
| `StartState`     | The [start state](/guides/entrances/) object of `from`.         |
