This document describes the various types of bar charts that you can create using the Chart API.

Table of Contents

Overview

There are a variety of bar charts that you can create, including vertical, horizontal, grouped, stacked, and overlapped versions of each.

Bar charts are good for side-by-side comparison and spotting trends in a small number of discrete data points. They're a good alternative to line charts when you have only a few data points in a series.

There are three general ways to show multiple series in a bar chart:

Grouped	Stacked	Overlapped
cht=bvg chd=t:5,5,5|10,10,10|15,15,15	cht=bvs chd=t:5,5,5|10,10,10|15,15,15	cht=bvo chd=t:5,5,5|10,10,10|15,15,15

You can control bar width and spacing using the chbh parameter. If you do not specify chbh, some bars might be cropped.

Note that by default, all series are displayed in the same color; if you don't specify different colors for different series, it will be hard to distinguish that there are multiple series in your chart. See Series Colors for details.

Bar charts will display at least one axis by default; if you want to hide any default axes, use the chxs parameter and specify an underscore for the <axis_or_tick> value.

If you use simple text format in stacked charts, you should beware that the chart will crop anything above 100 as the total stack height unless you add custom scaling, as shown here:

Without scaling, the middle three bars exceed 100, and get cropped in a simple text formatted data chart.	cht=bhs chco=4D89F9,C6D9FD chd=t:10,50,60,80,40|   50,60,100,40,20
If we want to show the full stacked bar length, we must either use a different encoding scheme, or use text formatting with custom scaling. The maximum scale value should be relative to the total stacked bar height; this example goes up to 160 (the maximum summed value).	cht=bhs chco=4D89F9,C6D9FD chd=t:10,50,60,80,40|   50,60,100,40,20 chds=0,160

Chart Types (cht)

There are a few different types of bar charts that you can make. Specify a bar chart with the following syntax:

Syntax

cht=<chart_type>

Where <chart_type> is one of the the following types:

Chart Type	Description	Example
bhs	Horizontal bar chart with stacked bars. The first example (all bars in dark blue) has one data series. The second example (bars in dark and pale blue) has two series. (It is also scaled to show the summed bar value, which exceeds 100). As you can see, multiple series are stacked. If you don't specify different series colors, all colors will be the same (and the bars won't look stacked). You can also specify a color for each bar within a single series.	cht=bhs chco=4D89F9 cht=bhs chco=4D89F9,C6D9FD chd=t:10,50,60,80,40|   50,60,100,40,20 chds=0,160
bvs	Vertical bar chart with stacked bars. This example has two series, and uses text format with custom scaling to ensure that all stacked values are fully visible. Note that if you move the zero line in a bvs chart using the chp parameter, if a bar is less than this value it will be displayed below the zero line, and if it is greater than this value it will be displayed above the zero line.	cht=bvs chco=4D89F9,C6D9FD chd=t:10,50,60,80,40|   50,60,100,40,20 chds=0,160
bvo	Vertical bar chart in which bars are stacked in front of one another, rather than atop one another. The height of each bar is its individual value, not its summed value. Bars will be sorted for you by height so that all bars are visible.	cht=bvo chd=t:   10,50,60,80,40   50,60,100,40,20   30,30,75,20,60
bhg	Horizontal bar charts with grouped bars. The top chart uses default group spacing values; the bottom chart uses the chbh parameter to modify the default bar width and group spacing to make groups more obvious.	cht=bhg chco=4D89D9,C6D9FD cht=bhg chco=4D89D9,C6D9FD chbh=15,4,15
bvg	Vertical bar chart with grouped bars.	cht=bvg chco=4D89F9,C6D9FD chbh=15,4,15

Back to top

Series Colors chco

You can specify the colors of individual bars, individual series, or multiple series using the chco parameter. If you don't specify a different color for each series, all series will be the same color.

Syntax

chco=<series_1_color>, ..., <series_n_color>

    or

chco=<series_1_bar_1>|<series_1_bar_2>|...|<series_1_bar_n>,<series_2>,...,<series_n>

<color>

An RRGGBB format hexadecimal number to apply to a series or individual bar. To apply the color to the whole series, it should be comma-delimited. To apply the color to an individual bar, it should be pipe-delimited. You can mix these two formats. See the table below for examples. Whenever you have fewer color values than data points or series, the colors will cycle through the list again, starting from the first color in that group.

Examples

