Leaderboard

Ranked leaderboard for one or more game entities. Supports Classic Quizzes, Match Quizzes, Top X games, and Template-based games. Multi-entity mode adds a dropdown selector and an aggregated "Overall" view across Classic Quiz entities.

Import

import { Leaderboard } from "fansunited-frontend-components";
import { LeaderboardEntity } from "fansunited-frontend-core";

Required props

Prop	Type	Description
`entities`	`LeaderboardEntity[]`	One or more game entities.
`sdk`	`FansUnitedSDKModel`	SDK instance.
`language`	`LanguageType`	Display language.

Optional props

Prop	Type	Description
`themeOptions`	`CustomThemeOptions`	See Theming.
`pageSize`	`number`	Entries per page (1–50).
`rankStyles`	`Record<number, LeaderboardRankStyle>`	Custom background and text colors for specific rank positions.
`showOverallOnly`	`boolean`	Show only the combined "Overall" leaderboard, hiding the dropdown and individual entity leaderboards. Only takes effect with multiple Classic Quiz entities. Defaults to `false`.
`showHeading`	`boolean`	Show the heading block above the table (the "Leaderboard" eyebrow label and the title beneath it). Only ever rendered when there's no entity dropdown. Defaults to `true`.

Entities

interface LeaderboardEntity {
  id: string;
  type: "CLASSIC_QUIZ" | "MATCH_QUIZ" | "TOP_X" | "TEMPLATE";
  // (case-insensitive — "classic_quiz", "Classic_Quiz", etc. all work)
}

Type	Description
`CLASSIC_QUIZ`	Classic Quiz leaderboard.
`MATCH_QUIZ`	Match Quiz prediction leaderboard.
`TOP_X`	Top X picks game leaderboard.
`TEMPLATE`	Template-based game leaderboard.

Multi-entity behavior

Setup	Behavior
Single entity	No dropdown. The entity title and description are shown as a heading.
Mixed game types	A dropdown selector switches between entities. The first entity is selected by default.
Multiple Classic Quiz entities	An extra "Overall" option is prepended to the dropdown that aggregates rankings across all the Classic Quiz entities. "Overall" is the default selection.

Rank styles

Use rankStyles to apply custom colors to specific rank positions (e.g. gold / silver / bronze). Import LeaderboardRankStyle from fansunited-frontend-core:

interface LeaderboardRankStyle {
  backgroundColor?: string;
  color?: string;
}

<Leaderboard
  entities={[{ id: "quiz-123", type: "classic_quiz" }]}
  sdk={sdk}
  language="en"
  rankStyles={{
    1: { backgroundColor: "#FFD700", color: "#000000" },
    2: { backgroundColor: "#C0C0C0", color: "#000000" },
    3: { backgroundColor: "#CD7F32", color: "#FFFFFF" },
  }}
/>

Notes:

Any row number is valid — you are not limited to the top 3.
Styles are applied by row position in the rendered list, not by the rank number shown in the # column. Row 1 is always the first entry on the current page, row 2 the second, and so on — regardless of ties.
The current user's own row always uses the standard user highlight regardless of any matching rankStyles entry.

Hiding the heading

The heading block (the "Leaderboard" eyebrow label plus the title under it) only ever renders when there's no dropdown competing for that space — i.e. a single entity, or showOverallOnly mode. Set showHeading={false} to hide it in those cases too, e.g. when embedding the table into a page that already has its own title:

<Leaderboard
  entities={[{ id: "quiz-123", type: "classic_quiz" }]}
  sdk={sdk}
  language="en"
  showHeading={false}
/>

Features

Highlighted current-user rank when the user is signed in.
Paginated results with configurable page size.
Custom branding colors are sourced from each entity automatically.
Light and dark mode supported via themeOptions.mode.
Optional rank-position styling via rankStyles.

Examples

Single entity

<Leaderboard
  entities={[{ id: "quiz-123", type: "classic_quiz" }]}
  sdk={sdk}
  language="en"
/>

Multiple Classic Quiz entities (with Overall)

<Leaderboard
  entities={[
    { id: "quiz-123", type: "classic_quiz" },
    { id: "quiz-456", type: "classic_quiz" },
  ]}
  sdk={sdk}
  language="en"
  pageSize={20}
/>

Mixed game types

<Leaderboard
  entities={[
    { id: "topx-789", type: "top_x" },
    { id: "match-quiz-321", type: "match_quiz" },
    { id: "quiz-123", type: "classic_quiz" },
    { id: "template-654", type: "template" },
  ]}
  sdk={sdk}
  language="en"
  pageSize={10}
  themeOptions={{ mode: "dark" }}
/>