Framework:Javascript GridAngular GridReact GridVue Grid

JavaScript Charts: Bar and Column Series

Because bar series are just transposed column series and have the same configuration, this section covers both series at once.

Bar series are a good choice to show values for a discrete set of objects, such as item categories, specific items, or time periods such as years or quarters.

Column Series

Regular Columns

To create a column chart, we need to use series type 'column'. We also have to provide the xKey and at least one yKey.

Since 'column' and 'bar' series can be stacked or grouped, they can have multiple yKeys, with one key for each stack/group component.

A minimal 'column' series config would therefore look like this:

series: [{
    type: 'column',
    xKey: 'quarter',
    yKeys: ['iphone']
}]

In the snippet above we are using the 'iphone' as the only yKey, to show revenue per quarter for this product alone. Using this simple series config produces the following chart:

Stacked Columns

If the goal is to show the quarterly revenue for each product category, multiple yKeys can be used. To go from a regular column chart above to a stacked one below, all we do is add some more yKeys like so:

yKeys: ['iphone', 'mac', 'ipad', 'wearables', 'services']

And that simple change transforms our chart into this:

Note that in the example code we also added yNames along with yKeys which configure the display names to make sure we have nice looking tooltip headers and legend entries.

yNames: ['iPhone', 'Mac', 'iPad', 'Wearables', 'Services']

Grouped Columns

If we want to show quarterly revenue for each product category as grouped columns, we can simply take the stacked column config from the example above and set the grouped property of the series to true:

grouped: true

This will produce the following chart:

Normalized Columns

Going back to our stacked column example, if we wanted to normalize the totals so that each column's segments added up to a certain value, for example 100%, we could add the following to our series config:

normalizedTo: 100

It's possible to use any non-zero value to normalize to.

Column Labels

It's possible to add labels to columns, by adding the following to the series config:

label: {}

That's it. The config can be empty like that. However, you might want to customise your labels. For example, by default the values are rounded to two decimal places for the labels, but in the example below even that is too much, so we use a label formatter that simply returns the integer part of the number:

label: {
    formatter: function (params) {
        // if the data contains values that are not valid numbers,
        // the formatter's `value` will be `undefined`
        return params.value === undefined ? '' : params.value.toFixed(0);
    }
}

The above formatter produces an attractive chart where the labels don't stick out of their columns:

It's best to avoid using labels with grouped columns (or bars), because columns in grouped mode tend to be narrow and often won't fit a label.

To learn more about label configuration please refer to the API reference below.

Bar Series

'bar' series configuration is exactly the same as 'column' series configuration and all the same modes (regular, stacked, grouped, normalized) apply to bars just as they do to columns.

To create a bar chart all you need to do is use type: 'bar' instead of type: 'column' in the series config and swap the axes — the 'category' axis moves from the bottom to the left of a chart, and the 'number' axis takes its place instead, moving from the left to the bottom:

axes: [
    {
        type: 'number',
        position: 'bottom'
    },
    {
        type: 'category',
        position: 'left'
    }
]

With these simple changes we go from stacked columns to stacked bars:

API Reference

xKey *
string
The key to use to retrieve x-values from the data.
xName
string
A human-readable description of the x-values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
yKeys *
string[]
The keys to use to retrieve y-values from the data.
yNames
string[]
Human-readable descriptions of the y-values. If supplied, a corresponding yName will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
data *
object[]
The data to use when rendering the series. If this is not supplied, data must be set on the chart instead.
visible
boolean
Whether or not to display the series.
Default: true
showInLegend
boolean
Whether or not to include the series in the legend.
Default: true
cursor
string
The cursor to use for hovered bars/columns. This config is identical to the CSS cursor property.
Default: 'default'
tooltip
Series-specific tooltip configuration.
See tooltip for more details.
grouped
boolean
Whether to show different y-values as separate bars (grouped) or not (stacked).
Default: false
normalizedTo
number
The number to normalise the bar stacks to. Has no effect when grouped is true. For example, if normalizedTo is set to 100, the bar stacks will all be scaled proportionally so that each of their totals is 100.
fills
string[]
The colours to cycle through for the fills of the bars.
Default: ['#f3622d', '#fba71b', '#57b757', '#41a9c9', '#4258c9', '#9a42c8', '#c84164', '#888888']
fillOpacity
number
The opacity of the fill for the bars.
Default: 1
strokes
string[]
The colours to cycle through for the strokes of the bars.
Default: ['#aa4520', '#b07513', '#3d803d', '#2d768d', '#2e3e8d', '#6c2e8c', '#8c2d46', '#5f5f5f']
strokeOpacity
number
The opacity of the stroke for the bars.
Default: 1
strokeWidth
number
The width in pixels of the stroke for the bars.
Default: 1
highlightStyle
Configuration for the highlighting used when the bars are hovered over.
See highlightStyle for more details.
shadow
Configuration for the shadow used behind the chart series.
See shadow for more details.
lineDash
number[]
Defines how the bar/column strokes are rendered. Every number in the array specifies the length in pixels of alternating dashes and gaps. For example, [6, 3] means dashes with a length of 6 pixels with gaps between of 3 pixels.
Default: []
lineDashOffset
number
The initial offset of the dashed line in pixels.
Default: 0
label
Configuration for the labels shown on bars.
See label for more details.
formatter
Function
Function used to return formatting for individual bars/columns, based on the given parameters. If the current bar/column is highlighted, the highlighted property will be set to true; make sure to check this if you want to differentiate between the highlighted and un-highlighted states.
formatter = (params: FormatterParams) => Formatter;

