Leaderboard Rankings

React leaderboard rankings list—avatars, scores, bylines, and crown highlights for full tables. Open-source leaderboard UI for games, communities, and SaaS challenges. shadcn/ui + Tailwind.

Leaderboard Rankings is a dense React table for competitive gamification—full rankings with avatars, scores, bylines, and crown highlights for the top three, plus pagination and collapsible rows with built-in highlighting for the current user in leaderboard-driven gamification flows.

Ava Elizabeth Turner

Level 42 - Diamond

289.4k

Leo Harrison

Level 39 - Platinum

251.8k

Rowan Elijah

Level 37 - Platinum

238.3k

Mia Sophia Bennett

Level 34 - Gold

221.7k

William Turner

Level 33 - Gold

199.5k

Installation

npx shadcn@latest add https://ui.trophy.so/leaderboard-rankings

Usage

import { LeaderboardRankings } from "@/components/ui/leaderboard-rankings"

<LeaderboardRankings
  rankings={[
    {
      userId: "u-1",
      rank: 1,
      userName: "Ava Elizabeth Turner",
      byline: "Level 42 - Diamond",
      value: 289400,
      avatarUrl: "https://i.pravatar.cc/96?img=32",
    },
    {
      userId: "u-2",
      rank: 2,
      userName: "Leo Harrison",
      byline: "Level 39 - Platinum",
      value: 251800,
      avatarUrl: "https://i.pravatar.cc/96?img=12",
    },
  ]}
/>

Examples

Basic Usage

Ava Elizabeth Turner

Level 42 - Diamond

289.4k

Leo Harrison

Level 39 - Platinum

251.8k

Rowan Elijah

Level 37 - Platinum

238.3k

Mia Sophia Bennett

Level 34 - Gold

221.7k

William Turner

Level 33 - Gold

199.5k

<LeaderboardRankings
  rankings={[
    {
      userId: "u-1",
      rank: 1,
      userName: "Ava Elizabeth Turner",
      byline: "Level 42 - Diamond",
      value: 289400,
      avatarUrl: "https://i.pravatar.cc/96?img=32",
    },
    {
      userId: "u-2",
      rank: 2,
      userName: "Leo Harrison",
      byline: "Level 39 - Platinum",
      value: 251800,
      avatarUrl: "https://i.pravatar.cc/96?img=12",
    },
  ]}
/>

Rank Change Indicators

Ava Elizabeth Turner

Level 42 - Diamond

289.4k

Leo Harrison

Level 39 - Platinum

251.8k

Rowan Elijah

Level 37 - Platinum

238.3k

Mia Sophia Bennett

Level 34 - Gold

221.7k

<LeaderboardRankings
  rankings={[
    {
      userId: "u-1",
      rank: 1,
      userName: "Ava Elizabeth Turner",
      byline: "Level 42 - Diamond",
      value: 289400,
      avatarUrl: "https://i.pravatar.cc/96?img=32",
      rankChange: 2,
    },
    {
      userId: "u-2",
      rank: 2,
      userName: "Leo Harrison",
      byline: "Level 39 - Platinum",
      value: 251800,
      avatarUrl: "https://i.pravatar.cc/96?img=12",
      rankChange: -1,
    },
  ]}
/>

Pagination

Ava Elizabeth Turner

Level 42 - Diamond

289.4k

Leo Harrison

Level 39 - Platinum

251.8k

Rowan Elijah

Level 37 - Platinum

238.3k

Mia Sophia Bennett

Level 34 - Gold

221.7k

William Turner

Level 33 - Gold

199.5k

Ruby Claire

Level 31 - Gold

198.3k

Ethan Brooks

Level 29 - Silver

187.2k

Chloe Madison

Level 28 - Silver

176.8k

Noah Bennett

Level 27 - Silver

169.3k

Isla Monroe

Level 26 - Silver

161.9k

Show

Page 1 of 2

<LeaderboardRankings
  showPagination
  rankings={[
    {
      userId: "u-1",
      rank: 1,
      userName: "Ava Elizabeth Turner",
      byline: "Level 42 - Diamond",
      value: 289400,
      avatarUrl: "https://i.pravatar.cc/96?img=32",
    },
    {
      userId: "u-2",
      rank: 2,
      userName: "Leo Harrison",
      byline: "Level 39 - Platinum",
      value: 251800,
      avatarUrl: "https://i.pravatar.cc/96?img=12",
    },
    {
      userId: "u-3",
      rank: 3,
      userName: "Rowan Elijah",
      byline: "Level 37 - Platinum",
      value: 238300,
      avatarUrl: "https://i.pravatar.cc/96?img=15",
    },
    // ...more rows
  ]}
