Headless SDK: leaderboards
useLeaderboard returns the windowed ranking, the user's row, and the bracket around it. The SDK handles live updates and the highlight logic; you write the markup.
Key takeaways
Quick read- useLeaderboard({ code }) returns entries (the top N) plus myRank and totalParticipants.
- Pass limit to size the top N; the hook polls every 30s (tune with refreshInterval).
- Each entry carries rank, participantId, name, score, and an optional change indicator.
- Highlight the current user by comparing entry.rank === myRank.
- For a user far down the board, read their exact rank from GET /gamify/leaderboards/{code}/rank/{pid}.
Bracket view
The default surface
"use client";
import { useLeaderboard } from "@bricqs/sdk-react";
export function TopBoard() {
// engagementId inherited from <BricqsProvider>
const { entries, myRank, isLoading } = useLeaderboard({
code: "april_quiz_cup",
limit: 10,
});
if (isLoading) return null;
return (
<section className="rounded-xl border bg-white p-5">
<header className="flex items-baseline justify-between mb-3">
<h3 className="font-bold">Top 10</h3>
{myRank != null && (
<span className="text-sm text-slate-500">You're #{myRank}</span>
)}
</header>
<ol className="divide-y">
{entries.map((e) => (
<li
key={e.participantId}
className={`flex items-center gap-3 py-2 ${e.rank === myRank ? "bg-orange-50 -mx-3 px-3" : ""}`}
>
<span className="w-8 text-right tabular-nums text-slate-500">{e.rank}</span>
<span className="flex-1 font-medium">{e.name}</span>
<span className="tabular-nums">{e.score.toLocaleString()}</span>
</li>
))}
</ol>
</section>
);
}Top view
Combine bracket and global top
const { entries, myRank } = useLeaderboard({ code: "april_quiz_cup", limit: 10 });
// entries = top 10; highlight the row where entry.rank === myRank.
// For the user's exact position when they're outside the top 10, call
// GET /gamify/leaderboards/april_quiz_cup/rank/{participantId}.Segmentation
Per-region or per-cohort views
// Segmented boards are separate leaderboard codes, configured server-side.
useLeaderboard({ code: "april_quiz_cup_south_india", limit: 50 });Model a segment as its own leaderboard code. Point the hook at the code you want; an unknown code returns an empty list.
Common mistakes
What goes wrong
Showing only the global top. The middle 80 percent of users disengage.
Pair the top N with the user's own rank (myRank, or the /rank/{pid} endpoint) so everyone sees their position.
Polling every 5 seconds for hours. Network panel and battery suffer.
Default 30 seconds. Tighten with refreshInterval only in the final hour of the window.
Highlighting the user only by name match. False positives when names collide.
Compare entry.rank === myRank. myRank is bound to the participant token, not the display name.
Hiding when scoring ends. Users do not know the deadline.
Render the window label + end time from your own contest metadata alongside the board.
Developer FAQ
Common questions when integrating gamification with Bricqs.
Ready to ship?
Wire it up with the Bricqs SDK or API
Headless SDK for React UIs, REST API for any backend. Same engine behind both.