chartist/live

smilAnimations

experimentalchartist/liveSource

function smilAnimations(): LiveAnimations

Animates the changes of an update with SMIL, timed by the chart's CSS: each updated node's changed numbers and paths move from their previous value to their new one over --ct-update-duration (a CSS time, 300 ms by default; 0s turns the animations off) with the easing in --ct-update-easing (a CSS easing, ease-out by default). The attributes hold their new values from the start, and an update during an animation continues from where each element is drawn.

It animates updates (update(), setOptions()) and changes of the matching responsive options, not resizes, and nothing while the visitor's system asks for reduced motion. Lines and areas follow their values' keys, and pie slices turn around the pie; layers and plugins can give keyframes of their own.

Returns

The animations, for liveDomRenderer({ animations })

Example

import { lineChart } from 'chartist';
import { liveDomRenderer, smilAnimations } from 'chartist/live';

// 300 ms with ease-out, unless the CSS sets --ct-update-duration
// and --ct-update-easing.
const chart = lineChart(
  '#chart',
  { labels: ['Mon', 'Tue', 'Wed'], series: [[5, 2, 4]] },
  { renderer: liveDomRenderer({ animations: smilAnimations() }) }
);

chart.update({ data: { labels: ['Mon', 'Tue', 'Wed'], series: [[3, 6, 1]] } });

diffScenes

experimentalchartist/liveSource

function diffScenes(previous: SceneNode, next: SceneNode, options?: DiffOptions): SceneChange[]

The changes between two scenes, matched by what each node stands for: add, update (with the previous node) and remove, in the new scene's document order, with the remove entries after their former parent's kept children. Every node of an added or removed subtree has its own entry. The live renderer patches its SVG with them; other renderers that change their output in place can use them too.

Nodes are matched among the children of matched parents: values by their layer, series and key (see key), series by layer and index, grid lines and axis labels by axis and tick, nodes with their own key by it, and the rest by element name and first class, in order.

Parameters

previous SceneNode: The previous scene
next SceneNode: The new scene
options? DiffOptions = {}: How values are identified, and the data's labels

Returns

The changes, in the new scene's document order

Example

import { lineChartConfig, toScene } from 'chartist';
import { diffScenes } from 'chartist/live';

const size = { width: 600, height: 300 };
const labels = ['Mo', 'Tu', 'We'];
const before = toScene(lineChartConfig({ labels, series: [[1, 2, 3]] }), size);
const after = toScene(lineChartConfig({ labels, series: [[1, 5, 3]] }), size);

for (const { op, node } of diffScenes(before, after, { labels })) {
  console.log(op, node.role, node.key);
}

liveDomRenderer

experimentalchartist/liveSource

function liveDomRenderer(options?: LiveDomRendererOptions): Renderer<DomRenderOutput>

Creates a DOM renderer that keeps a chart's SVG and changes it in place on every later render, instead of drawing a new one: elements that stand for the same thing as before stay, with only their changed attributes, classes and text set, elements for new nodes are created and elements of nodes that are gone are removed. What listeners added to kept elements stays, and mount gets the changes of the render.

Its first render, and every render without the previous one (1.x charts), draws a new SVG as domRenderer does. A chart whose container holds markup from renderForHydration() takes that markup over instead, keeping the server's elements, unless adopt is false. The renderer keeps no state of its own, so one instance can serve many charts.

Parameters

options? LiveDomRendererOptions = {}: How values are identified (key), update animations, such as smilAnimations(), and whether to take server markup over

Returns

The renderer, for renderer in chart() and the presets

Example

import { lineChart } from 'chartist';
import { liveDomRenderer } from 'chartist/live';

const labels = ['Mo', 'Tu', 'We', 'Th', 'Fr'];
const values = [3, 5, 4, 6, 5];
const chart = lineChart(
  '#chart',
  { labels, series: [values] },
  // Points and labels follow their day as the window slides.
  { renderer: liveDomRenderer({ key: 'label' }) }
);

let day = 0;
setInterval(() => {
  labels.push(`Day ${++day}`);
  labels.shift();
  values.push(Math.round(Math.random() * 10));
  values.shift();
  chart.update({ labels: [...labels], series: [[...values]] });
}, 1000);

ValueKeyContext

experimentalchartist/liveSource

interface ValueKeyContext

What ValueKey functions get about a value: where it is, the value itself, the label at its position and its meta.

Properties

readonly seriesIndex number: The series' index in the chart's data.
readonly valueIndex number: The value's index in its series (for pie data, 0).
readonly value unknown: The value, as the layer drew it.
readonly label unknown: The label at the value's position: labels[valueIndex], or the slice's label in pie data.
readonly meta unknown: The value's meta, if any.

ValueKey

experimentalchartist/liveSource

type ValueKey = 'index' | 'label' | ((value: ValueKeyContext) => string | number)

What identifies a value across updates: 'index' (the default) its position in its series, 'label' the label at its position, or a function of the value, such as ({ meta }) => meta.id.

DiffOptions

experimentalchartist/liveSource

interface DiffOptions

The options of diffScenes: how values are identified, and the labels for key: 'label'.

Properties

readonly key? ValueKey: What identifies a value across updates; 'index' by default.
readonly labels? readonly unknown[]: The new scene's labels, for key: 'label'.
readonly previousLabels? readonly unknown[]: The previous scene's labels, for key: 'label'; labels if omitted.

LiveAnimationContext

experimentalchartist/liveSource

interface LiveAnimationContext

What the live renderer hands its LiveAnimations after patching the SVG of an update.

Properties

readonly changes readonly SceneChange[]: The changes the render made, in document order.
readonly elementOf (node: SceneNode) => Element | undefined: The element of a node of the new scene.
readonly update RenderUpdate: The previous render, with the cause and the keyframes lookup.
readonly container Element: The chart's container.
readonly scene SceneNode: The new scene.
readonly measureStyle? MeasureStyle: Reads computed styles in the container, with the chart's root classes.
readonly valueKey (context: Omit<ValueKeyContext, 'label'>, scene: 'previous' | 'next') => string: The key that identifies a value across updates, as the renderer's key option says: for the value at valueIndex of series seriesIndex, with its value and meta, in the previous scene or the new one (labels differ between them).

LiveAnimations

experimentalchartist/liveSource

interface LiveAnimations

Update animations for the live renderer, such as smilAnimations: called after the SVG of an update was patched, it starts the animations and returns their timing, or nothing when the render doesn't animate.

Properties

animate (context: LiveAnimationContext) => UpdateAnimation | undefined: Starts the update animations of a render.

LiveDomRendererOptions

experimentalchartist/liveSource

interface LiveDomRendererOptions

The options of liveDomRenderer.

Properties

readonly key? ValueKey: What identifies a value across updates; 'index' by default.
readonly animations? LiveAnimations: Update animations, such as smilAnimations(); none by default.
readonly adopt? boolean: Takes over markup from renderForHydration() in the chart's container and keeps its elements; true by default. With false, the chart draws a new svg over the server markup.