Plugins

A Chartist plugin listens to the phases of a chart and changes its scene: it adds nodes, replaces them or drops them. The terminal draws that same scene, so a plugin needs no terminal version. Pass it in plugins, as you would on an SVG chart.

Marking values

This plugin keeps a circle on each value that reaches a target and drops the other points. The target line itself is a layer from the core, targetLine(), added with the layers option. The plugin is an ordinary 2.x plugin, written with nothing but chartist:

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

/**
 * Keeps a circle on each value that reaches the target. The other points
 * go.
 */
export const reached = (target: number): ChartPlugin => ({
  name: 'reached',
  install(chart) {
    chart.on('compose', current => {
      if (current.role !== 'point') {
        return;
      }
      const { x, y, value } = current.ctx;
      const hit =
        value && typeof value === 'object' && 'y' in value
          ? (value.y ?? 0) >= target
          : false;
      // A circle with the point's role, context and key, or null to drop it.
      return hit
        ? node('circle', { cx: x, cy: y, r: 6 }, 'ct-hit', {
            role: current.role,
            ctx: current.ctx,
            key: current.key
          })
        : null;
    });
  }
});

How it works:

• The compose listener sees every point with its value in ctx.value.
• It returns a circle with the point’s role, ctx and key, or null to drop the point. The circles stay in their series’ group, so they take its color.

On an SVG chart, the layer and the plugin go into the same options:

import { lineChart } from 'chartist';
import { targetLine } from '@chartist-js/essentials';
import { reached } from './reached';

lineChart('#chart', data, {
  low: 0,
  layers: {
    above: [
      targetLine({ value: 1000, label: 'target', labelPosition: 'start' })
    ]
  },
  plugins: [reached(1000)]
});

Events and plugins covers the phases, the scene nodes and writing a plugin.

What the terminal draws

Nodes with one of Chartist’s roles (line, point, bar, slice, band and the others) are drawn as the terminal draws that role. Every other node is drawn by its element:

That goes for nodes a plugin replaced too. The circles above keep the role point, but they’re circles now, so the terminal draws them as circles.

A node in a series’ group, or with a ct-series-x class, takes that series’ color. Other lines and points use the text color, and text the label color. Styles (stroke-width, dashes) and the plugin’s own classes don’t show: a cell has a character and a color, and in HTML its classes are the kind of mark and the series.

Plugins that need a page

A terminal chart is laid out and drawn, never mounted. Listeners of the render and mount phases don’t run, and calling update() on the chart throws. So plugins that work with the page, such as tooltips, hover effects and zoom, have nothing to do here. Plugins that change the scene in compose or scene work.

Next: Chartist’s options in the terminal in Customizing charts, or every function on the API page.