Hover Handling

This topic explains how to handle series and point hover events in the Chart and PieChart UI components.

Series Hover

When an end-user hovers the mouse pointer over a series, its appearance assumes a specific hover style. To customize the default hover style, use the series hoverStyle configuration object. This object can specify settings for all series:

JavaScript
var chartOptions = {
    commonSeriesSettings: {
        hoverStyle: {
            // Common hover style configuration    
        }
    }
};

for type-specific series:

JavaScript
var chartOptions = {
    commonSeriesSettings: {
        line: { // or 'bar', 'spline', etc.
            hoverStyle: {
                // Type-specific hover style configuration    
            }
        }
    }
};

or for an individual series:

JavaScript
var chartOptions = {
    series: [{
        hoverStyle: {
            // Individual hover style configuration
        }
    }, {
        // ...
    }]
};

To choose which series elements to highlight when the series is hovered over, specify the hoverMode property. Like the hover style, this property can be specified for all, type-specific or an individual series. There are several hover modes in the chart UI components. Available modes depend on the series type you use.

To handle the series hover event, assign a function to the onSeriesHoverChanged property of the chart.

JavaScript
var chartOptions = {
    onSeriesHoverChanged: function (info) {
        //...
    }
};

The onSeriesHoverChanged function accepts an object that contains information on the hover event. Among fields of this object, you can find the series whose hover state has been changed. An object that represents this series is described in the Series section. Use the isHovered() method of this object to identify whether the series has been hovered over or hovered out.

NOTE
There are series that consist of points only, e.g., the bar-like and candleStick series of the Chart UI component, and the pie and doughnut series of the PieChart UI component. The onSeriesHoverChanged function is not called when hovering over a point (a bar or a slice) in these types of series. To handle the hover event for these series, implement the onPointHoverChanged function and access the series of the point whose hover state has been changed (see the Point Hover topic).

Point Hover

When an end-user rests the mouse pointer over a series point, its appearance assumes a specific hover style. To customize the default hover style, use the point hoverStyle configuration object. This object can specify settings for all series:

JavaScript
var chartOptions = {
    commonSeriesSettings: {
        point: {
            hoverStyle: {
                // Hover style configuration    
            }
        }
    }
};

for type-specific series:

JavaScript
var chartOptions = {
    commonSeriesSettings: {
        line: { // or 'bar', 'spline', etc.
            point: {
                hoverStyle: {
                    // Type-specific hover style configuration    
                }
            }
        }
    }
};

or for an individual series:

JavaScript
var chartOptions = {
    series: [{
        point: {
            hoverStyle: {
                // Individual hover style configuration
            }
        }
    }, {
        // ...
    }]
};
NOTE
The point configuration object defines the points of the line-like, scatter and area-like series only. To set the hover style for points of other series types, use the hoverStyle configuration object of the parent series.

By default, the chart highlights only the point that was hovered over. But in some scenarios, you may need several points to be highlighted. To specify it, use the hoverMode property. Like the hover style, this property can be specified for all, type-specific or an individual series. It can accept one of the following values.

  • onlyPoint — highlights only the point that was hovered over
  • allSeriesPoints — highlights all points from the parent series
  • allArgumentPoints — highlights all points with the same argument
  • none — does not highlight anything

To handle the point hover event, assign a function to the onPointHoverChanged property of the chart.

JavaScript
var chartOptions = {
    onPointHoverChanged: function (info) {
        //...
    }
};

The onPointHoverChanged function accepts an object that contains information on the hover event. Among fields of this object, you can find the point whose hover state has been changed. An object that represents this point is described in the Point section. Use the isHovered() method of this object to identify whether the point has been hovered over or hovered out.

NOTE
Frequently, points that appear hovered over are not actually so, due to the 'allArgumentPoints' or 'allSeriesPoints' hover mode being set. For these points, the pointHoverChanged event does not occur and their isHovered() method returns false.