# Chart Legend

> A chart's key: a swatch, a name and a value per series. Rows can toggle their series.

Source: https://ngwr.dev/charts/chart-legend  
Added in v15.1

## Installation

Import the class, and `@use` the entry point in your global styles: without it the component renders unstyled.

```typescript
import { Component } from '@angular/core';
import { WrChartLegend } from 'ngwr/charts/chart-legend';

@Component({ imports: [WrChartLegend] })
export class MyComponent {}
```

```scss
@use 'ngwr/charts/chart-legend';
```

## Basic

It sits on a `<ul>` and renders the rows. Use it for a key several charts share; the bar, line, donut, meter group, scatter and radar charts draw their own legends with it.

```angular-html
<ul
  wr-chart-legend
  [items]="[
    { label: 'Direct', color: 'var(--wr-color-primary)', value: '4,812' },
    { label: 'Search', color: 'var(--wr-color-success)', value: '3,206' }
  ]"
></ul>
```

## Lines and markers

`dash` draws the key as a line, `marker` as a shape. Both put the shape on the line.

```angular-html
<ul
  wr-chart-legend
  [items]="[
    { label: 'Dashed line', color: 'var(--wr-color-success)', dash: '7 4' },
    { label: 'Triangle', color: 'var(--wr-color-danger)', marker: 'triangle' },
    { label: 'Line with points', color: 'var(--wr-color-on-surface-muted)', dash: '2 3', marker: 'diamond' }
  ]"
></ul>
```

## Toggle series

`toggleable` makes each row a toggle button. `hiddenSeries` holds the positions of the hidden series.

```angular-html
<ul wr-chart-legend toggleable [items]="items" [(hiddenSeries)]="hidden"></ul>

@for (metric of metrics; track $index) {
  @if (!hidden().includes($index)) {
    <wr-sparkline [data]="metric.data" [color]="metric.color" [ariaLabel]="metric.label" />
  }
}
```

```angular-ts
hidden = signal<readonly number[]>([]);
```

## Accessibility

| Part | Behaviour |
| --- | --- |
| Key | Hidden from screen readers. The row's text is its name. |
| Toggle row | A `<button aria-pressed>`. Pressed means shown. |
| Keyboard | `Tab` moves between rows. `Space` or `Enter` toggles. |
| Hidden series | Struck through as well as muted, so the state does not rest on colour. |
| Name | A toggleable list is named "Toggle series visibility". `ariaLabel` replaces it. |

## API

| Name | Description | Type | Default |
| --- | --- | --- | --- |
| `items` | One row per series, in the chart's order. | `readonly WrChartLegendItem[]` | `[]` |
| `toggleable` | Make each row a toggle button that shows and hides its series, through `hiddenSeries` and `toggled`. | `boolean` | `false` |
| `hiddenSeries` | The positions in `items` of the series that are hidden, ascending. Positions rather than labels: two series may share a label, and a label translated into another language would no longer match the one it hid. A position past the end of `items` is kept and ignored, so a series coming back finds its state. Written by a click on a `toggleable` row; read in either mode, so a legend that does not toggle still shows a series hidden from elsewhere as hidden. | `readonly number[]` | `[]` |
| `ariaLabel` | Accessible name of the list. A `toggleable` legend falls back to `chartLegend.toggleLabel` ("Toggle series visibility"), which tells a reader what its buttons do; one that does not toggle has no name unless given one. | `string \| null` | `null` |
| `(toggled)` | Emits when a reader shows or hides a series from a `toggleable` legend, after `hiddenSeries` moves. | `WrChartLegendToggle` | — |

## Types

```angular-ts
interface WrChartLegendItem {
  label: string;
  color: string;
  value?: string | null;
  marker?: WrChartMarker;
  dash?: string;
}

type WrChartMarker = 'circle' | 'square' | 'triangle' | 'diamond' | 'cross' | 'triangle-down';

interface WrChartLegendToggle {
  index: number;
  label: string;
  hidden: boolean;
}
```

