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({ id, view }) returns rows. view='bracket' gives 3 above and 3 below the user.
- view='top' gives the global top N. Combine both on the same screen for richer UX.
- The hook polls every 30 seconds during contest windows; switch to 5 seconds inside the last hour.
- Each row carries rank, score, displayName, isYou, and tieBreakRank for transparency.
- Always show the window label and end time. Without context, leaderboards confuse users.
Bracket view
The default surface
"use client";
import { useLeaderboard } from "@bricqs/headless-react";
export function MyBracket() {
const { rows, window: w, isLoading } = useLeaderboard({
id: "april_quiz_cup",
view: "bracket",
bracketSize: 7,
});
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">Your bracket</h3>
<span className="text-sm text-slate-500">
{w.label} · ends {w.endsAt}
</span>
</header>
<ol className="divide-y">
{rows.map((r) => (
<li
key={r.rank}
className={`flex items-center gap-3 py-2 ${r.isYou ? "bg-orange-50 -mx-3 px-3" : ""}`}
>
<span className="w-8 text-right tabular-nums text-slate-500">{r.rank}</span>
<span className="flex-1 font-medium">{r.displayName}</span>
<span className="tabular-nums">{r.score.toLocaleString()}</span>
</li>
))}
</ol>
</section>
);
}Top view
Combine bracket and global top
const top = useLeaderboard({ id: "april_quiz_cup", view: "top", limit: 10 });
const me = useLeaderboard({ id: "april_quiz_cup", view: "bracket", bracketSize: 5 });
// Render two sections side by sideSegmentation
Per-region or per-cohort views
useLeaderboard({
id: "april_quiz_cup",
view: "top",
limit: 50,
segment: { type: "region", value: "south-india" },
});Segment values are configured server-side. The hook does not validate; an unknown segment returns an empty list.
Common mistakes
What goes wrong
Showing only the global top. The middle 80 percent of users disengage.
Bracket view as primary, top view as secondary tab. The bracket is what motivates most participants.
Polling every 5 seconds for hours. Network panel and battery suffer.
Default 30 seconds. Tighten to 5 seconds only in the final hour of the window.
Highlighting the user only by name match. False positives when names collide.
Use isYou directly from the SDK row. It is bound to the participant token, not the displayName.
Hiding the window. Users do not know when scoring stops.
Always render w.label and w.endsAt. The most-asked support question is when does it end.
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.