chartjs-plugin-annotation

The chartjs-plugin-annotation allows you to draw various shapes and elements on the chart area.

Supported Annotation Types

• Lines
• Boxes
• Points
• Labels
• Polygons
• Ellipses
• Doughnut Labels: A specialized annotation type used to add content (such as text, images, or canvas elements) into the center area of doughnut charts.

Supported Chart Types and Scales

Annotations are compatible with:

• Chart Types: line, bar, scatter, and bubble charts.
• Scales: linear, logarithmic, time, or category scales.

The position option determines where the label is anchored within the annotation. It supports two formats:

1. Single Value: A string that applies to both horizontal and vertical axes.

   • Keywords: 'start', 'center', 'end'.
   • Percentage: A string in 'number%' format (e.g., '25%').

2. Object Value: An object specifying x and y independently.

   • x: Horizontal alignment ('start', 'center', 'end', or 'number%').
   • y: Vertical alignment ('start', 'center', 'end', or 'number%').
   • Note: Omitted properties default to 'center'.

// Example: Using a single string for both axes
label: {
  position: 'end'
}

// Example: Using an object for independent X and Y positioning
label: {
  position: {
    x: 'start',
    y: '50%'
  }
}

When a label contains multiple lines of text, you can apply different styles to each line by providing an array to the font or color options.

If the number of lines exceeds the number of provided configurations in the array, the last configuration in the array will be applied to all remaining lines.

When the content of a label contains multiple lines (an array of strings), you can style each line differently by providing an array to the font or color options.

• If the number of lines exceeds the number of provided styles, the last style in the array is applied to all remaining lines.
• This allows for complex, multi-styled text labels within a single annotation.

// Example concept: Multi-line styling
label: {
  content: ['Line 1', 'Line 2', 'Line 3'],
  color: ['red', 'blue'], // Line 1 is red, Line 2 is blue, Line 3 is blue
  font: [{ weight: 'bold' }, { weight: 'normal' }] // Line 1 is bold, others are normal
}

The position option determines where the label is located within the chart center. It accepts two formats:

1. Preset strings: 'start', 'center', or 'end'. If a string is used, it is applied to both vertical and horizontal axes.
2. Percentage strings: A string like '50%' representing the percentage position.
3. Object: An object {x: string, y: string} where x and y can be 'start', 'center', 'end', or a percentage string. Omitted properties default to 'center'.

Version 2.x introduces interaction options to configure which events trigger annotation interactions. By default, the plugin follows the standard Chart.js interaction configuration.

Removed Events

• dblclick: The dblclick event hook has been removed from annotation options. This was done because asynchronous execution of this hook prevents reliable chart re-rendering.
• dblClickSpeed: This option was removed from the plugin options as the dblclick hook is no longer available.

Scatter Chart Behavior

When using scatter charts, note that the interaction default mode in Chart.js is point. In version 1.x, the plugin default was nearest.

Line annotations can be positioned using two different modes:

1. Single Scale Mode: If scaleID is set, the line is drawn perpendicular to that axis. You must provide value (the start point) and endValue (the end point) to indicate the endpoints.
2. Two Coordinate Mode: If scaleID is unset, the line is drawn from (xMin, yMin) to (xMax, yMax). You can specify xScaleID and yScaleID to bind to specific axes.

Behavior for missing scales:

• If scaleID is not resolved: The line spans the entire chart from top-left to bottom-right.
• If xScaleID is not resolved: The line spans the entire chart width.
• If yScaleID is not resolved: The line spans the entire chart height.

A callout can connect a label to the annotation line if the label has been moved away from its original position using xAdjust or yAdjust.

Configure callouts via options.annotations[annotationID].label.callout:

• display: Set to true to draw the callout.
• position: Position relative to the label ('left', 'top', 'right', 'bottom', or 'auto').
• margin: Pixels between the label and the callout separator.
• borderColor: Stroke color of the pointer.
• borderWidth: Stroke width of the pointer.
• start: The starting point of the callout pointer as a pixel number or percentage string (e.g., '50%').
• side: Width of the starter line of the callout pointer.

label: {
  display: true,
  xAdjust: 50, // Move label away from line
  callout: {
    display: true,
    position: 'top',
    borderColor: 'black'
  }
}

The annotation plugin supports drawing lines, boxes, labels, points, polygons, and ellipses on the chart area.

Supported Chart Types:

• Line charts
• Bar charts
• Scatter charts
• Bubble charts
• Doughnut charts (specifically for adding doughnut label annotations in the middle area)

Supported Scales:

• Linear
• Logarithmic
• Time
• Category

Limitations: Annotations will not work on charts that do not have exactly two axes, such as pie, radar, and polar area charts.

The position option determines where the label content is placed relative to its bounding box or anchor point.

There are two ways to define position:

1. Simple String: Use 'start', 'center', or 'end'. If a percentage string is used (e.g., '25%'), it represents the percentage position within the box.
2. Object: Use an object to define independent horizontal (x) and vertical (y) alignments.
   • Example: { x: 'start', y: 'center' }.
   • Supported values for x and y are 'start', 'center', 'end', or percentage strings.
   • If a property is omitted, it defaults to 'center'.

If position is a string, it is applied to both vertical and horizontal axes simultaneously.