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.

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.

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.

{
  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.

{
  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:

Stacked Charts

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

{
  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).

{
  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.

{
  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.

{
  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.

{
  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.