# Leaderboard

<figure><img src="/files/AvhEW6GdljMl1lNgpIsO" alt="" width="563"><figcaption></figcaption></figure>

## 🧭 Overview

A leaderboard shows ranking among categories. It consists of a series of bars representing a quantitative metric for comparable entities. This viz allows to quickly benchmark all entities.

> 📊 Example Use Case
>
> * Top-selling products or services
> * User activity rankings
> * Department or team performance comparison
> * Most accessed content or features
> * Metric-based competition or gamification tracking

## ⭐ Key Features

* **Categorize by Bars:** Helps compare subgroups independently within the same chart.
* **Order Bars Within Categories:** Enhances readability and comparison inside groupings.
* **Enable Drill-down:** Supports exploratory analysis without leaving the chart context.
* **Show Rank for Bars:** Makes positions explicit without relying solely on visual length.

## Configuration

{% tabs %}
{% tab title="New Leaderboard" %}
**Learn how to create a leaderboard using the new design with this step-by-step guide.**\
Explore the interactive walkthrough below to get started quickly, then dive into the full configuration reference table for in-depth details.

{% @arcade/embed url="<https://app.arcade.software/share/qNxsA4fdtJt4yQuaZRS1>" flowId="qNxsA4fdtJt4yQuaZRS1" %}

**Chart Configuration Step-by-Step**

|                           | Option                  | How does it work?                                                                                                                                                                                                                                                                                                                       |
| ------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Category**              |                         |                                                                                                                                                                                                                                                                                                                                         |
|                           | Bar category            | The bar category corresponds to a column in your dataset, such as 'Product Type'.                                                                                                                                                                                                                                                       |
|                           | Category by bars        | Organizes bars into separate categories or groupings, allowing segmented ranking.                                                                                                                                                                                                                                                       |
|                           | Enable drill-down       | Allows users to click on a bar to explore more detailed or related data.                                                                                                                                                                                                                                                                |
|                           | Show rank for bars      | Displays a numeric rank for each bar based on its value position.                                                                                                                                                                                                                                                                       |
| **Value**                 |                         |                                                                                                                                                                                                                                                                                                                                         |
|                           | Bar height              | The bar height represents a value from your dataset. You can select an aggregation method from the menu, which may vary depending on the chart type.                                                                                                                                                                                    |
|                           | Precision               | <p>Precision determines the level of detail in how your values are displayed. By default, measures use a <code>.2f</code> format, meaning they are shown with two decimal places.</p><p><strong>Example:</strong><br>A value of <code>3.14159</code> will be displayed as <code>3.14</code> when using <code>.2f</code> formatting.</p> |
|                           | Unit                    | Unit represents the total quantity or category being measured for a KPI. It defines what the values correspond to, providing context for better interpretation.                                                                                                                                                                         |
|                           | Sentiment               | <p>Four different sentiment statuses (positive, warning, negative, neutral) can be used to color bars, enhancing visual distinction.</p><p><em>Note: Sentiments can be customized in the app theme.</em></p>                                                                                                                            |
|                           | Reverse height order    | Inverts the direction of bar heights, so lower values appear higher or vice versa.                                                                                                                                                                                                                                                      |
| **Additional parameters** |                         |                                                                                                                                                                                                                                                                                                                                         |
|                           | ID                      | Unique chart Id                                                                                                                                                                                                                                                                                                                         |
|                           | Add complementary value | <p>The complementary value is displayed in the data label, providing additional context and making it easier for viewers to interpret the data at a glance. It is possible to add a precision, an unit and a sentiment.<br></p>                                                                                                         |
|                           | Add user chart guide    | Lead your chart viewers through the narrative of your data.                                                                                                                                                                                                                                                                             |
| **Chart performance**     |                         | Technical performance                                                                                                                                                                                                                                                                                                                   |

**Style Configuration**

|              | Option | How does it work?                                                |
| ------------ | ------ | ---------------------------------------------------------------- |
| **Bars**     |        |                                                                  |
|              | Bars   | Customize the bar color to align with your branding preferences. |
| {% endtab %} |        |                                                                  |

{% tab title="Legacy Leaderboard" %}
This page provides a step-by-step guide for creating a leaderboard using the legacy design.

<mark style="color:red;">\*</mark>**Mandatory parameters**

