# Leaderboard (goodtabs UI)

Ranked rows with a rank, a name and a value in tabular figures.

## Install

```bash
npx shadcn@latest add https://ui.goodtabs.co/r/leaderboard.json
```

Or, with the @goodtabs namespace configured in components.json: `npx shadcn@latest add @goodtabs/leaderboard`

## Usage

```tsx
import { Leaderboard } from "@/components/ui/leaderboard"

<Leaderboard entries={entries} unit="points" highlight={3} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| entries | `{ name: string; value: string; detail?: string }[]` |  | Rows in rank order, best first. |
| unit | `string` |  | Read after each value by screen readers. |
| highlight | `number` |  | One-based rank to fill, for the viewer's own row. |

## When to use

- Top lists by installs, points or views
- Short rankings next to a stat or a chart

## When not to use

- Long sortable data: use a table
- Trends over time: use a chart

## Notes for agents

- Entries must already be sorted; rank is the position
- It renders an ordered list, so the rank number is hidden from screen readers and the list order carries it
- Format the value before passing it
- Server component: no state, no handlers

Docs: https://ui.goodtabs.co/components/leaderboard