Leaderboard

Overview

The leaderboard is a ranked standings card with a top-three podium and a paginated list below it. Switch the run selector to reorder the board by a different time range, page through the rankings, and spot the highlighted current-user row. Scores are deterministic per run, so the same run always renders the same order.

Use it for competitions, usage rankings, referral standings, or any ordered list of people where the top few deserve emphasis and everyone else needs a scannable, paged view.

Installation

Import the pattern from loosethreads:

import { Leaderboard } from "@pulp/loosethreads/patterns"

Usage

Pass the roster of players and the selectable runs. Each player is a { id, name, initials } record; each run is a { id, label, range, seed } record whose seed drives the per-run ordering. Point currentUserId at the row you want highlighted:

import { Leaderboard } from "@pulp/loosethreads/patterns"

const players = [
  { id: "ava-chen", name: "Ava Chen", initials: "AC" },
  { id: "marcus-reid", name: "Marcus Reid", initials: "MR" },
  { id: "sofia-nakamura", name: "Sofia Nakamura", initials: "SN" },
  { id: "you", name: "You", initials: "YO" },
]

const runs = [
  { id: "weekly", label: "This week", range: "Jul 7 - Jul 13, 2026", seed: 31 },
  { id: "monthly", label: "This month", range: "Jul 1 - Jul 31, 2026", seed: 53 },
]

function Standings() {
  return (
    <Leaderboard
      players={players}
      runs={runs}
      currentUserId="you"
      pageSize={10}
    />
  )
}

Props

Anatomy

The card stacks a header (title, date-range subtitle, and run selector), a podium that lays out the top three as 2 / 1 / 3 with a taller first-place pedestal, the paginated rankings list, and a pager footer. The current-user row carries an iris background, an iris border, and a (you) tag. Avatar chips draw from an iris pastel palette with dark initials.

Accessibility

• Run selector. The selector is a real aria-haspopup="listbox" button with aria-expanded, opening a role="listbox" whose options expose aria-selected. It closes on outside-click and Escape.
• Pagination. The pager uses real buttons with aria-label text and a disabled state at the first and last page.
• Not color alone. The current-user row is signalled by a text (you) tag in addition to the iris highlight, and avatar chips pair dark initials with the pastel fill to clear WCAG AA.
• Motion. Nothing auto-plays. Reordering and paging are user-driven, so no prefers-reduced-motion gate is required.