Scene

Parameters

name string

SVG element name, e.g. circle, g or text

attributes Record<string, AttrValue | undefined | null>

Attributes; undefined and null values are skipped

className string

Space-separated class names

meta RoleMeta<R>

Role, data context and key of the node

Returns

Example

import { lineChart, node } from 'chartist';

// Circles instead of the line chart's points.
lineChart(
  '#chart',
  { series: [[1, 3, 2, 4]] },
  {
    plugins: [
      {
        name: 'circles',
        install(chart) {
          chart.on('compose', current => {
            if (current.role !== 'point') {
              return;
            }
            const { x, y } = current.ctx;
            return node('circle', { cx: x, cy: y, r: 5 }, 'ct-circle', {
              role: 'point',
              ctx: current.ctx,
              key: current.key
            });
          });
        }
      }
    ]
  }
);

Parameters

scene SceneNode

The root of the tree to search, e.g. the scene payload

query NodeQuery & { readonly role: R }

The fields to match; without one, every node matches

Example

import { barChart, findAll } from 'chartist';

barChart(
  '#chart',
  { labels: ['Q1', 'Q2', 'Q3', 'Q4'], series: [[5, 4, 3, 7]] },
  {
    plugins: [
      {
        name: 'log-bars',
        install(chart) {
          chart.on('scene', ({ scene }) => {
            for (const bar of findAll(scene, { role: 'bar' })) {
              console.log(bar.key, bar.ctx.value, bar.ctx.y2);
            }
          });
        }
      }
    ]
  }
);

Parameters

scene SceneNode

The root of the tree to map

mapper (current: SceneNode) => void | SceneNode | null | undefined

Called once per node, with the node's mapped children

Returns

Example

import {
  autoScaleAxis,
  axisGrid,
  cartesianAxes,
  line,
  mapNodes,
  renderToString,
  stepAxis,
  toScene
} from 'chartist';

const labels = ['Mon', 'Tue', 'Wed'];
const scene = toScene(
  {
    data: { labels, series: [[1, 3, 2]] },
    axes: cartesianAxes([
      { id: 'x', side: 'bottom', type: stepAxis(), ticks: labels },
      { id: 'y', side: 'left', type: autoScaleAxis() }
    ]),
    layers: [axisGrid(), line()]
  },
  { width: 600, height: 300 }
);

// No grid lines, and the points marked for the stylesheet.
const mapped = mapNodes(scene, current => {
  if (current.role === 'grid') {
    return null;
  }
  if (current.role === 'point') {
    return current.addClass('is-marked');
  }
});
const markup = mapped ? renderToString(mapped) : '';

Properties

readonly seriesIndex? number

The index of the series the node belongs to. With it, the node gets a key and findAll can find it by series.

readonly valueIndex? number

The index of the value in its series the node stands for.

readonly value? unknown

The value the node stands for.

readonly meta? unknown

The meta of the value or series, as given in the data.

Properties

readonly key? string

A stable id, e.g. 0/1/3 (layer, series, value).

readonly role? keyof NodeRoles

What the node draws, e.g. point or bar: a key of NodeRoles.

readonly ctx? object

The node's data: what its role declares, or anything for plain nodes.

Properties

readonly name string

SVG element name, e.g. g, path, line.

readonly attrs Readonly<Record<string, AttrValue>>

The element's attributes, without class. Names with a ct: prefix (ct:value, ct:meta) are written in the Chartist namespace.

readonly classes readonly string[]

The element's class names, each once, in the order they were added.

readonly children readonly SceneNode[]

The child nodes, in document order.

readonly content? string

Text content, set with text().

readonly key? string

A stable id that survives updates. The pipeline keys data nodes that have none: layer/series/value for a value's node (e.g. 0/1/3), layer/series for a series' node.

Properties

attr (attributes: Record<string, AttrValue | undefined | null>) => this

Sets attributes; undefined or null removes one.

addClass (names: string) => this

Adds space-separated class names that aren't present yet.

removeClass (names: string) => this

Removes space-separated class names.

append (child: SceneNode, insertFirst?: boolean) => this

Adds a child at the end, or at the start with insertFirst.

remove (child: SceneNode) => this

Removes a direct child (by identity).

replace (child: SceneNode, next: SceneNode) => this

Replaces a direct child (by identity).

text (content: string) => this

Sets the text content.

empty () => this

Removes all children and text content.

Properties

readonly name string

SVG element name, e.g. g, path, line.

readonly attrs Readonly<Record<string, AttrValue>> & NodeRoles[R]['attrs']

The element's attributes, typed as the built-in layers set them; attr() can change them.

readonly classes readonly string[]

The element's class names, each once, in the order they were added.

readonly children readonly SceneNode[]

The child nodes, in document order.

readonly content? string

Text content, set with text().

readonly key? string

A stable id that survives updates. The pipeline keys data nodes that have none: layer/series/value for a value's node (e.g. 0/1/3), layer/series for a series' node.

attr (attributes: Record<string, AttrValue | undefined | null>) => this

Sets attributes; undefined or null removes one.

addClass (names: string) => this

Adds space-separated class names that aren't present yet.