Description	Example
One color per series, with comma-delimited colors.	cht=bvs chco=4D89F9,C6D9FD
One color per value, with pipe-delimited colors.	cht=bvs chco=FFC6A5|FFFF42|DEF3BD|00A5C6|DEBDDE
A combination of series colors and individual bar colors. This example shows a bar chart with two series. The first series all black (000000,) and comma-delimited. The second series is pipe-delimited, and assigns a different color for each point (FF0000|00FF00|0000FF).	chco=000000,FF0000|00FF00|0000FF chd=s:FOE,elo
This example demonstrates setting different colors for every bar in a multi-series chart.	chco=   FF0000|00FF00|0000FF,FFC6A5|DEF3BD|C6EFF7
You can also specify fills to color a series with solid, striped, or gradient colors. Solid fills look the same as using chco, but stripes or gradients create unique effects.	chd=   t:10,40,60,80,30,20 chf=   b0,lg,0,FFE7C6,0,76A4FB,1 chd=t:   40,40,60,80   30,50,55,86 chf=   b0,ls,0,FFE7C6,.3,76A4FB,.1   b1,ls,0,FF0000,.3,FFBFBF,.1

Back to top

Bar Labels

Bar charts support standard axis labels, but labels along the base of the bars are assigned to individual bars, rather than spread out along the bar chart. (To spread out labels evenly, use the chxp parameter as described below.) If you specify axis labels but don't specify custom labels along the bar axis, the bar labels will be the index number of each bar or group of bars. You can customize axis labels using the chxl parameter.

Description	Example
A bar chart using the default x-axis labels.	chxt=x,y
A bar chart using custom x-axis labels.	chxt=x,y chxl=0:|Jan|Feb|Mar|Apr|May
If you have a different number of labels and bars and want to space the labels evenly (rather than beneath each bar), use the chxp parameter with the syntax <axis_index>,0 where axis_index is the index of the axis to be labeled, and 0 indicates that they should be spaced evenly. (This is because a single 0 indicates the location of the first label, and no further values indicates that labels should be auto-placed evenly across the axis.) Top chart: Three chart labels are applied to five bars. The labels are aligned beneath the first three bars. Bottom chart: The same three labels are applied to five bars, but chxp=0,0 causes the labels to be evenly spaced across the x-axis (axis index 0).	chd=s:cEj9U chxt=x,y chxl=0:|2001|2002|2003 chd=s:cEj9U chxt=x,y chxl=0:|2001|2002|2003 chxp=0,0

Back to top

Bar Width and Spacing chbh

You can optionally specify custom values for bar widths and spacing between bars and groups. You can only specify one set of width values for all bars. If you don't specify chbh, all bars will be 23 pixels wide, which means that the end bars can be clipped if the total bar + space width is wider than the chart width.

Syntax

chbh=
  <bar_width_or_scale>,<space_between_bars>,<space_between_groups>

<bar_width_or_scale>

The width of the bar. You can specify widths and spacing absolutely or relatively, by entering one of the following values. Default value is 23 pixels, absolute value.

• width - Bar width, in pixels. All spacing values are also absolute values, in pixels. Bars can be clipped if the chart isn't wide enough.
• a - space_between_bars and space_between_groups are given in absolute units (or default absolute values, if not specified). Bars will be resized so that all bars will fit in the chart.
• r - space_between_bars and space_between_groups are given in relative units (or default relative values, if not specified) Relative units are floating point values compared to the bar width, where the bar width is 1.0: for example, 0.5 is half the bar width, 2.0 is twice the bar width. Bars can be clipped if the chart isn't wide enough.

<space_between_bars>

[Optional] Space between bars in the same group. If sizing is absolute, this is a width in pixels; if sizing is relative, this is a floating point value where 1.0 is the bar width. Default value is 4 pixels for absolute values, or 4/23 for relative values.

<space_between_groups>

[Optional] Space between bar groups in the same group. If sizing is absolute, this is a width in pixels; if sizing is relative, this is a floating point value where 1.0 is the bar width. Default value is 8 pixels for absolute values, or 8/23 for relative values.

You cannot omit intermediate optional parameters; you must end with a stated value. For example: chbh=10,5,10 is valid, chbh=10,,10 is not, chbh=10,5, is not.

Description	Example
This chart uses the a value to resize values automatically. The first chart specifies no group spacing, so groups are not apparent. The second chart adds some spacing (15 pixels) between groups.	chbh=a chbh=a,5,15
This chart uses the r value to specify sizes relative to the bar width. In this chart, spacing between bars is 0.5x bar width, and between groups is 1.5x bar width.	chbh=r,0.5,1.5
The first chart has five values in each series, but the chart is too small to hold all the bars with default values: 10 * 23 pixels for bars + 5 * 4 pixels for spacing + 4 * 8 pixels for group spacing                          282 pixels -- More than the 190 pixel chart width ...so some bars are clipped. The second chart specifies absolute bar and spacing values to fit all bars in the chart.	chbh omitted chs=190x125 two series, five values/series chbh=10,5,10

Back to top

Zero Line chp

You can specify a custom zero line for your chart using either the chp parameter, or using text encoding with data scaling. These zero lines work in two different ways:

