# Legend

> A legend labels the series of a chart or a progress bar with a colored marker, a name and an optional value.

Label chart series with colored markers. Group legend items in a list, add values, and let users toggle series on click.

Source: https://docs.tabler.io/ui/components/legend

---

## Legend marker

A `legend-dot` is a small square in the color of a series. Use it on its own next to a label. Set the color with a `legend-{color}` class. Full list of available colors can be found in the [Colors](/ui/base/colors) section.

```html
<span class="legend-dot legend-blue"></span>
<span class="legend-dot legend-azure"></span>
<span class="legend-dot legend-indigo"></span>
<span class="legend-dot legend-purple"></span>
<span class="legend-dot legend-pink"></span>
<span class="legend-dot legend-red"></span>
<span class="legend-dot legend-orange"></span>
<span class="legend-dot legend-yellow"></span>
<span class="legend-dot legend-lime"></span>
<span class="legend-dot legend-green"></span>
<span class="legend-dot legend-teal"></span>
<span class="legend-dot legend-cyan"></span>
```

## Legend item

Wrap the marker and the label in a `legend`. Put the color class on the item, so the marker and the hover background share it. Add a `legend-value` for a number next to the label.

```html
<div class="legend-list">
  <span class="legend legend-blue">
    <span class="legend-dot"></span> Allowed <span class="legend-value">339.0k</span>
  </span>
  <span class="legend legend-red">
    <span class="legend-dot"></span> Denied <span class="legend-value">1.2k</span>
  </span>
  <span class="legend legend-orange">
    <span class="legend-dot"></span> Challenged <span class="legend-value">815</span>
  </span>
</div>
```

## Interactive legend

Use a `button` or a link when clicking an item should toggle a series. The item gets a tinted background on hover, mixed from the series color. Add `active` to keep it, and `legend-off` to mark a hidden series.

```html
<div class="legend-list">
  <button type="button" class="legend legend-blue">
    <span class="legend-dot"></span> Allowed <span class="legend-value">339.0k</span>
  </button>
  <button type="button" class="legend legend-purple active">
    <span class="legend-dot"></span> Logged <span class="legend-value">-</span>
  </button>
  <button type="button" class="legend legend-teal legend-off">
    <span class="legend-dot"></span> Rate limited <span class="legend-value">-</span>
  </button>
</div>
```

With ApexCharts, hide the built-in legend and call `toggleSeries` with the series name:

```html
<button type="button" class="legend legend-blue" data-series="Allowed">
  <span class="legend-dot"></span> Allowed
</button>
```

```js
document.querySelectorAll('.legend').forEach((item) => {
  item.addEventListener('click', () => {
    chart.toggleSeries(item.dataset.series)
    item.classList.toggle('legend-off')
  })
})
```

## Vertical list

Add `legend-list-vertical` to stack the items, for example next to a donut chart.

```html
<div class="legend-list legend-list-vertical">
  <span class="legend legend-primary">
    <span class="legend-dot"></span> This year <span class="legend-value">$92,400</span>
  </span>
  <span class="legend legend-secondary">
    <span class="legend-dot"></span> Last year <span class="legend-value">$84,300</span>
  </span>
  <span class="legend">
    <span class="legend-dot"></span> Forecast <span class="legend-value">$98,000</span>
  </span>
</div>
```

## Large legend

Add `legend-lg` to put the label on the first line and a big value below it. Wrap the unit in a `legend-unit`. Add `legend-list-divided` to the list to draw a line between the items. This size works well above a chart, where the legend also shows the key numbers.

```html
<div class="legend-list legend-list-divided">
  <span class="legend legend-lg legend-primary">
    <span class="legend-dot"></span> P99 <span class="legend-value">124 <span class="legend-unit">ms</span>
    </span>
  </span>
  <span class="legend legend-lg legend-azure">
    <span class="legend-dot"></span> P95 <span class="legend-value">76 <span class="legend-unit">ms</span>
    </span>
  </span>
  <span class="legend legend-lg legend-green">
    <span class="legend-dot"></span> P75 <span class="legend-value">32 <span class="legend-unit">ms</span>
    </span>
  </span>
  <span class="legend legend-lg legend-yellow legend-off">
    <span class="legend-dot"></span> Requests <span class="legend-value">1,234</span>
  </span>
</div>
```

### Above a chart

Put the large items above a chart to show the latest value of each series. Turn off the chart's own legend, because the items already name the series.

```html
<div class="card">
  <div class="card-body">
    <div class="legend-list legend-list-divided mb-3">
      <span class="legend legend-lg legend-primary">
        <span class="legend-dot"></span> P99 <span class="legend-value">124 <span class="legend-unit">ms</span>
        </span>
      </span>
      <span class="legend legend-lg legend-azure">
        <span class="legend-dot"></span> P95 <span class="legend-value">76 <span class="legend-unit">ms</span>
        </span>
      </span>
      <span class="legend legend-lg legend-green">
        <span class="legend-dot"></span> P75 <span class="legend-value">32 <span class="legend-unit">ms</span>
        </span>
      </span>
      <span class="legend legend-lg legend-yellow">
        <span class="legend-dot"></span> P50 <span class="legend-value">10 <span class="legend-unit">ms</span>
        </span>
      </span>
    </div>
    <div id="chart-legend-latency-docs" class="position-relative" role="img" aria-label="Read latency by percentile"></div>
    <style>
      :root {
        --chart-legend-latency-docs-color-0: color-mix(in srgb, transparent, var(--tblr-primary) 100%);
        --chart-legend-latency-docs-color-1: color-mix(in srgb, transparent, var(--tblr-azure) 100%);
        --chart-legend-latency-docs-color-2: color-mix(in srgb, transparent, var(--tblr-green) 100%);
        --chart-legend-latency-docs-color-3: color-mix(in srgb, transparent, var(--tblr-yellow) 100%);
      }
    </style>
  </div>
</div>
```

### Large links

Large items work as links and buttons too, for example as filters above a list. Add `active` to mark the current item and `legend-off` for a hidden one.

```html
<div class="legend-list legend-list-divided">
  <a href="#" class="legend legend-lg legend-green active">
    <span class="legend-dot"></span> Passed <span class="legend-value">128</span>
  </a>
  <a href="#" class="legend legend-lg legend-red">
    <span class="legend-dot"></span> Failed <span class="legend-value">4</span>
  </a>
  <a href="#" class="legend legend-lg legend-yellow">
    <span class="legend-dot"></span> Skipped <span class="legend-value">12</span>
  </a>
  <a href="#" class="legend legend-lg legend-secondary legend-off">
    <span class="legend-dot"></span> Pending <span class="legend-value">3</span>
  </a>
</div>
```

## Variables

Use these SCSS variables to customize legends. The default values are:

```scss
$legend-margin-bottom: 0.5rem;
$legend-font-size: 1.5rem;
$legend-font-weight: null;
$legend-bg: var(--border-color);
$legend-size: 0.5rem;
$legend-border-radius: var(--border-radius-pill);
$legend-gap: 0.5rem;
$legend-padding-y: 0.375rem;
$legend-padding-x: 0.75rem;
$legend-list-gap: 0.25rem 1rem;
$legend-list-gap-interactive: 0.25rem;
$legend-lg-min-width: 9rem;
$legend-lg-value-font-size: $h2-font-size;
```

_Source: `core/scss/_variables.scss`_