removeClass (names: string) => this

Removes space-separated class names.

append (child: SceneNode, insertFirst?: boolean) => this

Adds a child at the end, or at the start with insertFirst.

remove (child: SceneNode) => this

Removes a direct child (by identity).

replace (child: SceneNode, next: SceneNode) => this

Replaces a direct child (by identity).

text (content: string) => this

Sets the text content.

empty () => this

Removes all children and text content.

readonly role R

What the node draws, e.g. point.

readonly ctx NodeRoles[R]['ctx'] & { readonly seriesIndex?: number; readonly valueIndex?: number }

The node's data, as its role declares it. seriesIndex and valueIndex read as number | undefined on any node, declared or not.

Properties

readonly name string

SVG element name, e.g. g, path, line.

readonly attrs Readonly<Record<string, AttrValue>>

The element's attributes, without class. Names with a ct: prefix (ct:value, ct:meta) are written in the Chartist namespace.

readonly classes readonly string[]

The element's class names, each once, in the order they were added.

readonly children readonly SceneNode[]

The child nodes, in document order.

readonly content? string

Text content, set with text().

readonly key? string

A stable id that survives updates. The pipeline keys data nodes that have none: layer/series/value for a value's node (e.g. 0/1/3), layer/series for a series' node.

attr (attributes: Record<string, AttrValue | undefined | null>) => this

Sets attributes; undefined or null removes one.

addClass (names: string) => this

Adds space-separated class names that aren't present yet.

removeClass (names: string) => this

Removes space-separated class names.

append (child: SceneNode, insertFirst?: boolean) => this

Adds a child at the end, or at the start with insertFirst.

remove (child: SceneNode) => this

Removes a direct child (by identity).

replace (child: SceneNode, next: SceneNode) => this

Replaces a direct child (by identity).

text (content: string) => this

Sets the text content.

empty () => this

Removes all children and text content.

readonly role? undefined

Always absent: plain nodes have no role.

readonly ctx? NodeContext

Data you attach to the node, if any.

Properties

readonly role R

The node's role, e.g. point.

readonly key? string

A stable id; the pipeline sets one for data nodes that have none.

Properties

readonly x number

Px from the left edge of the SVG.

readonly y number

Px from the top edge of the SVG.

Properties

readonly seriesIndex? undefined

Always absent: the node belongs to no series.

readonly valueIndex? undefined

Always absent: the node stands for no value.

Properties

readonly series unknown

The series as given in the data (array, or object with data).

readonly seriesIndex number

The series' index in the chart's data, across layers.

readonly meta unknown

The series' meta, if it's a series object with one.

Properties

readonly series unknown

The series as given in the data (array, or object with data).

readonly seriesIndex number

The series' index in the chart's data, across layers.

readonly meta unknown

The series' meta, if it's a series object with one.

readonly valueIndex? undefined

Always absent: the group stands for the whole series.

Properties

readonly valueIndex number

The value's index in its series, from 0.

readonly value NormalizedSeriesPrimitiveValue

The normalized value: a number, { x, y } numbers, or a hole.

Properties

readonly x number

Px from the left edge of the SVG.

readonly y number

Px from the top edge of the SVG.

readonly series unknown

The series as given in the data (array, or object with data).

readonly seriesIndex number

The series' index in the chart's data, across layers.

readonly meta unknown

The series' meta, if it's a series object with one.

readonly valueIndex number

The value's index in its series, from 0.

readonly value NormalizedSeriesPrimitiveValue

The normalized value: a number, { x, y } numbers, or a hole.

Properties

readonly series unknown

The series as given in the data (array, or object with data).

readonly seriesIndex number

The series' index in the chart's data, across layers.

readonly meta unknown

The series' meta, if it's a series object with one.

readonly valueIndex number

The value's index in its series, from 0.

readonly value NormalizedSeriesPrimitiveValue

The normalized value: a number, { x, y } numbers, or a hole.

readonly x1 number

The X of the bar's base, in px.

readonly y1 number

The Y of the bar's base, in px.

readonly x2 number

The X of the bar's end (the value), in px.

readonly y2 number

The Y of the bar's end (the value), in px.

Properties

readonly series unknown

The series as given in the data (array, or object with data).

readonly seriesIndex number

The series' index in the chart's data, across layers.

readonly meta unknown

The series' meta, if it's a series object with one.

readonly valueIndex? undefined

Always absent: the path stands for the whole series.

readonly values NormalizedSeries

All values of the series.

readonly path SvgPath

The path as drawn (a copy, safe to change).

Properties

readonly series unknown

The series as given in the data (array, or object with data).

readonly seriesIndex number

The series' index in the chart's data, across layers.

readonly meta unknown

The series' meta, if it's a series object with one.

readonly value number

The slice's value.

readonly valueIndex 0

Always 0: a slice's series has one value.

readonly index number

Same as seriesIndex, as in 1.x draw events.

readonly totalDataSum number

The sum of all slices (or the total option).

readonly path SvgPath

The slice's outline as drawn (a copy, safe to change).

readonly center Point

The center of the pie, in px in the SVG.

readonly radius number

