Leaderboard Block React component
A leaderboard with a medal podium for the top three, a ranked list with progress bars and up or down arrows against the previous period, period, metric and team switches that re-rank everyone with smooth motion, and your own row pinned at the bottom when you are further down.
About the Leaderboard Block component
Leaderboard Block ranks people by any score. The top three stand on a podium with gold, silver and bronze rings; everyone else follows in a list with a bar against the leader and an arrow showing how many places they moved since the previous period.
Switch the period, the metric or the team and everyone glides to their new place, including moving on and off the podium. The person looking at it is highlighted, and if they are further down than the visible rows their own position is pinned at the bottom so they always see where they stand.
When to use it
Use it for sales targets, community points, learning streaks, game scores or internal recognition.
Keep periods to two or three; more choices make the rank-change arrows harder to read.
Installation
Add the Leaderboard Block component to your project with the shadcn CLI. It lands in components/leaderboard.tsx as plain React + Tailwind CSS source you own and can edit.
npx shadcn@latest add @reactframe/leaderboardOr copy the source by hand and install its dependencies:
npm install motion clsx tailwind-mergeProps
<Leaderboard /> accepts 9 props, all optional.
| Prop | Type | Default |
|---|---|---|
| title | string | "Leaderboard" |
| description | string | "Points come from shipped tasks, reviews and helping teammates. Updated every hour." |
| players | { id: string; name: string; team: string; avatar?: string; scores: Record<string, Record<string, number>> }[] | — |
| periods | { id: string; label: string; previous?: string }[] | DEFAULT_PERIODS |
| metrics | { id: string; label: string; unit?: string }[] | DEFAULT_METRICS |
| currentUserId Highlighted as "You" and pinned under the list when outside the shown rows. | string | "nadia-petrova" |
| limit Rows shown under the podium. | number | 7 |
| theme | "dark" | "light" | "dark" |
| className | string | — |
- titlestringDefault: "Leaderboard"
- descriptionstringDefault: "Points come from shipped tasks, reviews and helping teammates. Updated every hour."
- players{ id: string; name: string; team: string; avatar?: string; scores: Record<string, Record<string, number>> }[]
- periods{ id: string; label: string; previous?: string }[]Default: DEFAULT_PERIODS
- metrics{ id: string; label: string; unit?: string }[]Default: DEFAULT_METRICS
- currentUserId
Highlighted as "You" and pinned under the list when outside the shown rows.
stringDefault: "nadia-petrova" - limit
Rows shown under the podium.
numberDefault: 7 - theme"dark" | "light"Default: "dark"
- classNamestring
npm dependencies
Installed for you by the shadcn CLI.
Leaderboard Block FAQ
- How do I shape the scores?
- Each player has scores keyed by period and then metric, for example scores.week.points. Add as many periods and metrics as you like and list them in the periods and metrics props.
- How are the up and down arrows worked out?
- A period can name a previous period. The block ranks both and shows how many places each person moved. Periods without previous, such as All time, show no arrows.
- How does the pinned You row work?
- Pass currentUserId. That person is highlighted wherever they are; if their rank is beyond the podium plus limit rows, their row appears under the list after a small gap.
- What if people have no photo?
- Leave avatar out and their initials are shown in a circle instead.
- Is it accessible?
- The podium and list are ordered lists with correct start numbers, controls are radio buttons, a select and toggle buttons, rank changes have text labels such as 'Up 3', and the footer announces your rank.
