# Leaderboard

<figure><img src="https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-b442d1f56becc4eb99875743c5d73238adad5d6e%2Fillustration_leaderboard_NEW.png?alt=media" 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 %}                |                              |