Leaderboard React chart component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Leaderboard is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import Leaderboard from @/components/ui/leaderboard.

import { Leaderboard, type LeaderboardItem } from "@/components/ui/leaderboard"

const team: LeaderboardItem[] = [
  { id: "daniel", name: "Daniel Reed", value: 48920.5, avatar: "/demo/mihai-ionescu.jpg", previousRank: 2 },
  { id: "ryan", name: "Ryan Cooper", value: 31200, avatar: "/demo/radu-marin.jpg", previousRank: 1 },
  { id: "emma", name: "Emma Carter", value: 18080, avatar: "/demo/ana-pop.jpg", previousRank: 3 },
  { id: "grace", name: "Grace Kim", value: 14450, avatar: "/demo/maria-toma.jpg", previousRank: 5 },
  { id: "olivia", name: "Olivia Brooks", value: 3450, avatar: "/demo/elena-stan.jpg", previousRank: null },
]

export function TopSellers() {
  return (
    <Leaderboard
      title="Top sellers"
      metric="Revenue, September 2026"
      items={team}
      valueFormat="currency"
      currency="USD"
      locale="en-US"
      highlightId="emma"
      limit={4}
      onItemClick={(item) => console.log(item.id)}
    />
  )
}

Props

• items*
  LeaderboardItem[]

  { id, name, value, avatar?, icon?, description?, previousRank?, delta?, href?, searchName? }. Ranked by value unless sort is none; equal values share a rank (1, 1, 3). previousRank null marks a new entry. icon replaces the avatar with a tile (products, channels).

• titledefault ""
  ReactNode

  The heading above the list; also the list's accessible name.

• metricdefault ""
  ReactNode

  The caption under the title: what is ranked and for which period.

• highlightIddefault ""
  string

  The id of the current user's row: tinted, with a "You" chip. When it falls outside the limit it is pinned as an extra last row after a gap.

• valueFormatdefault "number"
  LeaderboardValueFormat = "number" | "compact" | "currency" | "percent"

  How values print, through the chart kit with the locale: "48,921", "49K", "$48,921", "12.4%".

• currencydefault "USD"
  string

  ISO 4217 code for valueFormat="currency" (and deltaFormat="currency"), printed with its narrow symbol. An unknown code prints as a plain unit after the number.

• decimalsdefault 0
  number

  Fraction digits for values (0 to 6); auto when unset (Auto in the playground): 0 from 100 up, 1 for percent, up to 2 for small numbers.

• formatValue
  (value: number, item: LeaderboardItem) => string

  Full control over the value text, e.g. minutes: v => `${v} min`. The count-up and the spoken sentence use it too.

• localedefault ""
  string

  Intl locale for values and deltas. Empty uses the UIProvider locale, then the page's language.

• actions
  ReactNode

  Controls at the end of the header: a period picker, a button.

• variantdefault "surface"
  "surface" | "plain"

  surface is a raised panel (a list group); plain is bare rows for use inside a card or on a page.

• sizedefault "md"
  "sm" | "md" | "lg"

  Rows at least 44 / 56 / 64px with 32 / 40 / 48px avatars; a description plus a bar adds a little height. sm never goes below 44px, so it stays a full touch target.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The bar fill. neutral is the foreground ink (black in light mode, white in dark).

• colordefault ""
  string

  Any CSS color or a chart palette slot ("series-3") for the bars; replaces the tone.

• showChangedefault "rank"
  "rank" | "delta" | "none"

  rank: ▲2, ▼1, a gray dash or New, from previousRank. delta: a ghost trend badge from each item's delta. none hides the column.

• deltaFormatdefault "percent"
  LeaderboardDeltaFormat = "percent" | "number" | "currency"

  How deltas print with showChange="delta" (12.4 is +12,4 %).

• invertTrenddefault false
  boolean

  With showChange="delta": a falling delta is good and turns green (response time, costs).

• podiumdefault false
  boolean

  The top three on steps above the list: 2nd left, 1st in the middle and raised with a crown, 3rd right. The list continues from rank 4. Needs at least three items.

• showRankdefault true
  boolean

  The rank column (numbers or medals).

• medalsdefault true
  boolean

  Ranks 1 to 3 as gold, silver and bronze discs, in the list and on the podium.

• medalColorsdefault "["#E8B923", "#A7AFBA", "#C27C4E"]"
  [string, string, string]

  Gold, silver and bronze. The number on each disc turns dark or white by the color's lightness.

• showAvatarsdefault true
  boolean

  The avatar (photo or initials) or the item's icon tile before the name.

• showBarsdefault true
  boolean

  A 4px bar under each name, proportional to the largest value. Hidden when the largest value is zero or less.

• dividersdefault true
  boolean

  Hairlines between rows.

• sortdefault "desc"
  "desc" | "asc" | "none"

  desc ranks the highest first; asc is for lower-is-better metrics (response time); none keeps the given order.

• limitdefault 5
  number

  Rows before "Show all" (after the podium when it is on). 0 shows every row; a limit larger than the list hides the button.

• loadingdefault false
  boolean

  Skeleton rows with the avatar shape; the header stays.

• defaultExpandeddefault false
  boolean

  Starts with every row shown. Use expanded / onExpandedChange to control it.

• expanded
  boolean

  Controlled "show all" state.

• onExpandedChange
  (expanded: boolean) => void

  Fires when Show all / Show less is pressed.

• emptyState
  ReactNode

  Shown when items is empty. Defaults to a trophy tile with labels.empty.

• animateddefault true
  boolean

  Bars grow and values count up the first time the list scrolls into view; rows glide to their new place when the order changes and rank chips pop. Off (and under reduced motion) everything renders final.

• onItemClick
  (item: LeaderboardItem, rank: number) => void

  Makes every row a button with roving focus (Up / Down, Home / End, PageUp / PageDown, Enter).

• renderLink
  (props: ComponentProps<"a">) => ReactElement

  Renders rows whose item has an href, e.g. props => <Link {...props} href={props.href!} />. Defaults to a plain <a>.

• labels
  Partial<LeaderboardLabels>

  showAll(n), showLess, you, new, up(n), down(n), same, increase(text), decrease(text), rank(n), item(rank, name, value, change), empty, loading, list, podium. English defaults; item defaults to rank(n), name, value and change joined with commas.

• classNames
  Partial<Record<"header" | "title" | "metric" | "actions" | "podium" | "list" | "item" | "rank" | "avatar" | "name" | "description" | "value" | "change" | "bar" | "more", string>>

  Extra classes for the inner parts.

• className
  string

  Extra classes for the root, merged last.

Parts

FAQ

Used in

More React chart and stat components