Range Charts

Overview

JavaScript range charts or graphs display groups of data that are bound by lower and upper values. They are sometimes referred to as an area band graph, band graph, or silhouette graph. Similar in appearance to an area chart, this chart type is useful in depicting ranges, differences, and spreads. To create one, you’ll need to specify your chart type and provide your series data. Our range charts can display segmented or curved (spline) lines. You can also customize their scales and style their lines, markers, and backgrounds. Browse our ZingChart Gallery for examples and ideas.

Range Chart Types

In your chart object, add a type attribute, and set the chart type to range. Without further modification, a basic range chart with a single data set looks like this:

https://app.zingsoft.com/demos/embed/J30HZ3LH
https://app.zingsoft.com/demos/embed/J30HZ3LH
{
  type: "range",
  series: [
    { values: [ [15,30],
                [20,40],
                [16,35],
                [21,30],
                [25,45],
                [18,27],
                [23,35],
                [29,39],
                [27,30],
                [19,34]
                ]}
    ]
}

Series Data

Range charts can support single or multiple data sets. Make sure to specify both your lower and upper values for each data element. This range chart contains three data sets:

https://app.zingsoft.com/demos/embed/PBFSYXSQ
https://app.zingsoft.com/demos/embed/PBFSYXSQ
{
  type: "range",
  series: [
    { values: [ [15,30],
                [20,40],
                [16,35],
                [21,30],
                [25,45],
                [18,27],
                [23,35],
                [29,39],
                [27,30],
                [19,34]
                ]},
    { values: [ [25,35],
                [12,40],
                [19,30],
                [26,27],
                [12,35],
                [31,39],
                [52,59],
                [29,36],
                [21,25],
                [9,29]
                ]},
    { values: [ [40,45],
                [30,43],
                [35,36],
                [41,50],
                [50,54],
                [45,52],
                [39,42],
                [31,40],
                [41,49],
                [35,40]
                ]}
    ]
}

Chart-Specific Properties

You can further modify your range chart with the aspect attribute. This allows you to choose between segmented or curved (spline) lines.

Aspect

Range charts support two types of aspects: segmented (default) and spline. They can be applied globally to affect all plots or locally to affect specific plots.

To apply aspects globally, create a plot object. Insert your aspect attribute.

plot: {
    aspect: "segmented" /* or "spline" */
  }

To apply aspects locally, add them to the chart data object you want the change to apply to.

Note: If you specify an aspect value in the plot object and an aspect value in a chart data object, the latter will overwrite the former.

series: [
    {    /* Chart data object */
        aspect: "segmented",
        values: [ [15,30],
                [20,40],
                [16,35],
                [21,30],
                [25,45],
                [18,27],
                [23,35],
                [29,39],
                [27,30],
                [19,34]
                ]
    },
    {    /* Chart data object */
        aspect: "spline",
        values: [ [25,35],
                [12,40],
                [19,30],
                [26,27],
                [12,35],
                [31,39],
                [52,59],
                [29,36],
                [21,25],
                [9,29]
                ]
    }
  ]

Segmented Range Chart

On a segmented range chart, data points are connected by straight lines. Since they are the default aspect, specifying their type in the plot object (as depicted below) is optional.

https://app.zingsoft.com/demos/embed/TKLH6FTF
https://app.zingsoft.com/demos/embed/TKLH6FTF
{
  type: "range",
  plot: {
    aspect: "segmented"
  },
  series: [
    { values: [ [15,30],
                [20,40],
                [16,35],
                [21,30],
                [25,45],
                [18,27],
                [23,35],
                [29,39],
                [27,30],
                [19,34]
                ]}
    ]
}

Spline Range Chart

On a spline range chart, data points are connected by gently curving lines. Depending on what you are charting, spline lines may better represent your data.

https://app.zingsoft.com/demos/embed/XGR8A3O7
https://app.zingsoft.com/demos/embed/XGR8A3O7
{
  type: "range",
  plot: {
    aspect: "spline"
  },
  series: [
    { values: [ [15,30],
                [20,40],
                [16,35],
                [21,30],
                [25,45],
                [18,27],
                [23,35],
                [29,39],
                [27,30],
                [19,34]
                ]}
    ]
}

Further Customization and Styling

Once you have your basic range chart, you can next customize and style it. This section explains how to add a category or time-series scale to your range chart, as well as how to style your lines, markers, and backgrounds (the shaded region between your lower and upper values).

Scales

By default, ZingChart’s scales for both the x- and y-axis start as a quantitative (or numeric) one. Users generally want to modify their horizontal axis to display a category or time-series scale. We explain how to incorporate these scale types below.

Note: While the following sections display scale changes made to the x-axis (scale-x object), you can generally make the same changes to the y-axis (scale-y object) as well.

Category Scale

Category scales (also known as qualitative scales) consist of words and/or numbers. Your scale labels can display names, dates, places, events, and more. To add a category scale to your range chart, create a scale-x object, and insert a labels array. Provide your scale labels as string values, separated by commas.

Note: Do not confuse a labels array with a label (no "s") object. The latter allows you to specify your scale title.