The pie's radius in px (for a donut, to the middle of its ring).

readonly startAngle number

Where the slice starts, in degrees clockwise from the top.

readonly endAngle number

Where the slice ends, in degrees clockwise from the top.

Properties

readonly seriesIndex? undefined

Always absent: the node belongs to no series.

readonly valueIndex? undefined

Always absent: the node stands for no value.

readonly axis ScaleAxis

The axis the line belongs to; axis.dimension is x or y.

readonly index number

The tick's index.

readonly x1 number

The X of the line's start, in px.

readonly y1 number

The Y of the line's start, in px.

readonly x2 number

The X of the line's end, in px.

readonly y2 number

The Y of the line's end, in px.

Properties

readonly seriesIndex? undefined

Always absent: the node belongs to no series.

readonly valueIndex? undefined

Always absent: the node stands for no value.

readonly kind 'axis'

axis for axis labels; check it to tell them from pie labels.

readonly axis ScaleAxis

The axis the label belongs to; axis.dimension is x or y.

readonly index number

The tick's index.

readonly text Label

The label after labelInterpolationFnc.

readonly x number

The left edge of the label's box, in px.

readonly y number

The top edge of the label's box, in px.

readonly width number

The width of the label's box in px. On the X axis, the space to the next tick.

readonly height number

The height of the label's box in px. On the Y axis, the space to the next tick.

Properties

readonly x number

Px from the left edge of the SVG.

readonly y number

Px from the top edge of the SVG.

readonly series unknown

The series as given in the data (array, or object with data).

readonly seriesIndex number

The series' index in the chart's data, across layers.

readonly meta unknown

The series' meta, if it's a series object with one.

readonly kind 'pie'

pie for slice labels; check it to tell them from axis labels.

readonly valueIndex 0

Always 0, as for the slice.

readonly index number

Same as seriesIndex, as in 1.x draw events.

readonly text string

The label as drawn.

Properties

readonly x1 number

The X of the line's start, in px.

readonly y1 number

The Y of the line's start, in px.

readonly x2 number

The X of the line's end, in px.

readonly y2 number

The Y of the line's end, in px.

readonly ct:value? string | number

The value as written to the output, for points and bars.

readonly ct:meta? string

The value's meta, serialized, for points and bars that have one.

Properties

readonly d string

The path data, as in SVG's d attribute.

readonly ct:value? string | number

The value as written to the output, for slices.

readonly ct:meta? string

The series' meta, serialized, for slices that have one.

Properties

readonly ct:series-name? string

The series' name, if it has one.

readonly ct:meta? string

The series' meta, serialized, if it has one (line and bar charts).

Properties

readonly x number

The left edge, in px.

readonly y number

The top edge, in px.

readonly width number

The width in px.

readonly height number

The height in px.

Properties

point { ctx: PointContext; attrs: LineAttrs }

A value of a line chart: a line of 0.01 px (class ct-point).

bar { ctx: BarContext; attrs: LineAttrs }

A value of a bar chart: a line (class ct-bar).

line { ctx: PathContext; attrs: PathAttrs }

A series' line in a line chart: a path (class ct-line).

area { ctx: PathContext; attrs: PathAttrs }

A series' filled area in a line chart: a path (class ct-area).

slice { ctx: SliceContext; attrs: PathAttrs }

A pie or donut slice: a path (class ct-slice-pie or ct-slice-donut).

series { ctx: SeriesGroupContext; attrs: SeriesAttrs }

The g element that holds a series' nodes (class ct-series).

grid { ctx: GridContext; attrs: LineAttrs }

A grid line of an axis at a tick: a line (class ct-grid).

gridBackground { ctx: NoSeries; attrs: RectAttrs }

The rect behind the chart area (class ct-grid-background).

label { ctx: AxisLabelContext | PieLabelContext; attrs: object }

An axis label (a foreignObject with a span, or SVG text) or a pie label (SVG text). Check ctx.kind to tell them apart.

Example

import { node, type ChartPlugin } from 'chartist';

declare module 'chartist' {
  interface NodeRoles {
    marker: {
      ctx: { readonly seriesIndex: number; readonly label: string };
      attrs: { readonly cx: number; readonly cy: number };
    };
  }
}

// A marker on the last point of each series.
export const markers: ChartPlugin = {
  name: 'markers',
  install(chart) {
    chart.on('compose', current => {
      if (current.role !== 'series') {
        return;
      }
      const last = current.children.at(-1);
      if (last?.role !== 'point') {
        return;
      }
      const { x, y, seriesIndex } = last.ctx;
      return current.append(
        node('circle', { cx: x, cy: y, r: 6 }, 'ct-marker', {
          role: 'marker',
          ctx: { seriesIndex, label: 'last' }
        })
      );
    });
  }
};

Properties

readonly role? keyof NodeRoles

Only nodes of this role, e.g. bar.

readonly key? string

Only the node with this key, e.g. 0/1/3 (layer, series, value).

readonly seriesIndex? number

Only nodes of the series with this index (ctx.seriesIndex).

readonly valueIndex? number

Only nodes of the value with this index (ctx.valueIndex).