| Name | Description | Type | Default |
| --- | --- | --- | --- |
| `WrChartLegendItem` | One row of the legend. | `interface` | — |
| `label`required | The series' name, and the toggle's name. | `string` | — |
| `color`required | Any CSS colour. Fills a dot or a marker, strokes a line. | `string` | — |
| `value` | Printed after the label, muted, as given. No value element when left out. | `string \| null` | `undefined` |
| `marker` | Draws the key as this shape. With `dash`, the shape sits on the line. | `WrChartMarker` | `undefined` |
| `dash` | Draws the key as a line in this `stroke-dasharray`. `''` is solid. | `string` | `undefined` |
| `WrChartLegendToggle` | What `(toggled)` emits. | `interface` | — |
| `index`required | The row's position in `items`. | `number` | — |
| `label`required | The row's label. Labels can repeat, so key on `index`. | `string` | — |
| `hidden`required | Whether the series is hidden now. | `boolean` | — |

## CSS variables

Set these on the component's selector or a wrapper, not on `:root`: the defaults are declared on `ngwr/charts/chart-legend`'s own element.

| Variable | Default | Declared on |
| --- | --- | --- |
| `--wr-chart-legend-color` | `var(--wr-color-on-surface)` | `:where(.wr-chart-legend)` |
| `--wr-chart-legend-dot-size` | `0.625rem` | `:where(.wr-chart-legend)` |
| `--wr-chart-legend-font-size` | `var(--wr-text-xs)` | `:where(.wr-chart-legend)` |
| `--wr-chart-legend-gap-x` | `var(--wr-space-lg)` | `:where(.wr-chart-legend)` |
| `--wr-chart-legend-gap-y` | `var(--wr-space-sm)` | `:where(.wr-chart-legend)` |
| `--wr-chart-legend-hidden-color` | `var(--wr-color-on-surface-muted)` | `:where(.wr-chart-legend)` |
| `--wr-chart-legend-hidden-swatch-opacity` | `0.35` | `:where(.wr-chart-legend)` |
| `--wr-chart-legend-item-gap` | `var(--wr-space-sm)` | `:where(.wr-chart-legend)` |
| `--wr-chart-legend-label-font-weight` | `inherit` | `:where(.wr-chart-legend)` |
| `--wr-chart-legend-marker-size` | `0.75rem` | `:where(.wr-chart-legend)` |
| `--wr-chart-legend-toggle-hover-bg` | `var(--wr-color-hover)` | `:where(.wr-chart-legend)` |
| `--wr-chart-legend-toggle-min-height` | `1.5rem` | `:where(.wr-chart-legend)` |
| `--wr-chart-legend-toggle-padding-x` | `var(--wr-space-xs)` | `:where(.wr-chart-legend)` |
| `--wr-chart-legend-toggle-radius` | `var(--wr-border-radius-sm)` | `:where(.wr-chart-legend)` |
| `--wr-chart-legend-value-color` | `var(--wr-color-on-surface-muted)` | `:where(.wr-chart-legend)` |

## Dependencies

| Used by | [Bar Chart](https://ngwr.dev/charts/bar-chart), [Donut Chart](https://ngwr.dev/charts/donut-chart), [Line Chart](https://ngwr.dev/charts/line-chart), [Meter Group](https://ngwr.dev/charts/meter-group), [Radar Chart](https://ngwr.dev/charts/radar-chart), [Scatter Chart](https://ngwr.dev/charts/scatter-chart) |
| --- | --- |

## See also

- [Line Chart](https://ngwr.dev/charts/line-chart) — One or more series of values as lines or as an area chart, overlaid or stacked.
- [Bar Chart](https://ngwr.dev/charts/bar-chart) — Bars for one or several series, grouped or stacked, standing up or lying along a row, with lines over them.
- [Donut Chart](https://ngwr.dev/charts/donut-chart) — Parts of a whole as a ring or a pie.
- [Meter Group](https://ngwr.dev/charts/meter-group) — One bar split into labelled parts, with a legend.
- [Scatter Chart](https://ngwr.dev/charts/scatter-chart) — Points on two numeric axes.
- [Radar Chart](https://ngwr.dev/charts/radar-chart) — Several series compared across the same axes, as polygons on a polar grid or as polar-area wedges.
- [Sparkline](https://ngwr.dev/charts/sparkline) — A small trend line with no axes, to sit beside a number.