GitHub

Leaderboard Podium

Top-three React leaderboard podium with crowns, avatars, and ranks for competitive gamification. Leaderboard UI component for highlights and recap screens. Built on shadcn/ui + Tailwind. Open source.

The Leaderboard Podium spotlights top-three ranks in competitive gamification UIs. Pair with Leaderboard Rankings for a hero podium plus a full table—ideal after weekly resets, seasonal contests, or anywhere gamification needs a clear winner moment.

Leo Harrison1,100
Ava Elizabeth Turner1,250
Rowan Elijah980

Installation

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

Usage

import { LeaderboardPodium } from "@/components/ui/leaderboard-podium"
<LeaderboardPodium
  rankings={[
    {
      userId: "1",
      userName: "Ava Elizabeth Turner",
      rank: 1,
      value: 2500,
      avatarUrl: "https://i.pravatar.cc/96?img=32",
    },
    {
      userId: "2",
      userName: "Leo Harrison",
      rank: 2,
      value: 2200,
      avatarUrl: "https://i.pravatar.cc/96?img=12",
    },
    {
      userId: "3",
      userName: "Rowan Elijah",
      rank: 3,
      value: 1800,
      avatarUrl: "https://i.pravatar.cc/96?img=15",
    },
  ]}
/>

Examples

Basic Usage

Leo Harrison1,100
Ava Elizabeth Turner1,250
Rowan Elijah980
<LeaderboardPodium rankings={rankings} />

Sizes

Leo Harrison1,100
Ava Elizabeth Turner1,250
Rowan Elijah980
Leo Harrison1,100
Ava Elizabeth Turner1,250
Rowan Elijah980
Leo Harrison1,100
Ava Elizabeth Turner1,250
Rowan Elijah980
<LeaderboardPodium rankings={rankings} size="sm" />
<LeaderboardPodium rankings={rankings} size="default" />
<LeaderboardPodium rankings={rankings} size="lg" />

Partial Podium

Works with fewer than 3 users:

Bob2,200
Alice2,500
// Only 2 users - shows 2nd and 1st place
<LeaderboardPodium
  rankings={[
    { userId: "1", userName: "Alice", rank: 1, value: 2500 },
    { userId: "2", userName: "Bob", rank: 2, value: 2200 },
  ]}
/>

With Trophy

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

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 LeaderboardPodium props in your UI layer:

const rankings = (response.rankings ?? []).slice(0, 3)

<LeaderboardPodium rankings={rankings} />

API Reference

LeaderboardPodium

PropTypeDefaultDescription
rankingsLeaderboardRanking[]RequiredTop rankings (uses first 3)
size"sm" | "default" | "lg""default"Podium size
showValuebooleantrueShow score below name
showAvatarbooleantrueShow avatar images
medalStyle"classic" | "modern" | "minimal""classic"Crown badge display style

LeaderboardRanking

interface LeaderboardRanking {
  userId: string
  userName: string | null
  rank: number
  value: number
  avatarUrl?: string | null
}
Raise an issue Contribute