<table><thead><tr><th width="165.33333333333331">Section</th><th width="226">Option</th><th>Configuration Tutorial</th></tr></thead><tbody><tr><td></td><td>Dataset<mark style="color:red;">*</mark></td><td>Select the dataset used by the chart</td></tr><tr><td></td><td>Label<mark style="color:red;">*</mark></td><td>Your label of choice</td></tr><tr><td></td><td>Value<mark style="color:red;">*</mark></td><td>Your value of choice</td></tr><tr><td>Legend</td><td>Display Legend</td><td>Toggle the legend display</td></tr><tr><td>Legend</td><td>Additional Info</td><td>Display contextual in-depth info</td></tr><tr><td>Legend</td><td>Bar Selected By Default</td><td>Select a bar by default</td></tr><tr><td>Sort</td><td>Sort Bars</td><td>Select ascending or descending order</td></tr><tr><td>Sort</td><td>Display Rank For Sorted Bars</td><td>Display the rank of each sorted bars</td></tr><tr><td>Variation</td><td>Variation</td><td>Display a variation badge next to the value based on a column containing the variations</td></tr><tr><td>Variation</td><td>Variation Legend</td><td>Display a legend for your variation</td></tr><tr><td>Variation</td><td>Hide Empty Variation</td><td>Hide variation badge if the value is empty</td></tr><tr><td>Groups</td><td>Groups</td><td>Breakdown labels into groups based on a column containing the groups</td></tr><tr><td>Groups</td><td>Groups Order</td><td>Order group based on a column, on an advanced order or a custom order</td></tr><tr><td>Groups</td><td>Groups Additional Info</td><td>Add a legend to your groups</td></tr><tr><td>Groups</td><td>Recycle Groups Colors</td><td>Reuse groups colors when chart data changes (filters changes for example)</td></tr><tr><td>Packs</td><td>Packs</td><td>Group labels together based on a column</td></tr><tr><td>Packs</td><td>Display Pack Names</td><td>Display or not the packs names</td></tr><tr><td>Packs</td><td>Packs Order</td><td>Order pack based on a column, on an advanced order or a custom order</td></tr><tr><td>Drill</td><td>Drill</td><td>Click on labels and see children details</td></tr><tr><td>Drill</td><td>Drill Children Order</td><td>Order children based on a column, on an advanced order or a custom order</td></tr><tr><td>Enrich Chart</td><td>Average</td><td>Add a vertical average bar based on a value or a column</td></tr><tr><td>Enrich Chart</td><td>Average Legend</td><td>Display a legend for your average bar</td></tr><tr><td>Enrich Chart</td><td>Additional Values</td><td>Display additional values next to the main one (will not be displayed on mobile)</td></tr><tr><td>Enrich Chart</td><td>Target</td><td>Represent target but use it with caution as it is preferable to use the bullet tile to represent targets</td></tr><tr><td>Enrich Chart</td><td>Sparklines</td><td>See the Sparklines section</td></tr><tr><td>Display</td><td>Scale</td><td>Define the bars scale using two bounds</td></tr><tr><td>Display</td><td>Size</td><td>Define the chart size when having multiple ones</td></tr><tr><td>Display</td><td>Mobile Size</td><td>Define the chart size when having multiple ones on mobile</td></tr><tr><td>Display</td><td>Custom CSS Class</td><td>Set a custom CSS class to target this specific chart with CSS</td></tr><tr><td>Tutorial</td><td>ID</td><td><p>Enter an ID.</p><p>Change the ID to display the tutorial again.</p><p>All tutorials with the same ID will be displayed only once</p></td></tr><tr><td>Tutorial</td><td>Message</td><td>Enter your message | This will be displayed to your users</td></tr><tr><td>Tutorial</td><td>Always display this tutorial</td><td>By default the tutorial is shown once only</td></tr></tbody></table>
{% endtab %}

{% tab title="New vs. Legacy Configuration" %}

| **⭐️ New**                   | **Legacy**                   |
| ---------------------------- | ---------------------------- |
| **Bar category**             | Bars label                   |
| Order bars                   | Labels order                 |
| Categorize by bars           | Groups                       |
| Order bars within categories | Groups order                 |
| Reverse bar order            | /                            |
| Enable drill-down            | Drill                        |
| Show rank for bars           | Display rank for sorted bars |
| **Bar height**               | Bars value                   |
| **Line Y-Axis**              | Y axis                       |
| Reverse height order         | Sort bars                    |
| Add complementary value      | Additional info              |
| Add user chart guide         | Tutorial                     |
| {% endtab %}                 |                              |
| {% endtabs %}                |                              |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-v3.toucantoco.com/visualizations-and-layouts/creating-visualizations/viz-gallery/new-viz-designs/leaderboard.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.