# List scene

The list scene ranks a few things under a headline. Every row has its rank, its name, a meter measured against the first row, and a count. Use it for a top three: repositories, customers, songs, pages.

> Live preview: see the scene playing at https://bettertyped.github.io/react-wrapped/docs/scenes/list/
>
> Three rows, each measured against the first.

## Installation

```bash
pnpm add @react-wrapped/scenes @react-wrapped/core gsap
```

## Usage

Call `listScene` with what the scene says, then with the key and the label it goes by. What comes back is a scene placed in a video: put it in the `scenes` array of a [player](https://bettertyped.github.io/react-wrapped/docs/player/wrapped-player/). The code below places the scene in the preview above.

```tsx
import { listScene } from "@react-wrapped/scenes";

export const scene = listScene(
  {
    eyebrow: "Where it happened",
    title: ["Your top", "repositories."],
    items: [
      {
        name: "ada/orbit-cli",
        value: 742,
        unit: "commits",
        meta: "TypeScript",
        color: "#3178c6",
      },
      { name: "ada/telemetry", value: 355, unit: "commits", meta: "Go", color: "#00add8" },
      { name: "ada/dotfiles", value: 203, unit: "commits", meta: "Shell", color: "#89e051" },
    ],
  },
  { key: "repositories", label: "Top repositories" },
);
```

## Props

| Prop | Type | What it does |
| --- | --- | --- |
| `eyebrow` | `string` | The small line above the headline. |
| `title` | `readonly string[]` | The headline, one entry per line. |
| `items` | `readonly { name: string; value: number; unit: string; meta?: string; color?: string \| null }[]` | The rows, biggest first. `value` and `unit` are the count on the right, `meta` is the small note on the left, and `color` puts a dot before it. |

> Three rows fit every format. With more, the scene is scaled down to fit the frame, so the type gets smaller.

## What a viewer can rewrite

These texts are the scene's fields. From the pencil on the [timeline](https://bettertyped.github.io/react-wrapped/docs/player/timeline/) a viewer opens the [scene editor](https://bettertyped.github.io/react-wrapped/docs/player/scene-editor/) and rewrites them. Numbers, charts and pictures stay yours. Place the scene with `locked: true` and it offers none of them.

| Field | In the editor | Edited as |
| --- | --- | --- |
| `eyebrow` | Line above | One line |
| `title` | Headline | Lines, one per line on screen |

## How it comes in

The rows slide in from one side, a beat apart (the seed picks the side). Each row's meter then draws from the left while its count climbs. The scene then holds for at least as long as its text takes to read. The way out is not the scene's: the player adds a [transition](https://bettertyped.github.io/react-wrapped/docs/transitions/).

## In a real year

The sample lists the three repositories with the most commits and tags each with its main language.

> Live preview: see the scene playing at https://bettertyped.github.io/react-wrapped/docs/scenes/list/

## Related

- [Scenes](https://bettertyped.github.io/react-wrapped/docs/scenes/)
- [Split scene](https://bettertyped.github.io/react-wrapped/docs/scenes/split/)
- [Bars scene](https://bettertyped.github.io/react-wrapped/docs/scenes/bars/)
- [Trophies scene](https://bettertyped.github.io/react-wrapped/docs/scenes/trophies/)
- [Custom scene](https://bettertyped.github.io/react-wrapped/docs/guides/custom-scene/)

Source: https://bettertyped.github.io/react-wrapped/docs/scenes/list/