Value Boxes

Overview

Value boxes are the labels that appear adjacent to the data points on your chart. Able to display any combination of values, text, and/or tokens, they can be applied across an entire series array, to selected series, or to individual data points such as minimum, maximum, first, and/or last values. Refer to the JSON Attributes/Syntax page for Value Boxes for a full list of attribute options.

Note: Value boxes are distinguished from tooltips and crosshairs, which are labels that only appear when a user hovers over the data points.

Formatting

Default Value Boxes

For the majority of ZingChart chart types, value boxes are not visible by default. (Pie charts are a notable exception.) To add value boxes to your chart, go to the plot object and create a value-box object. This will cause all of the plot values to display.

{
  type: 'bar',
  plot: {
    'value-box': {
      //Displays all data values by default.
    }
  },
  'scale-x': {
    labels: [ "Q1", "Q2", "Q3", "Q4" ]
  },
  'scale-y': {
    values: "0:100:25"
  },
  series: [{
    values: [30, 59, 33, 81]
  }, {
    values: [34, 64, 40, 85]
  }]
}

Multiple Value Boxes

Value boxes can be either a simple object ('value-box': {}) or an array of objects ('value-box': [{},{}]). Configuring value boxes as an array with multiple objects allows you to associate different tokens and text strings to each node while providing different placement and styling to each object.

https://app.zingsoft.com/demos/embed/CR2HI0P9
https://app.zingsoft.com/demos/embed/CR2HI0P9

Text and Tokens

To change the default text, add a text attribute to your value-box object. You can provide any combination of alphanumeric characters and/or ZingChart tokens, such as %v widgets, $%v, or %v %t. Refer to the ZingChart Tokens Tutorial for a full list of available tokens. While tokens such as %v (node values) and %t (plot text) are used across all chart types, there are many tokens that are chart-specific or for specific use cases.

https://app.zingsoft.com/demos/embed/JRCD2COT
https://app.zingsoft.com/demos/embed/JRCD2COT
{
  type: 'bar',
  plot: {
    'value-box': {
      text: "$%vK"
    }
  },
  'scale-x': {
    labels: [ "Q1", "Q2", "Q3", "Q4" ]
  },
  'scale-y': {
    values: "0:100:25"
  },
  series: [{
    values: [30, 59, 33, 81]
  }, {
    values: [34, 64, 40, 85]
  }]
}

Type

Value boxes display across all data points in a series by default. To change this, add a type attribute to your value-box object. You can have your value boxes display the minimum (min), maximum (max), first (first), and/or last (last) values. Note that multiple values can be provided, such as type: 'min,max' or type: 'min,max,first,last'. They can also display all (all) or no (none) values.

Note: Another way to specify where data points are placed is to use Logic Rules. Used with ZingChart Tokens, they allow you to create custom rules on how to display value boxes. See our Incorporating Rules section below.

https://app.zingsoft.com/demos/embed/17J2JVFE
https://app.zingsoft.com/demos/embed/17J2JVFE
{
  type: 'bar',
  plot: {
    'value-box': {
      text: "$%vK",
      type: "max" //all (default), min, max, first, last, and/or none
    }
  },
  'scale-x': {
    labels: [ "Q1", "Q2", "Q3", "Q4" ]
  },
  'scale-y': {
    values: "0:100:25"
  },
  series: [{
    values: [30, 59, 33, 81]
  }, {
    values: [34, 64, 40, 85]
  }]
}

Placement

Use the placement attribute to specify where value boxes are placed in relation to the data points. The placement options vary based on the chart type. The following values are currently available:

Chart Type Placement Options
Area Chart auto | top | bottom | left | right | over
Bar Chart top-out(=top) | top-in | middle | bottom-in | bottom-out(=bottom) | over
Bubble Chart top | bottom | left | right | over
Heat Map top | bottom | left | right | over
Line Chart auto | top | bottom | left | right | over
Pie Chart out | in | center
Scatter Plot top | bottom | left | right | over

Stacked Charts

Use the %stack-top token and some simple rules to only show valueBox text at the top of a stack.

https://app.zingsoft.com/demos/embed/IRTBOF85
https://app.zingsoft.com/demos/embed/IRTBOF85

Note: Depending on the length or size of your value box text, you may need to adjust the offsets. Add an offset-x and/or offset-y attribute, and provide a pixel value.

https://app.zingsoft.com/demos/embed/VLN4BD7U
https://app.zingsoft.com/demos/embed/VLN4BD7U
{
  type: 'bar',
  plot: {
    'value-box': {
      text: "$%vK",
      placement: "top-in",
      'font-color': "white"
    }
  },
  'scale-x': {
    labels: [ "Q1", "Q2", "Q3", "Q4" ]
  },
  'scale-y': {
    values: "0:100:25"
  },
  series: [{
    values: [30, 59, 33, 81]
  }, {
    values: [34, 64, 40, 85]
  }]
}

Angle