interface FormatterParams {
  datum: any;
  fill: string;
  stroke: string;
  strokeWidth: number;
  highlighted: boolean;
  xKey: string;
  yKey: string;
}

interface Formatter {
  fill: string;
  stroke: string;
  strokeWidth: number;
}
listeners
A map of event names to event listeners.
See listeners for more details.

tooltip

bar > tooltip

Series-specific tooltip configuration.

bar: {
  ...
  tooltip: {
    enabled?: boolean; // default: true
    renderer?: Function;
  }
}
enabled
boolean
Whether or not to show tooltips when the series are hovered over.
Default: true
renderer
Function
Function used to create the content for tooltips.
renderer = (params: RendererParams) => string;

interface RendererParams {
  datum: any;
  title?: string;
  color?: string;
  xKey: string;
  xValue: any;
  xName?: string;
  yKey: string;
  yValue: any;
  yName?: string;
}

highlightStyle

bar > highlightStyle

Configuration for the highlighting used when the bars are hovered over.

bar: {
  ...
  highlightStyle: {
    fill?: string; // default: 'yellow'
    stroke?: string;
  }
}
fill
string
The fill colour of the bars when hovered over. Use undefined for no highlight.
Default: 'yellow'
stroke
string
The colour of the stroke around the bars when hovered over. Use undefined for no highlight.

shadow

bar > shadow

Configuration for the shadow used behind the chart series.

bar: {
  ...
  shadow: {
    enabled?: boolean; // default: true
    color?: string; // default: 'rgba(0, 0, 0, 0.5)'
    xOffset?: number; // default: 0
    yOffset?: number; // default: 0
    blur?: number; // default: 5
  }
}
enabled
boolean
Whether or not the shadow is visible.
Default: true
color
string
The colour of the shadow.
Default: 'rgba(0, 0, 0, 0.5)'
xOffset
number
The horizontal offset in pixels for the shadow.
Default: 0
yOffset
number
The vertical offset in pixels for the shadow.
Default: 0
blur
number
The radius of the shadow's blur, given in pixels.
Default: 5

label

bar > label

Configuration for the labels shown on bars.

bar: {
  ...
  label: {
    enabled?: boolean; // default: true
    placement?: 'inside' | 'outside'; // default: 'inside'
    color?: string; // default: 'rgba(70, 70, 70, 1)'
    fontStyle?: 'normal' | 'italic' | 'oblique'; // default: 'normal'
    fontWeight?: 'normal' | 'bold' | 'bolder' | 'lighter' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'; // default: 'normal'
    fontSize?: number; // default: 12
    fontFamily?: string; // default: 'Verdana, sans-serif'
  }
}
enabled
boolean
Whether or not the labels should be shown.
Default: true
placement
string
Where to render series labels relative to the segments.
Default: 'inside'
Options: 'inside', 'outside'
color
string
The colour to use for the labels.
Default: 'rgba(70, 70, 70, 1)'
fontStyle
string
The font style to use for the labels.
Default: 'normal'
Options: 'normal', 'italic', 'oblique'
fontWeight
string
The font weight to use for the labels.
Default: 'normal'
Options: 'normal', 'bold', 'bolder', 'lighter', '100', '200', '300', '400', '500', '600', '700', '800', '900'
fontSize
number
The font size in pixels to use for the labels.
Default: 12
fontFamily
string
The font family to use for the labels.
Default: 'Verdana, sans-serif'

listeners

bar > listeners

A map of event names to event listeners.

bar: {
  ...
  listeners: {
    nodeClick?: Function;
  }
}
nodeClick
Function
The listener to call when a bar/column node is clicked.
nodeClick = (params: NodeClickParams) => any;

interface NodeClickParams {
  type: 'nodeClick';
  series: BarSeries;
  datum: any;
  xKey: string;
  yKey: string;
}

Next Up

Continue to the next section to learn about histogram series.