Rendering

Parameters

config ChartConfig

The chart: data, axes, layers, plugins and listeners

size SceneSize

The size to lay out at, in px, and how to measure text

Returns

Example

import { lineChartConfig, node, toScene } from 'chartist';
import { renderToString } from 'chartist/server';

const config = lineChartConfig(
  { labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'], series: [[12, 9, 7, 8, 5]] },
  {
    viewBox: { width: 600, height: 300 },
    on: {
      // Styles inside the SVG, for tools that read it on its own.
      scene: ({ scene }) => ({
        scene: scene.append(
          node('style').text('.ct-line { fill: none; stroke: #d70206; }'),
          true
        )
      })
    }
  }
);
const scene = toScene(config, { width: 600, height: 300 });

export const markup = renderToString(scene);

Example

import { seriesColors } from 'chartist';

// The color of series `c`, the third.
export const third = seriesColors[2];

Parameters

element Element

The element to change

name string

The attribute's name, as in a scene node's attrs

value string | number

The attribute's value

Example

import { applyAttribute } from 'chartist';

const point = document.querySelector('.ct-point');
if (point) {
  applyAttribute(point, 'ct:value', 12);
  applyAttribute(point, 'style', 'stroke-width: 12px;');
}

Parameters

current SceneNode

The node to create

document Document

The document to create the elements in

options? RenderElementOptions = {}

The namespace, and a callback for each created element

Returns

Example

import { node, renderElement } from 'chartist';

const dot = renderElement(node('circle', { cx: 5, cy: 5, r: 4 }, 'ct-dot'), document);
document.querySelector('svg')?.append(dot);

Example

import { chart, domRenderer, pie, type Renderer } from 'chartist';

const dom = domRenderer();
// The DOM renderer, with a name for screen readers on every render.
const renderer: Renderer = {
  ...dom,
  render(scene, container) {
    const output = dom.render(scene, container);
    output.svg.setAttribute('role', 'img');
    output.svg.setAttribute('aria-label', 'Monthly budget');
    return output;
  }
};

chart('#chart', {
  data: { series: [50, 30, 20] },
  coordinates: 'polar',
  layers: [pie()],
  renderer
});

Example

import { estimateText, type MeasureText } from 'chartist';

// Bold labels: a tenth wider than the estimate.
export const measureText: MeasureText = (text, options) => {
  const size = estimateText(text, options);
  return { ...size, width: size.width * 1.1 };
};

Properties

readonly width number

The width to lay out at, in px. In toScene(), the root svg gets it as its width, unless the config sets one.

readonly height number

The height to lay out at, in px. In toScene(), the root svg gets it as its height, unless the config sets one.

readonly measureText? MeasureText

Text measurement for layout; an estimate by default.

readonly labels? LabelMode

Label mode when the config sets none. svg by default in toScene(), since string output often goes to tools without HTML support; html in renderForHydration(), as chart() draws them.

Properties

readonly svg SVGSVGElement

The chart's svg element, in the container.

readonly elementOf (node: SceneNode) => Element | undefined

The rendered element of a scene node of this render.

readonly remove () => void

Takes the SVG out of the container again.

readonly patched? boolean

true when the renderer changed its previous output in place with the update it got, instead of replacing it. Then changes says what it did.

readonly changes? readonly SceneChange[]

What the renderer did to each changed node, with patched. Without them, the chart describes the render as a replacement.

readonly animation? UpdateAnimation

The timing of the update animation the renderer started, if any. The mount event passes it on as animation.

Properties

readonly html? boolean

Creates the elements in the XHTML namespace, as inside a foreignObject.

readonly created? (node: SceneNode, element: Element) => void

Called for every node and the element created for it.

Properties

readonly width number

The text's width in px.

readonly height number

The text's height in px: one line.

readonly fontSize? number

The font size in px the text was measured with, when known.

Properties

readonly classes? readonly string[]

Class names of the text, for renderers that apply CSS.

readonly fontSize? number

Font size in px. Without it, the browser measures with the CSS font size and the estimate uses 12, the size of 1.x .ct-label.

readonly rootClass? string

Classes of the chart's root svg, so chart-type CSS applies.

readonly container? Element

Where to measure (the chart container), so its CSS applies.

Example

import type { MeasureText } from 'chartist';

// Wider glyphs than the estimate, for a wide font.
export const measureText: MeasureText = (text, options = {}) => {
  const fontSize = options.fontSize ?? 12;
  return { width: text.length * fontSize * 0.7, height: fontSize * 1.25 };
};

Properties

readonly classes? readonly string[]

Class names of the element whose style is read.

readonly rootClass? string

Classes of the chart's root svg, so chart-type CSS applies.

readonly container? Element

Where to measure (the chart container), so its CSS applies.

Example

import { domRenderer, type Renderer } from 'chartist';

// The DOM renderer, but donuts are laid out for 30px rings, whatever
// the stylesheet says. Pass it as `renderer` to `chart()`.
export const renderer: Renderer = {
  ...domRenderer(),
  measureStyle: property => (property === 'stroke-width' ? '30px' : undefined)
};

Properties

readonly op 'remove' | 'update' | 'add'

What happened to the node.

readonly node SceneNode

The node: of the new scene, or of the previous one for remove.

readonly previous? SceneNode

The node in the previous scene, for update.

Properties

readonly duration number

The duration in ms.

readonly easing string

The CSS easing, such as ease-out or cubic-bezier(0.3, 0, 0.2, 1).

Properties

readonly previous TOutput

What this renderer returned for the previous render.

readonly previousScene SceneNode

The previous render's scene.

readonly cause RenderCause

Why the chart renders.

readonly labels readonly unknown[]

The data's labels, for keys from labels.

readonly previousLabels readonly unknown[]

The previous render's labels, for keys from labels in the previous scene.

readonly keyframes (previous: SceneNode, next: SceneNode, progress: readonly number[]) => Keyframes | undefined

Asks the chart's plugins, then the layer that drew the node, for the keyframes of a node's update at the given progress points (0 is the previous node, 1 the new one; points may lie beyond them when the easing overshoots). Returns nothing when none of them has any.

Properties

readonly elementOf? (node: SceneNode) => Element | undefined

The rendered element of a scene node, if the output is DOM.

readonly remove? () => void

Removes the output again.

readonly patched? boolean

true when the renderer changed its previous output in place with the update it got, instead of replacing it. Then changes says what it did.

readonly changes? readonly SceneChange[]

What the renderer did to each changed node, with patched. Without them, the chart describes the render as a replacement.

readonly animation? UpdateAnimation

The timing of the update animation the renderer started, if any. The mount event passes it on as animation.

Properties

render (scene: SceneNode, target: Element, update?: RenderUpdate<TOutput>) => TOutput

Renders a scene into the chart's container, after the scene phase and on every update and resize. From the second render on, it gets the previous render as update: a renderer that changes its previous output in place returns patched: true and its changes; one that ignores update replaces its output, as the DOM renderer does.

readonly measureText? MeasureText

Measures text for layout, in the container so its CSS applies; without it, Chartist estimates text sizes.

readonly measureStyle? MeasureStyle

Reads computed styles for layout, in the container so its CSS applies; without it, layout uses its defaults (a donut's ring is laid out for 60 px).

readonly labels? LabelMode

The default label mode of this renderer; html if omitted.

adopt? (container: Element, replay: (layout: { readonly width: number; readonly height: number; readonly labels: LabelMode }) => SceneNode) => TOutput & { readonly repaired: number } | undefined

Takes over markup from renderForHydration() in the chart's container, instead of rendering: finds it and reads the layout its marker records, gets the scene for that layout from replay, binds the scene's nodes to the markup's elements and makes them what render() would draw. A chart calls it once, before its first render, unless it always draws a new svg; later renders go through render(), with the adopted output as the previous one. Returns nothing when there's no markup to take over or it doesn't match the scene, and the chart then renders as usual. liveDomRenderer() from chartist/live has it; the DOM renderer doesn't, since it replaces its svg on every render.