chartjs-plugin-annotations

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.