# Leaderboard

> Where you stand and what it takes to move up: a line that fills as you close on the person above, and an overtake that swings out a lane to pass.

Leaderboards show a ranked list and leave you to work out how far the next place is. This one measures it for you. Under the board a line of hairlines sets you against the person just above: it fills as you score, while “184 XP to pass Mira” rolls down as it goes. When you pass someone, or anyone passes anyone, the climber swings out a lane, passes, and settles into its new place while the one passed drops back; the ranks roll, and a small ▲2 shows beside the climber for a moment. Outside the top few, your own row stays pinned under them, so you never scroll to find yourself. In first place the line becomes your lead over second, in green. Scores are yours: pass entries and who’s looking; the board sorts, ranks and animates whatever changed.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/leaderboard.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: none
- Hairline UI components it needs (the CLI installs them too): `number-roll`, `text-morph`
- Docs and live preview: https://hairlineui.com/ui/leaderboard
- Registry item (source): https://hairlineui.com/r/leaderboard.json

## Usage

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

<Leaderboard
  title="Gold league"
  period="Ends in 2 days"
  unit="XP"
  you={user.id}
  entries={players} // { id, name, score, avatar? }[]
/>
```

## Live from your API

Poll the league every few seconds; the board animates whatever moved.

```tsx
"use client";
import useSWR from "swr";
import { Leaderboard, type LeaderEntry } from "@/components/leaderboard";

export function League({ leagueId, userId }: { leagueId: string; userId: string }) {
  const { data } = useSWR<LeaderEntry[]>(`/api/leagues/${leagueId}`, (u: string) => fetch(u).then((r) => r.json()), { refreshInterval: 5000 });
  return <Leaderboard title="Gold league" period="This week" unit="XP" you={userId} entries={data ?? []} />;
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `entries` | `LeaderEntry[]` | – | Each entry: id, name, score, and optionally avatar. Any order; the board sorts them. |
| `you` | `string` | – | The id of the person looking: their row is highlighted or pinned, and the line measures them. |
| `title / period` | `string` | – | Over the board. |
| `unit` | `string` | `"pts"` | After every score. |
| `top` | `number` | `5` | How many rows show before your pinned row. |
| `locale` | `string` | – | For the numbers; the visitor’s once hydrated when left out. |

## States

- **to pass**: The gap to the person above (their score minus yours, plus one) rolls down; the line under it fills from where it stood when they became your target to full when you draw level (700ms per change).
- **overtake**: Rows that change place glide from where they were (760ms). A climber swings 12px out to the right halfway, slightly larger, and comes back in at its new place, drawn over the rows it passes; a row passed dims a little as it drops. Ranks roll and a ▲ chip shows beside the climber for 2.2s.
- **pinned**: If you’re below the top rows, three dots and your own row follow them, on a grey step.
- **lead**: In first place the line is full and green, and says your lead over second.
- **reduced motion**: Rows change places in place; numbers change without rolling.

## What it handles

A ranked list leaves you to find yourself and work out the gap to the next place, and rows that change order jump without showing who passed whom.

- **The next place, measured**: A line fills as you close on the person above, with the gap rolling down.
- **Overtakes you can see**: The climber swings out a lane and passes; the one passed drops back.
- **Always find yourself**: Outside the top few, your row is pinned under them.
- **Leading, too**: In first place the line becomes your lead over second.
- **Ranks that roll**: Places and scores roll; a ▲ chip marks who climbed.
- **Quiet for screen readers**: Your place is announced when it changes, never the scores ticking.

## Replaces

a leaderboard table, a ranking list, a rank change badge, a progress to next rank bar

## Where it fits

- **Learning and fitness leagues**: Weekly leagues where the next place is the reason to do one more lesson.
- **Sales and support boards**: Deals or tickets closed this month, on a team dashboard.
- **Games and contests**: Scores in a game, a hackathon or a referral contest.
- **Community and creators**: Top contributors, streaks or points in a community.

## Notes

- The board is an ordered list; your row is marked aria-current; only your place is announced when it changes, never the scores.
- Overtakes glide from measured row positions with the Web Animations API, so nothing re-renders while rows move.
- The to-pass line is drawn in the library’s hairline mark: 2px lines every 4px, faint where empty.
- Installs Number roll and Text morph. With reduced motion rows change places in place.

License: MIT (https://hairlineui.com/license#components)
