# Leaderboard

Leaderboard is a neobrutalist React component from Cruise UI. Ranked rows with gold/silver/bronze chips, avatars, change arrows and scores; stacked cards on phones.

Install (with the @cruiseui registry in components.json, see Installation):

```bash
npx shadcn@latest add @cruiseui/leaderboard
```

Import: `import { CruiseLeaderboard } from "@/components/cruise/leaderboard";`

## When to use

Rankings in games, sales competitions, class scores.

## When not to

Data people sort and filter (use a Table).

## Example (React)

```tsx
import { CruiseLeaderboard } from "@/components/cruise/leaderboard";

const rows = [
  { id: "ada", name: "Ada Okafor", score: 12450, change: 2 },
  { id: "tunde", name: "Tunde Bello", score: 11980, change: -1 },
  { id: "ngozi", name: "Ngozi Eze", score: 10720 },
  { id: "me", name: "Idris Bankole", score: 9800, change: 3 },
  { id: "musa", name: "Musa Garba", score: 9110, change: -2 },
];

export default function LeaderboardExample() {
  return <CruiseLeaderboard rows={rows} currentUserId="me" unit="XP" label="This week's leaderboard" />;
}
```

## HTML

Needs theme.css (https://cruiseui.dev/theme.css).

```html
<ol class="leaderboard" aria-label="This week's leaderboard">
  <li class="leaderboard-row">
    <span class="leaderboard-rank" data-place="1"><span class="visually-hidden">Rank </span>1</span>
    <span class="avatar avatar-sm" aria-hidden="true"><span class="avatar-fallback">AO</span></span>
    <span class="leaderboard-name">Ada Okafor</span>
    <span class="leaderboard-change" data-dir="up"><span class="visually-hidden">up </span>2</span>
    <span class="leaderboard-score">12,450 XP</span>
  </li>
  <li class="leaderboard-row" aria-current="true">
    <span class="leaderboard-rank"><span class="visually-hidden">Rank </span>4</span>
    <span class="avatar avatar-sm" aria-hidden="true"><span class="avatar-fallback">IB</span></span>
    <span class="leaderboard-name">Idris Bankole<span class="leaderboard-you">(you)</span></span>
    <span></span>
    <span class="leaderboard-score">9,800 XP</span>
  </li>
</ol>
```

## Props: CruiseLeaderboard

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rows` | `CruiseLeaderboardRow[]` | — | — |
| `currentUserId?` | `string` | — | The row to highlight as "you". |
| `label?` | `string` | `"Leaderboard"` | — |
| `unit?` | `string` | `""` | After the score, e.g. "XP" or "pts". |
| `className?` | `string` | — | — |

## Accessibility

- An ordered list labelled "Leaderboard"; each rank reads "Rank 1".
- Changes say "up 2" / "down 1", not only ▲ / ▼ and colour.
- The current user's row is aria-current and says "(you)".