• Data scaling - When you use text format data with the scaling parameter chds, it will push the zero line up as much as necessary to show all negative values.
• chp parameter - You can also move the zero line manually, in any data format, to any location, using the chp parameter. This actually creates an artificial zero line, and redraws the bars as the difference between the data value and your arbitrary zero value (that is, the bars are drawn from your zero line to the bar value). This cannot be used in combination with chds.

Syntax

chp=
  <zero_value_series_1>,
   ...,
  <zero_value_series_n>

<zero_value_series_1>

A floating point value from 0.0—1.0, inclusive, where 0.0 is the bottom of the axis, and 1.0 is top of the axis. Bars will be redrawn to show the difference between this and their value.

Description	Example
Here are three copies of a bar chart with the same data: The first shows the chart with no zero line specified. The second shows the chart with a zero line of 0.2, or the zero line is pushed 0.2 of the distance up the y-axis. Notice that the value 20 has disappeared because it's right on the new zero line. The third shows the chart with a zero line of 0.5. Now the 20 value has reappeared as a negative value, as is the 40 value (which is less than 50). This is because bars are drawn from the new zero line location to the actual data value, so values less than 50 on the chart go downward, and values greater than 50 are drawn upward.	chd=t:20,40,60,80,95 No zero line specified. chd=t:20,40,60,80,95 chp=0.2 chd=t:20,40,60,80,95 chp=0.5
This example shows setting a zero line by using text formatted data with custom scaling (chds). You cannot use chds and chp together. The example has values ranging from -60 to 120. The scale is set to -80 to 140, to leave space above and below the bars.	chd=t:30,-60,50,120,80 chds=-80,140

Back to top

Compound Charts

You can add lines, candlesticks, and shape markers to a bar chart to make a compound chart. See Compound Charts for more details.

Markers on Specific Bars (cht=bvg only)

By default, when you draw a chm marker on a grouped vertical chart, the marker is drawn on the same series from which it derives its data. If the data is a hidden series, the default behavior is to center the marker on the bar group.

However, with vertically grouped bar charts (type bvg) you can specify a placement series that is different from the marker's data series. To do this, specify the <series_index> parameter (the third parameter) using the following syntax: <data_series_index>:<placement_series_index>.

Note that if you specify a hidden or nonexistent placement series, the marker will be centered horizontally on the group.

The best way to use this feature is to use a hidden series for the marker data, and place the marker on a visible series.

The following examples show the default behavior, with both the data series and placement series the same, and the advanced syntax, specifying a different data and placement series.

Hidden data series, default marker placement	Hidden data series, advanced marker placement
chd=t2: // First two series are visible   10,20,30,40,50  // Red bars   20,40,60,80,100 // Blue bars   20,20,20,20,20  // Hidden: black circle data   30,30,30,30,30  // Hidden: black square data chm=   o,000000,2,,10 // Circle markers   s,000000,3,,10 // Square markers In this example, basic syntax specifies that marker data and placement should be on the same series. Since this is a hidden series, default placement is centered vertically on each group.	chd=t2: // First two series are visible   10,20,30,40,50  // Red bars   20,40,60,80,100 // Blue bars   20,20,20,20,20  // Hidden: black circle data   30,30,30,30,30  // Hidden: black square data chm=   o,000000,2:0,,10 // Circle markers   o,000000,3:1,,10 // Square markers In this example, advanced syntax specifies a different data source and placement series for the markers. Circles use data from hidden series 2 and are placed on series 0; squares use data from hidden series 3 and are placed on series 1.

The following example shows how to add several different marker types to individual bars in a grouped bar chart. Note how the black circle is centered on the groups, because it specifies a hidden series as the placement series.

chd=t4: // First four series are rendered as bars. Remaining data is hidden.
  5,10,15,20,25,30   // Purple bar
  10,20,30,40,50,60  // Blue bar
  30,40,50,60,70,80  // Olive bar
  5,5,5,5,5,5        // Black bar
  0,15,25,30,45,55   // Hidden data: Purple circle, blue error bar start
  15,30,40,45,55,65  // Hidden data: Blue error bar end
  20,35,45,50,55,65  // Hidden data: Yellow error bar start
  40,45,55,80,75,85  // Hidden data: Yellow error bar end
chm=                 // Markers:
  o,D000D0,4:0,,10   // Purple circle: data series 4, placement series 0 (purple)
  E,00D0D0,4:1,,1:10 // Blue error bars: data series 4, placement series 1 (blue)
  E,D0D000,6:2,,1:10 // Yellow error bars: data series 6, placement series 2 (olive)
  o,000000,3:4,,10   // Black circle: data series 3, placement 4 (hidden placement series, centered in group)

Back to top

Standard Features

The rest of the features on this page are standard chart features.