chartjs-plugin-annotation

What is chartjs-plugin-annotation?

The chartjs-plugin-annotation package is a plugin for Chart.js that allows you to add annotations to your charts. These annotations can be lines, boxes, or labels that highlight specific areas or points on the chart, making it easier to convey additional information or emphasize certain data points.

What are chartjs-plugin-annotation's main functionalities?

Line Annotation

This feature allows you to add a horizontal or vertical line to your chart. The line can be used to mark a specific value on the x or y axis. In this example, a horizontal line is added at the y-value of 25 with a label 'Threshold'.

{
  type: 'line',
  mode: 'horizontal',
  scaleID: 'y-axis-0',
  value: '25',
  borderColor: 'red',
  borderWidth: 2,
  label: {
    enabled: true,
    content: 'Threshold'
  }
}

Box Annotation

This feature allows you to add a rectangular box to your chart. The box can highlight a specific area on the chart. In this example, a box is drawn from January to March on the x-axis and from 10 to 50 on the y-axis.

{
  type: 'box',
  xScaleID: 'x-axis-0',
  yScaleID: 'y-axis-0',
  xMin: 'January',
  xMax: 'March',
  yMin: 10,
  yMax: 50,
  backgroundColor: 'rgba(101, 33, 171, 0.5)',
  borderColor: 'rgb(101, 33, 171)',
  borderWidth: 1
}

Label Annotation

This feature allows you to add a label at a specific point on the chart. The label can contain text and can be styled with various options. In this example, a label is added at the point (February, 30) with the text 'This is a label'.

{
  type: 'label',
  xValue: 'February',
  yValue: 30,
  backgroundColor: 'rgba(0,0,0,0.8)',
  content: ['This is a label'],
  font: {
    size: 12
  },
  color: 'white',
  position: 'center'
}

Other packages similar to chartjs-plugin-annotation

chartjs-plugin-datalabels

The chartjs-plugin-datalabels package is another plugin for Chart.js that allows you to display labels on data points. While chartjs-plugin-annotation focuses on adding annotations like lines and boxes, chartjs-plugin-datalabels is more about adding labels directly to the data points themselves.

chartjs-plugin-zoom

The chartjs-plugin-zoom package provides zoom and pan functionalities for Chart.js charts. While it doesn't offer annotation features, it allows users to interact with the chart by zooming in and out or panning across the data, which can be useful for detailed data analysis.

chartjs-plugin-crosshair

The chartjs-plugin-crosshair package adds a crosshair to Chart.js charts, which can be used to highlight the exact position of the cursor on the chart. This is somewhat similar to annotations in that it helps to highlight specific points, but it is more focused on real-time interaction.

README

chartjs-plugin-annotation.js

An annotation plugin for Chart.js >= 2.4.0

Currently draws lines and boxes on the chart area.

Configuration

To configure the annotations plugin, you can simply add new config options to your chart config.

{
	annotation: {
		annotations: [{
			id: 'a-line-1', // optional
			type: 'line',
			mode: 'horizontal',
			scaleID: 'y-axis-0',
			value: '25',
			borderColor: 'red',
			borderWidth: 2,

			// Fires when the user clicks this annotation on the chart
			// (be sure to enable the event in the events array below).
			onClick: function(e) {
				// `this` is bound to the annotation element
			}
		}],

		// Defines when the annotations are drawn.
		// This allows positioning of the annotation relative to the other
		// elements of the graph.
		//
		// Should be one of: afterDraw, afterDatasetsDraw, beforeDatasetsDraw
		// See http://www.chartjs.org/docs/#advanced-usage-creating-plugins
		drawTime: 'afterDraw', // (default)

		// Mouse events to enable on each annotation.
		// Should be an array of one or more browser-supported mouse events
		// See https://developer.mozilla.org/en-US/docs/Web/Events
		events: ['click'],

		// Double-click speed in ms used to distinguish single-clicks from 
		// double-clicks whenever you need to capture both. When listening for
		// both click and dblclick, click events will be delayed by this
		// amount.
		dblClickSpeed: 350 // ms (default)
	}
}

Line Annotations

Vertical or horizontal lines are supported.

