---
id: "packages/active-charts/all-exports/chart-legend"
title: "Chart legend"
description: "ChartExportLegendItem, ChartExportLegendOptions, ChartInteractionSource, ChartLegend and 6 more: generated from the source of active-charts."
url: "/packages/active-charts/all-exports/chart-legend"
locale: "en"
revision: "g0mvjxwj5c-88bdbe1c:chart-legend"
---

# Chart legend

Exported by `@workspace/active-charts`. Generated from the package source; part of [the index of every export](/packages/active-charts/all-exports).

## Types

**ChartExportLegendItem**

```ts
type ChartExportLegendItem = Pick<
  ChartLegendEntry,
  'label' | 'key' | 'visible'
>;
```

One entry of an export legend: a legend entry's text, key and visibility,
so `useChartLegend().entries` passes as is. A hidden entry is drawn dimmed.
A token reference in a colour is resolved at the capture moment.

**ChartExportLegendOptions**

```ts
interface ChartExportLegendOptions {
  position?: 'top' | 'bottom' | 'left' | 'right';
  align?: 'start' | 'center' | 'end';
}
```

Where an export legend stands.

**ChartInteractionSource**

```ts
type ChartInteractionSource = 'pointer' | 'touch' | 'keyboard';
```

The input that started an interaction: a mouse or a pen (`pointer`), a
finger (`touch`, a pointer event whose `pointerType` is `'touch'`), or a
key.

**ChartLegend**

```ts
interface ChartLegend {
  readonly entries: readonly ChartLegendEntry[];
  readonly connected: boolean;
  activate(entryId: string, action?: ChartLegendAction): boolean;
  showAll(): boolean;
  readonly link: ChartLegendLink;
}
```

The headless legend of one chart (`useChartLegend()`).

**ChartLegendAction**

```ts
type ChartLegendAction = 'toggle' | 'isolate';
```

An action on one entry: `toggle` is a click on the chart's own entry (it
hides a visible target and shows a hidden one), `isolate` its double
click (isolating the entry that is already the only one shown shows all).

**ChartLegendChange**

```ts
interface ChartLegendChange {
  readonly action: 'hide' | 'show' | 'isolate' | 'show-all';
  readonly entryId: string | null;
  readonly target: ChartLegendTarget | null;
  readonly hidden: readonly ChartLegendTarget[];
  readonly source: ChartInteractionSource | 'api';
}
```

A legend change the chart applied.

**ChartLegendEntry**

```ts
interface ChartLegendEntry {
  readonly id: string;
  readonly target: ChartLegendTarget;
  readonly label: string;
  readonly key: ChartLegendKey;
  readonly visible: boolean;
  readonly available: {
    readonly toggle: boolean;
    readonly isolate: boolean;
    readonly showAll: boolean;
  };
}
```

One entry of a chart's discrete legend, as the chart resolves it.

**ChartLegendKey**

```ts
type ChartLegendKey =
  | {readonly kind: 'tile'; readonly color: string}
  | {
      readonly kind: 'line';
      readonly color: string;
      readonly dash?: readonly number[];
      readonly marker?: MarkerShape;
    }
  | {
      readonly kind: 'marker';
      readonly color: string;
      readonly shape: MarkerShape;
    }
  | {
      readonly kind: 'pair';
      readonly start: string;
      readonly end: string;
      readonly shape: MarkerShape;
    }
  | {readonly kind: 'neutral'};
```

How the chart's own legend keys an entry. `color` is the CSS colour the
package paints with: the host's colour, or a token reference such as
`var(--chart-3)`, which resolves wherever the host's tokens are in scope
(a token override scoped to the chart does not reach a legend rendered
outside it).

- `tile`: a filled square (a bar, a slice, a box).
- `line`: a stroke, with the series' dash pattern (its second encoding)
and the shape of the markers it draws.
- `marker`: a marker shape (a scatter, a lollipop, a dumbbell end).
- `pair`: the two ends of a dumbbell series side by side.
- `neutral`: a series that paints by role (waterfall, candlestick, OHLC)
has no one colour, and its key claims none.

**ChartLegendLink**

```ts
interface ChartLegendLink {
  readonly [chartLegendLinkBrand]: true;
}
```

Connects one chart to one `useChartLegend()`. Opaque and stable: give it
to exactly one chart as `legendLink`.

**ChartLegendTarget**

```ts
type ChartLegendTarget =
  | {readonly kind: 'series'; readonly seriesId: string}
  | {readonly kind: 'category'; readonly key: ChartItemKey};
```

What a legend entry hides and shows: a series, named in the selection
namespace (`ChartSeriesItemRef.seriesId`), or a category of a categorical
chart, named by its `categoryKey` value (the row position when the chart
names no `categoryKey`).