Arrows

Overview

Need to direct the attention of your viewers to something specific in your chart? Arrows give you the ability to do just that. ZingChart offers a variety of ways to customize your arrows, in terms of both positioning and styling.

Basics

The first step to adding arrows to your chart is to add the "arrows" container. This will allow you to create any number of arrow objects in your chart.

arrows: [ ]

Once you've done this, you can begin to add individual arrow objects. Each of these arrow objects require the "from" and "to" attributes to be set in order for the arrow to appear.

arrows: [{
  from: {},
  to: {}
}]

To add multiple arrows, you can simply add another arrow object within your container.

arrows: [
  {
    from: {},
    to: {}
  },
  {
    from: {},
    to: {}
  }
]

Attributes

From

The "from" attribute is used to set the point on the chart at which the arrow begins. This can be set in one of two ways. The first method involves setting specific x and y coordinates that refer to a point on the chart. The second method sets the arrow's beginning point to a data node on your chart.

(X,Y) Coordinates

Setting the (x,y) coordinates for your arrow gives you more control, but may cause you to run in to issues if the values used within your chart change or if the size of your chart changes. When using (x,y) coordinates, keep in mind that all coordinates will be relative to the origin, which is located in the top-left corner of the chart.

arrows: [{
  from: {
    x: 400,
    y: 200
  },
  to: {}
}],
https://app.zingsoft.com/demos/embed/EP44PAXT
https://app.zingsoft.com/demos/embed/EP44PAXT

Data Nodes

Data nodes are arguably more reliable because they will automatically make the appropriate adjustments to the arrow if the size of your chart were to change. When the size of a chart changes, the (x,y) location of your data may change position, which would potentially require you to adjust the (x,y) position of your arrow. With data nodes, arrows will always point to the same data point, even when your chart changes. To set a data node, use the "hook" attribute in place of the individual x and y coordinates. Plot refers to a set of values, and the index refers to the individual item of data within that set of values. Plots and indices begin at 0, not 1.

arrows: [{
  from: {
    hook: "node:plot=2,index=1"
  },
  to: {}
}],
https://app.zingsoft.com/demos/embed/F0VS8VSC
https://app.zingsoft.com/demos/embed/F0VS8VSC

To

The "to" attribute is used to set the point on the chart at which the arrow ends. The functionality of the "to" attribute is virtually identical to the "from" attribute. As such, arrows can point to either a specific (x,y) coordinate on the chart, or to a data node on your chart.

(X,Y) Coordinates

Setting the (x,y) coordinate for you arrow gives you more granular control over your arrow, but may cause you to run in to issues if the values within your chart change or if the size of your chart changes.

arrows: [{
  from: {},
  to: {
    x: 304,
    y: 320
  }
}],
https://app.zingsoft.com/demos/embed/SNM7SLFA
https://app.zingsoft.com/demos/embed/SNM7SLFA

Data Nodes

Data nodes offer more flexibility when it comes to manipulating your chart data or chart size. Just like with the "from" attribute, data nodes are set using the "hook" attribute.

arrows: [{
  from: {},
  to: {
    hook: "node:plot=2,index=19"
  }
}],
https://app.zingsoft.com/demos/embed/NCO14KAX
https://app.zingsoft.com/demos/embed/NCO14KAX

Styling

Many of the styling options will produce the best results when you include a text box with your arrow. In our scatter chart, we can see a positive correlation between the red data points. Having already used data nodes to set the placement of the arrow, let's add a text label and some styling options. Setting the "text" attribute will apply a label over the arrow.

arrows: [{
  text: "Positive Correlation",
  from: {
    hook: "node:plot=2,index=1"
  },
  to: {
    hook: "node:plot=2,index=19"
  }
}],
https://app.zingsoft.com/demos/embed/WI9DM51K
https://app.zingsoft.com/demos/embed/WI9DM51K

Adding a text label opens up a number of styling options. We can customize the appearance of the text using a number of CSS-like attributes such as "font-family", "font-weight", and "font-size".

arrows: [{
  text: "Positive Correlation",
  'font-family': "Helvetica",
  'font-size':12,
  from: {
    hook: "node:plot=2,index=1"
  },
  to: {
    hook: "node:plot=2,index=19"
  }
}],

Now, let's add some color to our arrow. By setting two background colors, we're creating a gradient that will be used by the text label. We can also modify the border so that it more resembles the data markers.

arrows: [
  {
    text: "Positive Correlation",
    'font-family': "Helvetica",
    'font-size':12,
    'background-color-1': "#ef4810",
    'background-color-2': "#cc3300",
    'border-width':2,
    'border-color': "#a62b02",
    from: {
      hook: "node:plot=2,index=1"
    },
    to: {
      hook: "node:plot=2,index=19"
    }
  }
],

Finally, we'll add a slight shadow effect by setting the "shadow" attribute to true, set a vertical offset so that the arrow does not cover the data points that we're interested in, and add some padding around the text within the label.

arrows: [{
  text: "Positive Correlation",
  'font-family': "Helvetica",
  'font-size':12,
  'background-color-1': "#ef4810",
  'background-color-2': "#cc3300",
  'border-width':2,
  'border-color': "#a62b02",
  shadow: true,
  'shadow-blur':3,
  'offset-y':-35,
  padding: "5px",
  from: {
    hook: "node:plot=2,index=1"
  },
  to: {
    hook: "node:plot=2,index=19"
  }
}],
https://app.zingsoft.com/demos/embed/70I87H8O
https://app.zingsoft.com/demos/embed/70I87H8O

For a more full list of available attributes, please visit our JSON Syntax page.

Summary

Arrows are a helpful feature for charts that need a prominent callout, and there are a number of styling options to make them look just the way you want.

Don't forget, a comprehensive list of available attributes and objects can be found on our JSON Syntax page.