Written by Laszlo Simon on March 31, 2023

Customizing Vizzu Charts - Annotations using MarkerJS

Adding annotations to a Vizzu chart can be a useful way to highlight specific data points and add additional information to your visualizations. We will do this in two steps. First, we add the Marker.js UI to the Vizzu chart to create the annotation visually and export them in JSON format, and second, using the exported JSON, we show them on the chart permanently, without the editor UI. By following these steps, you can create interactive and informative visualizations that make it easier to understand complex data.

Prerequisites

Before you start this tutorial, it’s best that you have a basic understanding of JavaScript, Vizzu, and Marker.js. You can find the corresponding documentation here:

Part 1: Making the Annotations

Step 0: Getting Started

To get started, create a new HTML file and include the following code:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Vizzu Chart with Annotations</title>
  </head>
  <body>
    <div id="vizzu-container" style="width:500px; height:350px;"></div>
    <script src="./index.js" type="module"></script>
  </body>
</html>

This new HTML file contains an empty div element that will be used to render the Vizzu chart. We also include the JavaScript file called ‘index.js’ that we’ll create next.

You’ll need to have Vizzu and Marker.js imported into your project. You can do this by adding the following code to your JavaScript file:

import Vizzu from 'https://cdn.jsdelivr.net/npm/vizzu@latest/dist/vizzu.min.js';
import 'https://cdn.jsdelivr.net/npm/markerjs2@2.29.0/markerjs2.min.js';

Step 1: Create the Vizzu Chart

First, we will need a chart that we will annotate. We will use a simple example from the README of Vizzu.

We set up the data we want to visualize:

let data = {
  series: [
    { name: 'Foo', values: ['Alice', 'Bob', 'Ted'] },
    { name: 'Bar', values: [15, 32, 12] }
  ]
};

Next, we initialize the Vizzu chart:

let chart = new Vizzu('vizzu-container', { data });

Finally, we create a simple bar chart with two series, ‘Foo’ and ‘Bar’:

let animating = chart.animate({
    x: 'Foo',
    y: 'Bar'
});

Step 2: Add Marker.js UI over the Chart

Now, we need to create a new instance of the Marker.js MarkerArea class and pass the container div as its target element:

let markerArea = new markerjs2.MarkerArea(document.getElementById('vizzu-container'));

Next, you need to show the Marker.js UI by calling the show() method:

markerArea.show();

We also add an event listener to the MarkerArea object to capture the annotation data in JSON format when we finish annotating:

markerArea.addEventListener('render', event => {
    navigator.clipboard.writeText(JSON.stringify(event.state));
    alert("Annotation JSON object copied to clipboard!");
});

This code listens to the render event and copies the annotation data in JSON format to the clipboard when we finish annotating. We also display an alert message - just in case - that the annotation data has been copied to the clipboard.

With this code, we have successfully added the Marker.js annotation editor UI over the Vizzu chart. The next step is to open our project in a browser and add annotations to the chart.

Part 2: Displaying the annotations

Once we annotated the chart and saved the annotations to the clipboard by clicking the check mark button, we can add these annotations permanently to our chart.

First, we roll back the Marker.js-related code we added in the last step of the first part. Then, we add the following code instead:

import 'https://cdn.jsdelivr.net/npm/markerjs-live@1.1.0/markerjs-live.min.js';

This imports the Marker.js Live library instead of the Editor. Next, we create a new MarkerView object, which, uses the same container div as the Vizzu chart.

let markerView = new mjslive.MarkerView(document.getElementById('vizzu-container'));

Next, we paste the annotation data that we saved to the clipboard earlier into the config variable:

let config = /* Paste your JSON annotation object here! */;

Finally, after the chart animation has been completed, we show the annotations permanently on the chart.

animating.then(chart => {
    markerView.show(config);
});

See the Pen Vizzu with Annotations by Vizzu (@Vizzu) on CodePen.

With this code, we have successfully added the annotations made using the Marker.js UI to the Vizzu chart.