{
	type: 'line',

	// optional annotation ID (must be unique)
	id: 'a-line-1',

	// set to 'vertical' to draw a vertical line
	mode: 'horizontal',

	// ID of the scale to bind onto
	scaleID: 'y-axis-0',

	// Data value to draw the line at
	value: 25,

	// Optional value at which the line draw should end
	endValue: 26,

	// Line color
	borderColor: 'red',

	// Line width
	borderWidth: 2,

	// Line dash
	// https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash
	borderDash: [2, 2],

	// Line Dash Offset
	// https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset
	borderDashOffset: 5,

	label: {
		// Background color of label, default below
		backgroundColor: 'rgba(0,0,0,0.8)',

		// Font family of text, inherits from global
		fontFamily: "sans-serif",

		// Font size of text, inherits from global
		fontSize: 12,

		// Font style of text, default below
		fontStyle: "bold",

		// Font color of text, default below
		fontColor: "#fff",

		// Padding of label to add left/right, default below
		xPadding: 6,

		// Padding of label to add top/bottom, default below
		yPadding: 6,

		// Radius of label rectangle, default below
		cornerRadius: 6,

		// Anchor position of label on line, can be one of: top, bottom, left, right, center. Default below.
		position: "center",

		// Adjustment along x-axis (left-right) of label relative to above number (can be negative)
		// For horizontal lines positioned left or right, negative values move
		// the label toward the edge, and negative values toward the center.
		xAdjust: 0,

		// Adjustment along y-axis (top-bottom) of label relative to above number (can be negative)
		// For vertical lines positioned top or bottom, negative values move
		// the label toward the edge, and negative values toward the center.
		yAdjust: 0,

		// Whether the label is enabled and should be displayed
		enabled: false,

		// Text to display in label - default is null
		content: "Test label"
	},

	// Mouse event handlers - be sure to enable the corresponding events in the
	// annotation events array or the event handler will not be called.
	// See https://developer.mozilla.org/en-US/docs/Web/Events for a list of
	// supported mouse events.
	onMouseenter: function(e) {},
	onMouseover: function(e) {},
	onMouseleave: function(e) {},
	onMouseout: function(e) {},
	onMousemove: function(e) {},
	onMousedown: function(e) {},
	onMouseup: function(e) {},
	onClick: function(e) {},
	onDblclick: function(e) {},
	onContextmenu: function(e) {},
	onWheel: function(e) {}
}

Box Annotations

Box annotations are supported. If one of the axes is not specified, the box will take the entire chart dimension.

The 4 coordinates, xMin, xMax, yMin, yMax are optional. If not specified, the box is expanded out to the edges

{
	type: 'box',

	// optional annotation ID (must be unique)
	id: 'a-box-1',

	// ID of the X scale to bind onto
	xScaleID: 'x-axis-0',

	// ID of the Y scale to bind onto
	yScaleID: 'y-axis-0',

	// Left edge of the box. in units along the x axis
	xMin: 25,

	// Right edge of the box
	xMax: 40,

	// Top edge of the box in units along the y axis
	yMax: 20,

	// Bottom edge of the box
	yMin:  15,

	// Stroke color
	borderColor: 'red',

	// Stroke width
	borderWidth: 2,

	// Fill color
	backgroundColor: 'green',

	// Mouse event handlers - be sure to enable the corresponding events in the
	// annotation events array or the event handler will not be called.
	// See https://developer.mozilla.org/en-US/docs/Web/Events for a list of
	// supported mouse events.
	onMouseenter: function(e) {},
	onMouseover: function(e) {},
	onMouseleave: function(e) {},
	onMouseout: function(e) {},
	onMousemove: function(e) {},
	onMousedown: function(e) {},
	onMouseup: function(e) {},
	onClick: function(e) {},
	onDblclick: function(e) {},
	onContextmenu: function(e) {},
	onWheel: function(e) {}
}

To-do Items

The following features still need to be done:

• Point Annotations
• Text annotations

Installation

To download a zip, go to the Chart.Annotation.js on Github

To install via npm:

npm install chartjs-plugin-annotation --save

Prior to v0.2.0 this plugin was known as Chart.Annotation.js. You can still install this old version via NPM.

Documentation

You can find documentation for Chart.js at www.chartjs.org/docs.

Contributing

Before submitting an issue or a pull request to the project, please take a moment to look over the contributing guidelines first.

License

Chart.Annotation.js is available under the MIT license.