You can change the rotation angle of your value boxes with the angle attribute. A positive value turns your value boxes in a clockwise direction. A negative value turns them in a counterclockwise direction. In the example below, the value boxes were turned 270 degrees (or -90).

Note: Sometimes your value box offsets will need to be adjusted. Use the offset-x and/or offset-y attribute(s), and provide a pixel value.

https://app.zingsoft.com/demos/embed/RXXXH1PF
https://app.zingsoft.com/demos/embed/RXXXH1PF
{
  type: 'bar',
  plot: {
    'value-box': {
      text: "$%vK",
      placement: "top-in",
      'font-color': "white",
      angle: -90,
      'offset-y': 5
    }
  },
  'scale-x': {
    labels: [ "Q1", "Q2", "Q3", "Q4" ]
  },
  'scale-y': {
    values: "0:100:25"
  },
  series: [{
    values: [30, 59, 33, 81]
  }, {
    values: [34, 64, 40, 85]
  }]
}

Styling

Font Styling

To style your value box text, use styling attributes such as font-color (provide a hexadecimal or RGB value), font-family, font-size, font-weight (normal or bold), or font-style (normal or italic). Browse the Value Boxes JSON Attributes/Syntax page for more styling options.

https://app.zingsoft.com/demos/embed/6BJH597R
https://app.zingsoft.com/demos/embed/6BJH597R
{
  type: 'bar',
  plot: {
    'value-box': {
      text: "$%vK",
      'font-color': "#666699",
      'font-family': "Georgia",
      'font-size': 15,
      'font-weight': "normal",
      'font-style': "normal"
    }
  },
  'scale-x': {
    labels: [ "Q1", "Q2", "Q3", "Q4" ]
  },
  'scale-y': {
    values: "0:100:25"
  },
  series: [{
    values: [30, 59, 33, 81]
  }, {
    values: [34, 64, 40, 85]
  }]
}

Box Styling

To style the background color and borders of your value boxes, use styling attributes such as background-color, border-color, border-width, line-style (solid, dotted, dashed, or dashdot), and shadow (true or false). To adjust the padding around your value box text, create a padding attribute and provide a percentage value. You can also add callout arrows by creating a callout attribute and setting the value to true. Refer to the Value Boxes JSON Attributes/Syntax page for additional styling attributes.

https://app.zingsoft.com/demos/embed/E6IFGZHQ
https://app.zingsoft.com/demos/embed/E6IFGZHQ
{
  type: 'bar',
  plot: {
    'value-box': {
      text: "$%vK",
      'background-color': "#f0f0f5",
      'border-width': 1,
      'border-color': "#666699",
      'line-style': "dashdot",
      shadow: false,
      padding: "15%",
      callout: true
    }
  },
  'scale-x': {
    labels: [ "Q1", "Q2", "Q3", "Q4" ]
  },
  'scale-y': {
    values: "0:100:25"
  },
  series: [{
    values: [30, 59, 33, 81]
  }, {
    values: [34, 64, 40, 85]
  }]
}

Incorporating Rules

You can format and style your value boxes based on specified conditions. Read our Logic Rules Tutorial and ZingChart Tokens Tutorial for more in-depth information. Rules allow you to dictate which values appear, as well as how they are formatted and styled, so that you can draw greater attention to outliers, notable data clusters, and so on. To get started, create a rules array. Inside the array, create an object for each new rule. Each object must contain a rule (rule attribute) and attributes for what happens what the rule is met.

Note: Rules are not limited to value boxes. In the example below, a rules array was also added to the plot object to color the bars based on their data values.

https://app.zingsoft.com/demos/embed/APO3G0WL
https://app.zingsoft.com/demos/embed/APO3G0WL
{
  type: 'bar',
  plot: {
    'value-box': {
      text: "$%vK",
      'font-family': "Georgia",
      rules: [{
        rule: "%v >= 75",
        placement: "top-out",
        'font-color': "black",
        'font-size': 16,
        'background-color': "white",
        'border-color': "gray",
        'border-width': 1,
        padding: "5%",
        callout: true
      }, {
        rule: "%v < 75",
        placement: "top-in",
        'font-color': "white",
        'font-weight': "normal"
      }]
    },
    rules: [{
      rule: "%v >= 75",
      'background-color': "yellow orange"
    }, {
      rule: "%v < 75",
      'background-color': "gray black"
    }]
  },
  'scale-x': {
    labels: [ "Q1", "Q2", "Q3", "Q4" ]
  },
  'scale-y': {
    values: "0:100:25"
  },
  series: [{
    values: [30, 59, 33, 81]
  }, {
    values: [34, 64, 40, 85]
  }]
}

Summary

Value boxes are labels that show a node's value, displayed on or near a node. Value boxes allow your users to quickly glean the exact value of a node without having to interact with the chart (such as hovering the node). They are most useful when there are discrete data points on your chart, such as a bar or pie chart. For a full list of value box attributes, see the JSON configuration page.