Crosshair

Overview

Crosshair is a pair of perpendicular lines (horizontal and vertical), moving with the mouse. It might be useful, when you need to get the particular data of an action, while the axes contain any other information, such as years/months or any kind of percentage. Also, it looks similar to an aim in shooting; it's easier to "hit" the necessary point and get some extra information about it with the crosshair on a web chart.

Crosshair listens to these events: mouseMove, mouseOver, mouseOut, when mouse is inside the DataPlot box, Crosshair appears. Note that Crosshairs can have only one label each axis (one label on x-axis and another on y-axis).

Crosshairs can be used on all Cartesians (Area, Line, Bar, Column, etc.) and Scatter Charts.

Enable

If you want to switch the Crosshair on, set the .crosshair() as true:

  // turn the crosshair on
  chart.crosshair(true);

JsFiddle Playground

Binding to axes

In case you've got several axes on the same scale, you should tie the crosshair to one of them. Unless you do it, the default axis will be chosen (with the "0" index). Use axisIndex() method for this.

  // set the indexes of the axes used
  var yLabel = chart.crosshair().yLabel();
  yLabel.axisIndex(1);
  var xLabel = chart.crosshair().xLabel();
  xLabel.axisIndex(0);

Look at the sample downwards. Here we've got three axes and the crosshair is on.

JsFiddle Playground

Appearance

Lines

In some situations you may not need one or both lines but highlighted labels are still necessary. Write .xStroke(null) to remove the x-axis line (or .yStroke(null) to remove the y-axis):

  // remove the x-axis line
  var crosshair = chart.crosshair();
  crosshair.xStroke(null);

JsFiddle Playground

Labels

Disable

Use the standard function to disable the axes labels.

  // disable the crosshair yLabels
  var crosshair = chart.crosshair();
  crosshair.yLabel(false);

JsFiddle Playground

Change text

The crosshair label's format is the same as axis label's format by default. You may use the textFormatter() to change the crosshair's labels' performance.

  // set the label performance
  var yLabel = chart.crosshair().yLabel();
  yLabel.textFormatter(function() {
    return "$" + this.value;
  });

Here is the sample with customized both x and y crosshair labels.

JsFiddle Playground

As far as you can use any function as textFormatter() of crosshair labels you use these labels to display additional information. Here is a sample with more complex labels formatter.

JsFiddle Playground

You are looking at an outdated 7.11.0 version of this document. Switch to the 8.0.1 version to see the up to date information.