ComponentAdded in v15.1

Chart Legend

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

Installation

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

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

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

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.

<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>
  • Direct4,812
  • Search3,206
  • Social1,157
  • Referral644

Lines and markers

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

<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>
  • Solid line
  • Dashed line
  • Square
  • Triangle
  • Line with points

Toggle series

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

<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" />
  }
}
hidden = signal<readonly number[]>([]);

Accessibility

PartBehaviour
KeyHidden from screen readers. The row's text is its name.
Toggle rowA <button aria-pressed>. Pressed means shown.
KeyboardTab moves between rows. Space or Enter toggles.
Hidden seriesStruck through as well as muted, so the state does not rest on colour.
NameA toggleable list is named "Toggle series visibility". ariaLabel replaces it.

API

NameDescriptionTypeDefault
itemsOne row per series, in the chart's order.readonly WrChartLegendItem[][]
toggleableMake each row a toggle button that shows and hides its series, through hiddenSeries and toggled.booleanfalse
hiddenSeriesThe 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[][]
ariaLabelAccessible 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 | nullnull
(toggled)Emits when a reader shows or hides a series from a toggleable legend, after hiddenSeries moves.WrChartLegendToggle—

Types

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;
}
NameDescriptionTypeDefault
WrChartLegendItemOne row of the legend.interface—
labelrequiredThe series' name, and the toggle's name.string—
colorrequiredAny CSS colour. Fills a dot or a marker, strokes a line.string—
valuePrinted after the label, muted, as given. No value element when left out.string | nullundefined
markerDraws the key as this shape. With dash, the shape sits on the line.WrChartMarkerundefined
dashDraws the key as a line in this stroke-dasharray. '' is solid.stringundefined
WrChartLegendToggleWhat (toggled) emits.interface—
indexrequiredThe row's position in items.number—
labelrequiredThe row's label. Labels can repeat, so key on index.string—
hiddenrequiredWhether 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.

VariableDefaultDeclared on
--wr-chart-legend-colorvar(--wr-color-on-surface):where(.wr-chart-legend)
--wr-chart-legend-dot-size0.625rem:where(.wr-chart-legend)
--wr-chart-legend-font-sizevar(--wr-text-xs):where(.wr-chart-legend)
--wr-chart-legend-gap-xvar(--wr-space-lg):where(.wr-chart-legend)
--wr-chart-legend-gap-yvar(--wr-space-sm):where(.wr-chart-legend)
--wr-chart-legend-hidden-colorvar(--wr-color-on-surface-muted):where(.wr-chart-legend)
--wr-chart-legend-hidden-swatch-opacity0.35:where(.wr-chart-legend)
--wr-chart-legend-item-gapvar(--wr-space-sm):where(.wr-chart-legend)
--wr-chart-legend-label-font-weightinherit:where(.wr-chart-legend)
--wr-chart-legend-marker-size0.75rem:where(.wr-chart-legend)
--wr-chart-legend-toggle-hover-bgvar(--wr-color-hover):where(.wr-chart-legend)
--wr-chart-legend-toggle-min-height1.5rem:where(.wr-chart-legend)
--wr-chart-legend-toggle-padding-xvar(--wr-space-xs):where(.wr-chart-legend)
--wr-chart-legend-toggle-radiusvar(--wr-border-radius-sm):where(.wr-chart-legend)
--wr-chart-legend-value-colorvar(--wr-color-on-surface-muted):where(.wr-chart-legend)

Dependencies

See also