Show Nav

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.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "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 cad 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.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

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.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "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.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "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.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

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.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "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.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "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.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "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.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "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.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "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

Got a question about how value boxes work? We are happy to help. Email support@zingchart.com or start a chat right here on this page for help.