/>

Current User Focus

Ava Elizabeth Turner

Level 42 - Diamond

289.4k

Leo Harrison

Level 39 - Platinum

251.8k

Rowan Elijah

Level 37 - Platinum

238.3k

Grace Coleman

Level 22 - Bronze

130.6k

Olivia Reed

Level 22 - Bronze

129.9k

Evan Knight

Level 21 - Bronze

129.3k

Nora Ellis

Level 14 - Rookie

110.3k

Owen Ward

Level 14 - Rookie

109.8k

Paige Hudson

Level 13 - Rookie

109.2k

Quinn Tate

Level 13 - Rookie

108.6k

Riley James

Level 12 - Rookie

107.9k

<LeaderboardRankings
  currentUserId="u-20"
  rankings={[
    {
      userId: "u-1",
      rank: 1,
      userName: "Ava Elizabeth Turner",
      byline: "Level 42 - Diamond",
      value: 289400,
      displayed: true,
    },
    {
      userId: "u-2",
      rank: 2,
      userName: "Leo Harrison",
      byline: "Level 39 - Platinum",
      value: 251800,
      displayed: true,
    },
    {
      userId: "u-3",
      rank: 3,
      userName: "Rowan Elijah",
      byline: "Level 37 - Platinum",
      value: 238300,
      displayed: true,
    },
    {
      userId: "u-4",
      rank: 4,
      userName: "Mia Sophia Bennett",
      byline: "Level 34 - Gold",
      value: 221700,
      displayed: false,
    },
    // ... hidden rows collapse into "..."
    {
      userId: "u-19",
      rank: 19,
      userName: "Grace Coleman",
      byline: "Level 22 - Bronze",
      value: 130600,
      displayed: true,
    },
    {
      userId: "u-20",
      rank: 20,
      userName: "Olivia Reed",
      byline: "Level 22 - Bronze",
      value: 129900,
      displayed: true,
    },
    {
      userId: "u-21",
      rank: 21,
      userName: "Evan Knight",
      byline: "Level 21 - Bronze",
      value: 129300,
      displayed: true,
    },
    {
      userId: "u-22",
      rank: 22,
      userName: "Ivy Brooks",
      byline: "Level 20 - Bronze",
      value: 128700,
      displayed: false,
    },
    // ... another collapsed block
    {
      userId: "u-40",
      rank: 40,
      userName: "Nora Ellis",
      byline: "Level 14 - Rookie",
      value: 110300,
      displayed: true,
    },
    {
      userId: "u-41",
      rank: 41,
      userName: "Owen Ward",
      byline: "Level 14 - Rookie",
      value: 109800,
      displayed: true,
    },
    {
      userId: "u-42",
      rank: 42,
      userName: "Paige Hudson",
      byline: "Level 13 - Rookie",
      value: 109200,
      displayed: true,
    },
    {
      userId: "u-43",
      rank: 43,
      userName: "Quinn Tate",
      byline: "Level 13 - Rookie",
      value: 108600,
      displayed: true,
    },
    {
      userId: "u-44",
      rank: 44,
      userName: "Riley James",
      byline: "Level 12 - Rookie",
      value: 107900,
      displayed: true,
    },
  ]}
/>

With Trophy

Use the Trophy SDK to fetch leaderboard data server-side:

Snippet

import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient({
  apiKey: 'YOUR_API_KEY'
});

const response = await trophy.leaderboards.get("weekly-words", {
  offset: 0,
  limit: 10,
  run: "2025-01-15"
});

Then pass the response into LeaderboardRankings props in your UI layer:

const rankings = response.rankings ?? []

<LeaderboardRankings rankings={rankings} />

API Reference

Prop	Type	Default	Description
`rankings`	`LeaderboardRankingItem[]`	Required	Rows to render in ranking order
`onUserClick`	`(ranking) => void`	-	Optional row click handler
`currentUserId`	`string`	-	Highlights the matching row with a stronger border style
`showPagination`	`boolean`	`false`	Show page controls and page size selector
`defaultPageSize`	`10 \| 25 \| 50 \| 100`	`10`	Initial number of rankings shown per page

LeaderboardRankingItem

interface LeaderboardRankingItem {
  userId: string
  userName: string | null
  rank: number
  value: number
  byline?: string | null
  avatarUrl?: string | null
  rankChange?: number
  displayed?: boolean
}

Leaderboard Podium Points Awards

Raise an issue Contribute

On This Page

Installation Usage Examples Basic Usage Rank Change Indicators Pagination Current User Focus With Trophy API Reference LeaderboardRankingItem

Power Gamification with Trophy

Trophy powers the infrastructure you need to ship reliable gamification features at scale.

Get Started