Your first chart

This tutorial builds a small chart with a line trace and a bar trace, then updates it and listens for clicks. It takes about five minutes.

Status

Holochart is pre-alpha. Everything on this page runs today; see Installation for how to use it from source until the first alpha is published.

1. Add a container

Holochart draws into an element you provide. Give it a size: the chart fills its container.

<div id="chart" style="width: 640px; height: 400px"></div>

2. Create a chart

Call createChart with the element and a figure. A figure is a plain object with data (a list of traces), layout, and config. All three are optional except data.

import { createChart } from '@mk7s/holochart';

const el = document.getElementById('chart')!;

const chart = createChart(el, {
  data: [
    {
      type: 'scatter',
      x: [1, 2, 3, 4, 5],
      y: [3, 1, 4, 2, 5],
      mode: 'lines+markers',
      name: 'Visits',
    },
  ],
});

mode: 'lines+markers' draws a line through the points and a marker at each one. Use 'markers' for a scatter plot or 'lines' for a plain line chart.

3. Add a bar trace

Traces in data share the same axes by default. Add a bar trace next to the scatter trace:

const chart = createChart(el, {
  data: [
    {
      type: 'scatter',
      x: [1, 2, 3, 4, 5],
      y: [3, 1, 4, 2, 5],
      mode: 'lines+markers',
      name: 'Visits',
    },
    { type: 'bar', x: [1, 2, 3, 4, 5], y: [2, 2, 3, 1, 4], name: 'Signups' },
  ],
});

Because both traces have a name, the legend shows both. Bars always draw below lines and markers, as in Plotly, so the line stays visible even though the bar trace comes later. To change that, give a trace a higher zorder.

4. Add titles

Titles and axes live in layout:

const chart = createChart(el, {
  data: [/* the two traces from step 3 */],
  layout: {
    title: { text: 'Weekly traffic' },
    xaxis: { title: { text: 'Week' } },
    yaxis: { title: { text: 'Count' } },
  },
  config: { responsive: true },
});

config: { responsive: true } resizes the chart when its container changes size. Config controls behavior, not appearance. See Core concepts for the difference between layout and config.

This is the chart so far, live. Hover a point, drag to zoom, and double-click to zoom back out:

Loading example…

Loading source…

line/with-bars

5. Update the chart

Change trace data or style with chart.update. The second argument picks which traces to change:

chart.update({ data: [{ y: [4, 2, 5, 3, 6] }] }, { traces: [0] });

Change layout with chart.relayout, using dotted attribute paths:

chart.relayout({ 'xaxis.range': [0, 6], 'title.text': 'Weekly traffic (updated)' });

Holochart works out which stages of its pipeline an update touches and re-runs only those. A color change restyles the existing GPU buffers. A data change recomputes that trace.

Every update method returns a promise that resolves once the new frame is drawn, and chart.ready does the same for the first frame:

await chart.ready;
await chart.update({ data: [{ y: [4, 2, 5, 3, 6] }] }, { traces: [0] });

6. Listen for clicks

Subscribe to events with chart.on. A click event carries the points under the cursor:

chart.on('click', (event) => {
  for (const point of event.points) {
    console.log(point.curveNumber, point.x, point.y);
  }
});

See the events reference for every event and its payload.

7. Clean up

When you remove the chart from the page, call destroy. It releases the WebGL context and all GPU memory the chart used.

chart.destroy();

purge(el) does the same for the chart in an element, and also removes the note described next.

When WebGL2 is unavailable

Holochart draws with WebGL2. In a browser without it (or with it disabled, or on a blocklisted GPU), createChart throws a WebGLUnavailableError and newPlot rejects with one. The container shows a short note that WebGL2 is required, followed by the chart's text description (its title, chart type and one line per trace), so the page is not left with an empty box. No chart is registered for the element: getChart(el) returns undefined, and purge(el) removes the note.

import { newPlot, WebGLUnavailableError } from '@mk7s/holochart';

try {
  await newPlot(el, data, layout);
} catch (error) {
  if (error instanceof WebGLUnavailableError) {
    // The note is already in `el`; show a static image instead if you have one.
  } else {
    throw error;
  }
}

WebGLUnavailableError and ValidationError (thrown in config.strict mode) both extend HolochartError. The renderer's own error is in error.cause.

What is underneath

Every chart is drawn with a small set of GPU primitives: instanced markers, screen-space lines, rectangles, and text, all in one WebGL canvas. The figure you pass is the whole description of the chart: it is plain data, so you can build it on a server or store it as JSON.

Next steps

• Core concepts: the figure model, schema, and pipeline
• Scatter, Line, Bar, and Horizontal bar chart pages
• Layout attribute reference and config reference