Line Charts
Overview
ZingChart supports three area chart types:
- Standard 2D
- 3D
- Vertical
These chart types can then be modified to appear:
- Segmented
- Splined
- Stepped
- Jumped
- Stacked
Note: See our Line Chart Gallery for inspiration on all the different line chart possibilities.
Line Chart Types
Specify your chart type with the type attribute. You can create a simple two-dimensional line chart (line), three-dimensional line chart (line3d), or vertical line chart (vline).
Note: Learn more about how to create 3D charts with our 3D Charts Tutorial.
Line Chart
Our standard line chart is specified by the line value. It connects your data points with the default segmented lines (which you can modify with the aspect attribute, discussed further below). They can contain single or multiple datasets.
{
type: 'line',
}
Vertical Line Chart
A vertical line chart is specified by the vline value. For this chart type, the axes are switched so that the x-axis scale runs on the vertical axis and the y-axis scale runs on the horizontal axis.
{
type: 'vline',
}
Trellis Line Chart
To create a trellis chart, you’ll need to insert a graphset array. Inside the array, you can add a chart object for each of your individual charts.
Note: Refer to our Adding Additional Charts page for more information on how to create a graphset array, as well as how to insert additional charts.
In our trellis line chart example below, the three datasets (taken from the vertical line chart example above) were separated to display as three smaller charts.
{
graphset: [
{
type: 'vline',
height: '100%',
width: '33.33%',
x: '0%',
y: '0%',
series: [
{ values: [20,40,25,50,15,45,33,34]}
]
},
{
type: 'vline',
height: '100%',
width: '33.33%',
x: '33.33%',
y: '0%',
series: [
{ values: [5,30,21,18,59,50,28,33]}
]
},
{
type: 'vline',
height: '100%',
width: '33.33%',
x: '66.66%',
y: '0%',
series: [
{ values: [30,5,18,21,33,41,29,15]}
]
}
]
}
Data
Line charts support series arrays that contain single or multiple datasets. They can display arrays with null values (to depict unavailable data), as well as array of arrays (which allows you to depict missing or non-linear data).
Array
A basic array allows you to present consistent, linear data. Values are represented on the y-axis, while the corresponding x-axis values are automatically provided. (The default value starts at zero and increases sequentially by one.)
series: [
{ values: [y0, y1, y2, y3, ..., yN]}, /* Add a single dataset */
{ values: [y0, y1, y2, y3, ..., yN]}, /* or multiple datasets */
{ values: [y0, y1, y2, y3, ..., yN]},
]
Array with Null Values
When you have missing data that you want to visually convey in your chart, you can use an array with null values. Null values will show the breaks in your plot. See the example below, where null values have replaced plot indices 2 and 5:
{
type: 'line',
series: [
{ values: [20,40,null,50,15,null,33,34]} /* Plot indices 2 and 5 are unavailable */
]
}
Array of Arrays
An array of arrays is useful for when you have unavailable data but still want to display a continuous line. Because you specify your corresponding x-axis values, you can bridge over missing sections by providing the x- and y-axis coordinates of nearby values.
{
type: 'line',
series: [
{ values: [[0,20],[1,40],[3,50],[4,15],[6,33],[7,34]]} /* Plot indices 2 and 5 are unavailable */
]
}
You can also use an array of arrays to display non-linear data. Simply provide your x- and y-axis coordinate values in the order you want your line drawn.
{
type: 'line',
series: [
{ values: [[0,20],[6,40],[3,50],[2,15],[5,33],[7,34]]}
]
}
Chart-Specific Properties
Further modify your line charts with our aspect and stacked attributes. You can create spline, stepped, jumped, and stacked line charts.
The following demo illustrates the different options available for the area chart modifications discussed below:
Aspect
Aspects can be applied globally to affect all plots or locally to affect specific plots. The aspect value options for line charts are:
| Value | Description |
|---|---|
segmented (default) |
Data points are connected by straight lines. Since it is the default aspect, specifying its type is optional. |
spline |
Data points are connected by gently curving lines |
stepped |
Data is depicted as a series of stepped horizontal or vertical lines. This aspect is useful for emphasizing differences, comparisons, and sudden changes in data. |
jumped |
Displays only the horizontal portion of a stepped line. |
To apply aspects globally, create a plot object and insert your aspect attribute.
plot: { /* Plot object */
aspect: 'segmented', /* 'spline' | 'stepped' | 'jumped' */
stacked: false /* or true */
}
To apply aspects locally, add them to the chart data object you want the change to apply to.
series: [
{ /* Chart data object */
aspect: 'segmented' /* 'spline' | 'stepped' | 'jumped' */
values: [y0, y1, y2, y3, ..., yN]
}
]
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.
Connect Nulls
To connect null points rather than having a break in your plot, set connectNulls to true.
{
type: 'line',
plot: {
connectNulls: true,
},
}
Cluster
Use the clustered attribute to set the entire plot to be placed within one key scale.
The clusterIndex attribute sets which key scale to place the plot in.
To offset the margin of the cluster, use clusterOffset.
These attributes can be used within the plot or series object.
{
plot: {
clustered: true,
clusterOffset: 10,
},
series: [{
clusterIndex: 0,
}]
}
Midpoint
Use the midPoint attribute to whether a node is wrapped before and after its position.
By default, tooltip is triggered before and after the node when hovering over the series line.
However, setting midPoint to false will trigger the tooltip for the node only on or after the node.
{
plot: {
midPoint: false,
}
}
Monotone
Use the monotone attribute to set whether monotone interpolation is applied to the chart.
This only applies if using the spline aspect.
{
plot: {
monotone: false,
}
}
Segment Trackers
The segmentTrackers attribute sets whether tooltips are activated on the lines.
Setting the attribute to false will only enable tooltips on the markers.
{
plot: {
segmentTrackers: false, // true by default
}
}
Stacked
The stacked attribute allows you to stack multiple datasets on top of each other. With this chart type, you can create a standard stacked bar or 100% stacked bar, as well as specify which datasets are sorted into which stacks.
Note: We recommend using stacked line charts with caution as they can be visually confusing compared to other stacked chart types. Consider using a stacked area chart or stacked bar chart instead.
Standard Stacked Line Chart
Add a stacked attribute to your plot object and set the value to true. (By default, the value is set to false.)
{
plot: {
stacked: true
}
}
100% Stacked Line Chart
To create a 100% stacked line chart, add a stacked attribute to your plot object and set the value to true. Next, add a stack-type attribute and set the value to 100%. (By default, the value is set to normal.)
You'll also need to specify your minimum and maximum values for the y-axis. Create a scale-yobject. Inside, add a min-value attribute and set the value to 0. Add a max-value attribute and set the value to 100. Alternatively, you can add a values attribute and include your min and max value as string separated by colons- values: "0:100".
Note: Learn more about min/max scales with our Scales Tutorial.
{
type: 'line',
plot: {
stacked: true,
stackType: '100%'
},
scaleY: {
minValue: 0,
maxValue: 100
}
}
Step Start
Use the stepStart attribute to set where a step should occur relative to two nodes.
The available options are 'after', 'before', 'middle'.
{
plot: {
stepStart: 'after', // 'middle' by default
}
}
Further Customization and Styling
Once you’ve set up your basic line chart, the next step is to customize and style it. This section explains how to configure your scales. We also discuss how to style your chart’s lines and markers.
Scales
ZingChart’s default scales for both the x- and y-axis is a linear one. However, users generally want to modify their scales so that they display a category or time-series scale on their horizontal (scale-x) axis and a quantitative scale (linear or logarithmic) on their vertical (scale-y) axis. We explain how to configure your scales accordingly.
Note: Learn more about scales with our Scales Tutorial.
Note: While scale modification changes in the examples below are made to the x-axis (scale-x object), the same changes can be made to the y-axis (scale-y object) as well.
Category Scale
A category (or qualitative) scale can be used to describe names, places, time periods, events, and more. They can consist of any word and/or number combination.
Configure your category scale by adding a scale-x object to your chart. Inside, add a labels array. The array can include scale labels such as:
labels: [ 'Jan', 'Feb', 'March', 'April', 'May', 'June' ]
labels: [2000, 2002, 2004, 2006, 2008, 2010]
labels: [ 'Q1', 'Q2', 'Q3', 'Q4' ]
Note: Be careful not to confuse the labels array, which adds scale labels, with the label object, which allows you to specify your scale title.
You can set your margins to automatically adjust, helping to accommodate your scale labels. Create a plotarea object, and add an adjust-layout attribute. Set the value to true.
{
type: 'line',
plotarea: {
adjustLayout: true /* For automatic margin adjustment. */
},
}
Time-Series Scale
Time-series scales are used to represent time increments that range from milliseconds to years. To create one, add a scale-xobject, and place a min-value attribute, step attribute, and transform object inside it.
For the min-value and step, you’ll need to provide your minimum and step scale values in Unix time. Also known as Epoch time, this is measured by the number of milliseconds that have elapsed since January 1, 1970, UTC time. You can calculate your timestamps by using Epoch Converter, an online conversion tool.
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.
You can set your margins to automatically adjust, helping to ensure all your scale labels fit comfortably within your chart. Create a plotarea object. Add an adjust-layout attribute, and set the value to true.
{
type: 'line',
utc: true, /* Force UTC time. */
plotarea: {
adjustLayout: true /* For automatic margin adjustment. */
}
}
Logarithmic Scale
Logarithmic scales are another kind of quantitative scale where the logarithm (the power to which your base value is raised) increases sequentially by one.
To configure your scale, create a scale-y object, and insert a progression attribute. Set the value to log. (The default value is lin, for linear scale.) Next, add a log-base attribute. You can specify your base value to be Math.E (this is the default, and corresponds to the base of natural logarithms, i.e., e or Euler’s number) or 10.
Make sure your scale labels fit comfortably inside your chart by setting the margins to automatically adjust. Create a plotarea object, and add an adjust-layout attribute. Set the value to true.
{
type: 'line',
plotarea: {
adjustLayout: true
},
scaleY: {
progression: 'log', /* Logarithmic Scale */
logBase: Math.E, /* or 10 */
decimals: 3
}
}
Styling
In this section, we explain how to style your chart's lines and markers.
Note: For more styling options, see our JSON Attributes/Syntax page.
Line Color, Style, and Width
You can specify the color, style, and width of your chart lines. Start in the chart data object of the plot you want to change. For your line color, add a line-color attribute and provide your color as a hexadecimal or RGB value.
For your line style, add a line-style attribute. Specify your choice of solid (default), dashed, or dotted line. You can also style your line width by adding a line-width attribute with a pixel value.
{
type: 'line',
series: [
{
values: [20,40,25,50,15,45,33,34],
lineColor: '#6666FF', /* hexadecimal or RGB value */
lineStyle: 'dashed', /* 'solid' | 'dotted' */
lineWidth: '5px' /* in pixels */
}
]
}
Marker Color, Size, and Width
To modify your markers, create a marker object and place it in the chart data object of the plot you want to style. With markers, you’ll want to specify both the fill (color and size) and border (color and width). For fill color, add a background-colorattribute and provide your color as a hexadecimal or RGB value. For fill size, add a size attribute and provide a pixel value.
To style the border color, add a border-color attribute and specify your color value. For border width, add a border-width attribute and specify your pixel value.
Note: Learn more about markers with our Markers Tutorial.
{
type: 'line',
series: [
{
values: [20,40,25,50,15,45,33,34],
marker: { /* Marker object */
backgroundColor: '#FF0066', /* hexadecimal or RGB value */
size: 8, /* in pixels */
borderColor: '#6666FF', /* hexadecimal or RBG value */
borderWidth: '5px' /* in pixels */
}
}
]
}
