---
id: "packages/active-charts/all-exports/selection"
title: "Selection"
description: "ChartCellItem, ChartCellItemRef, ChartItem, ChartItemKey and 12 more: generated from the source of active-charts."
url: "/packages/active-charts/all-exports/selection"
locale: "en"
revision: "g0mvjxwj5c-88bdbe1c:selection"
---

# Selection

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

## Types

**ChartCellItem**

```ts
interface ChartCellItem<TDatum = ChartDatum> extends ChartCellItemRef {
  datum: TDatum;
}
```

A heatmap cell as the chart reports it (T8): its row.

**ChartCellItemRef**

```ts
interface ChartCellItemRef {
  kind: 'cell';
  x: ChartItemKey;
  y: ChartItemKey;
}
```

A reference to a heatmap cell (T8): the values of its row's x and y
fields, compared like item keys (a `Date` and a number by time, a string
by its text), never by the text a gutter writes.

**ChartItem**

```ts
type ChartItem<TDatum = ChartDatum> =
  | ChartSeriesItem<TDatum>
  | ChartCellItem<TDatum>
  | ChartNodeItem
  | ChartLinkItem;
```

An item a chart draws, as it reports it to the host: one of the four forms
of {@link ChartItemRef} with its payload. Each chart reports only the forms
it draws, and its events are typed to them.

**ChartItemKey**

```ts
type ChartItemKey = string | number | Date;
```

The value that identifies an item within its series: the value of the
row's item-key field (`ChartSelectionOptions.itemKey`, the x key by
default). Strings match strings and numbers numbers; a `Date` matches a
`Date` (or a number) with the same time, so an instant can be named either
way. An ISO string does not match a `Date`.

**ChartItemRef**

```ts
type ChartItemRef =
  ChartSeriesItemRef | ChartCellItemRef | ChartNodeItemRef | ChartLinkItemRef;
```

A reference to one item: what a host stores, passes back as
`selectedItems`, and receives from `onSelectionChange`. One union across
the package (ADR-042, T8): an item of a series, a heatmap cell, a node or
a sankey link. A chart resolves the forms it draws and ignores the others,
so one host selection can be given to several charts. Narrow on `kind`
(absent on an item of a series) or on `'seriesId' in ref`.

**ChartLinkItem**

```ts
type ChartLinkItem<TLink = unknown> = ChartLinkItemRef & {
  source: string;
  target: string;
  link: TLink;
};
```

A sankey link as the chart reports it (T8): its ids and the host's link.

**ChartLinkItemRef**

```ts
type ChartLinkItemRef =
  | {kind: 'link'; id: string; source?: string; target?: string}
  | {kind: 'link'; id?: undefined; source: string; target: string};
```

A reference to a sankey link (T8). Its identity is the host's
`LinkDatum.id` when the link has one; otherwise its source and target node
ids, which name every link between those two nodes at once (parallel links
without ids are one item). The chart reports `id` when the link has one,
with `source` and `target` always.

**ChartNodeItem**

```ts
interface ChartNodeItem<TNode = unknown> {
  kind: 'node';
  id?: string;
  name: string;
  node: TNode;
  path?: readonly TNode[];
}
```

A node as the chart reports it (T8): the host's node object, its name, and
for a hierarchy leaf its path from the data's root (inclusive).

**ChartNodeItemRef**

```ts
interface ChartNodeItemRef {
  kind: 'node';
  id: string;
}
```

A reference to a node (T8): a treemap or sunburst leaf by its
`HierarchyNode.id`, a sankey node by its `NodeDatum.id`. The host's own
id; never a position in the tree or a label.

**ChartSelectionChange**

```ts
type ChartSelectionChange<
  TDatum = ChartDatum,
  TItem = ChartSeriesItem<TDatum>,
> =
  | {
      source: ChartInteractionSource;
      item: TItem;
      selected: boolean;
      requested: boolean;
    }
  | {
      source: 'update';
      removed: readonly ChartItemRef[];
      requested: false;
    };
```

What changed the selection, and how.

**ChartSelectionEvents**

```ts
interface ChartSelectionEvents<
  TDatum = ChartDatum,
  TItem = ChartSeriesItem<TDatum>,
> {
  onSelectionChange?: (
    selection: ChartItemRef[],
    change: ChartSelectionChange<TDatum, TItem>,
  ) => void;
  onItemActivate?: (item: TItem, source: ChartInteractionSource) => void;
}
```

The events of selection and activation. `TItem` is the item form the chart
draws: {@link ChartSeriesItem} on the Cartesian charts.

**ChartSelectionOptions**

```ts
interface ChartSelectionOptions {
  enabled?: boolean;
  mode?: 'single' | 'multiple';
  itemKey?: string;
}
```

Selection behaviour of a chart.

**ChartSelectionProps**

```ts
interface ChartSelectionProps<
  TDatum = ChartDatum,
  TItem = ChartSeriesItem<TDatum>,
  TOptions = ChartSelectionOptions,
>
  extends ChartSelectionState, ChartSelectionEvents<TDatum, TItem> {
  selection?: FeatureOption<TOptions>;
}
```

Selection props of a chart: the behaviour (`selection`), the state, and the
events. `TOptions` narrows the behaviour where a family has no item key to
choose (heatmap, treemap, sunburst, sankey).

**ChartSelectionState**

```ts
interface ChartSelectionState {
  selectedItems?: readonly ChartItemRef[];
  defaultSelectedItems?: readonly ChartItemRef[];
}
```

The selection state a host owns (controlled) or seeds (uncontrolled).

**ChartSeriesItem**

```ts
interface ChartSeriesItem<
  TDatum = ChartDatum,
> extends ChartSeriesItemRef {
  seriesName: string;
  datum: TDatum;
  interval?: {start: number; end: number; count: number};
}
```

An item of a series, as the chart reports it. For a grouped chart the item
is the displayed bucket: `datum` is the bucket row and `interval` names the
source rows it summarises (W4).

**ChartSeriesItemRef**

```ts
interface ChartSeriesItemRef {
  kind?: 'series';
  seriesId: string;
  key: ChartItemKey;
  interval?: {start: number; end: number};
}
```

A reference to an item of a series: a Cartesian mark (a point, a bar, a
glyph), a radar vertex, or a slice, stage, bar or sector of a categorical
chart (T8). The form ADR-042 introduced; `kind` is optional and absent on
every reference a chart reports.