> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudj.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Leaderboards

> Configure competitive rankings with multi-language support, disabled-state visibility, and distribution configs

Leaderboards turn accumulated XP (or challenge completions, streaks, custom events) into competitive rankings. Members see where they stand; admins configure what gets ranked and how.

## Creating a leaderboard

Top nav -> **+ New -> Leaderboard**.

<Steps>
  <Step title="Basic info" icon="pen">
    Name, description, icon. Rendering was stabilised in #781 so multi-column layouts don't flicker.
  </Step>

  <Step title="Ranking criteria" icon="scale-balanced">
    Pick the metric that ranks members:

    * **XP earned** (total or in a window)
    * **Challenges completed**
    * **Streak length**
    * **Custom event count**
  </Step>

  <Step title="Window" icon="calendar">
    Rolling window for the ranking:

    * **All time** — cumulative forever.
    * **Monthly / weekly / daily** — resets automatically.
    * **Custom range** — fixed start/end.
  </Step>

  <Step title="Distribution (rewards)" icon="gift">
    Attach rewards to top N positions. Distribution configs let you tier — different rewards for #1, #2-5, #6-10 etc. Avoids reward-save duplication bug (#1070).

    **Bonus XP defaults to 0** (#688) — set it explicitly if you want it to fire.
  </Step>

  <Step title="Visibility" icon="eye">
    * **Language** — per-locale titles/descriptions (#1062).
    * **Disabled state** — disabled leaderboards still show in admin lists (#1650) so you can re-enable without hunting.
  </Step>
</Steps>

***

## Language support

Leaderboards fully support multi-language (#1062). Edit the title, description, and reward copy per locale. Members see the leaderboard in their chosen language.

***

## Dynamic count

The leaderboard row count is **not hardcoded** (#1376) — configure how many positions display (top 10, 25, 50, 100). Members outside the displayed range still accumulate rank, they just don't render in the list.

***

## Name input focus

The name input field retains focus properly (#2230) — you can type the full name without re-clicking after each keystroke (this used to be a pain point on longer names).

***

## Disabled leaderboards

Turn off a leaderboard without deleting it — the **disabled state** keeps the config safe but hides it from members. Disabled boards still show in the admin list (#1650) so you can flip them back on.

***

## Patterns

<AccordionGroup>
  <Accordion title="Monthly XP top-10" icon="calendar">
    Metric: total XP, window: monthly. Rewards: tiered (big for #1, medium for #2-5, small for #6-10). Resets on the 1st of each month.
  </Accordion>

  <Accordion title="All-time streak kings" icon="fire">
    Metric: longest streak, window: all-time. Rewards: one big badge for #1, smaller badges for #2-10.
  </Accordion>

  <Accordion title="Weekly challenge leader" icon="trophy">
    Metric: challenges completed, window: weekly. Rewards: reward entries (giveaway tickets) for top 20.
  </Accordion>

  <Accordion title="Loyalty-tier leaderboards" icon="ranking-star">
    Separate leaderboards per [loyalty tier](/admin-guide/rewards/loyalty-tiers) so Bronze members compete with Bronze, Gold with Gold — healthier competition than a single mixed board.
  </Accordion>
</AccordionGroup>

***

## Sidebar fix note

Leaderboard studio sidebar was previously broken (#2239). If you're on a very old admin build and see rendering issues, force-refresh or clear the Turbopack cache.

***

## API

* `GET /admin/leaderboards` — list
* `POST /admin/leaderboards` — create
* `PATCH /admin/leaderboards/:id` — update
* `GET /admin/leaderboards/:id/distribution-events` — distribution configs

See the [Admin API reference](/api-reference/admin).