https://app.zingsoft.com/demos/embed/VX5B756P
https://app.zingsoft.com/demos/embed/VX5B756P
{
  type: "range",
  'scale-x': {
    label: {    /* Scale Title */
      text: "Above is an example of a category scale",
    },
    labels: [ "Jan", "Feb", "March", "April", "May", "June", "July", "Aug", "Sept", "Oct" ] /* Scale Labels */
  },
  series: [
    { values: [ [15,30],
                [20,40],
                [16,35],
                [21,30],
                [25,45],
                [18,27],
                [23,35],
                [29,39],
                [27,30],
                [19,34]
                ]}
    ]
}

Time-Series Scale

Time-series scales are used to represent time increments ranging from years down to milliseconds. To add one to your range chart, create a scale-x object. Inside add a min-value attribute, step attribute, and transform object.

For the min-value and step, you’ll need to specify your minimum and step scale values in Unix time. This is measured by the number of milliseconds that have elapsed since January 1, 1970, UTC time. You can calculate your timestamps with an online conversion tool such as Epoch Converter.

Note: Make sure to provide your Unix time in milliseconds. You can convert seconds to milliseconds by multiplying by 1000.

The transform object will convert your Unix timestamps into a more readable format. In the object, add a type attribute, and set the value to date. Next, add an all attribute. You can specify how you want your scale formatted by using our ZingChart tokens, contained in a string.

Note: To ensure your time-series scale reads in UTC time (ZingChart currently defaults to local time), add a utc attribute, and set the value to true.

https://app.zingsoft.com/demos/embed/STD7KULR
https://app.zingsoft.com/demos/embed/STD7KULR
{
  type: "range",
  utc: true, /* Force UTC time. */
  plotarea: {
    'adjust-layout': true /* For automatic margin adjustment. */
  },
  'scale-x': {
    label: { /* Add a scale title with a label object. */
      text: "Above is an example of a time-series scale",
    },
    'min-value':1420070400000, /* Unix timestamp for Jan 1, 2015. */
    step: "day",
    transform: { /* Converts your Unix timestamp to a human readable format. */
      type: "date", /* Set your transform type to "date". */
      all: "%m.%d.%y" /* Specify your date/time format, using tokens. */
    }
  },
  series: [
    { values: [ [15,30],
                [20,40],
                [16,35],
                [21,30],
                [25,45],
                [18,27],
                [23,35],
                [29,39],
                [27,30],
                [19,34],
                [23,40]
                ]}
    ]
}

Tokens

Range chart-specific tokens include:

TokenDescription
%node-max-valueThe upper node value
%node-min-valueThe lower node value

Refer to the ZingChart Tokens Tutorial for a full list of available tokens.

Styling

Next, you can style your range chart’s lines, markers, and backgrounds. This covers just the basics. For even more styling and customization options, see our JSON Attributes/Syntax page.

Line Color, Style, and Width

Go to the chart object of the plot you want to style. To specify your line color, add a line-color attribute. Provide your color as a hexadecimal or RGB value. To change your line style, add a line-style attribute, and then specify your choice of solid (default), dashed, or dotted line. You can also change your line’s width. Simply insert a line-width attribute, and provide a pixel value.

https://app.zingsoft.com/demos/embed/FWI7YMJS
https://app.zingsoft.com/demos/embed/FWI7YMJS
{
  type: "range",
  series: [
    { values: [ [15,30],
                [20,40],
                [16,35],
                [21,30],
                [25,45],
                [18,27],
                [23,35],
                [29,39],
                [27,30],
                [19,34]
                ]
      'line-color': "#6666FF",
      'line-style': "dashed",
      'line-width':5
    }
    ]
}

Marker Color, Size, and Width

Modify the color, size, and width of your range chart markers. Create a marker object, and place it in the chart object of the plot you want your changes to apply to. With markers, you can modify the fill (color and size) and border (color and width). For fill color, use a background-color attribute. Specify your fill size with a size attribute. For border color, use a border-color attribute. Specify your border width with a border-width attribute.

https://app.zingsoft.com/demos/embed/F3IE5B7U
https://app.zingsoft.com/demos/embed/F3IE5B7U
{
  type: "range",
  series: [
    { values: [ [15,30],
                [20,40],
                [16,35],
                [21,30],
                [25,45],
                [18,27],
                [23,35],
                [29,39],
                [27,30],
                [19,34]
              ],
      marker: { /* Marker object */
        'background-color': "#FF0066",
        size:8,
        'border-color': "#6666FF",
        'border-width':5
      }
    }
    ]
};

You can also use the maxMarker and minMarker objects to style the upper node and lower node markers, respectively.

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

Background Color and Transparency

You can change the color (single color or gradient) and transparency of the shaded area between your upper and lower range values. To change your background color, add a background-color attribute to your chart object. For a single color, add one hexadecimal or RGB value. For a gradient (two color) background, add two values, separated by a space. You can adjust your color’s transparency by adding an alpha-area attribute. Transparency ranges from 0 (clear) to 1 (solid). Provide a value between 0-1, and make sure to insert a zero before your decimal point.

https://app.zingsoft.com/demos/embed/BOMK3MJ3
https://app.zingsoft.com/demos/embed/BOMK3MJ3
{
  type: "range",
  series: [
    { values: [ [15,30],
                [20,40],
                [16,35],
                [21,30],
                [25,45],
                [18,27],
                [23,35],
                [29,39],
                [27,30],
                [19,34]
              ],
      'background-color': "#6666FF #FF0066",
      'alpha-area':0.5
    }
    ]
};

Summary

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