Results:
Loading...
Javascript Data GridJavascriptReact Data GridReactAngular Data GridAngularVue Data GridVue

React ChartsBar and Column Series

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

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

Column Series

Regular Columns

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

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

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

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

Stacked Columns

If the goal is to show the total quarterly revenue for each product category, multiple stacked series can be used by adding more column-type series.

series: [
    { type: 'column', xKey: 'quarter', yKey: 'iphone', stacked: true },
    { type: 'column', xKey: 'quarter', yKey: 'mac', stacked: true },
    { type: 'column', xKey: 'quarter', yKey: 'ipad', stacked: true },
    { type: 'column', xKey: 'quarter', yKey: 'wearables', stacked: true },
    { type: 'column', xKey: 'quarter', yKey: 'services', stacked: true },
]

This example demonstrates stacked columns using the series configuration above. Additionally:

  • We set yName on each series to configure the display names to provide tooltip headers and legend entries.

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 omit the stacked property.

This will produce the following chart:

Grouped Stacks

Stacks can be displayed in separate groups. The IDs of such groups should be specified in stackGroup property for each series (if left unset for some series, such series will be stacked together).

Normalized Columns

Going back to our stacked column example, if we wanted to normalize the totals so that each column's segments add 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 (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 options.

series: [{
    type: 'bar',
    xKey: 'quarter',
    yKey: 'iphone',
    ...
}]

With this simple change we go from stacked columns to stacked bars:

API Reference

Properties available on the AgBarSeriesOptions<DatumType = any> interface.

xKey *
string
The key to use to retrieve x-values from the data.
yKey *
string
The keys to use to retrieve y-values from the data.
type
'bar' | 'column'
'bar' | 'column'
grouped
boolean
Whether to show different y-values as separate bars (grouped) or not (stacked).
Default: false
stacked
boolean
An option indicating if the bars/columns should be stacked.
stackGroup
string
An ID to be used to group stacked items.
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.
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.
yName
string
Human-readable description 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.
flipXY
boolean
boolean
fill
CssColor
The colour to use for the fill of the bars. 
fill: CssColor;

type CssColor = string
stroke
CssColor
The colours to use for the stroke of the bars. 
stroke: CssColor;

type CssColor = string
strokeWidth
PixelSize
The width in pixels of the stroke for the bars.
Default: 1
strokeWidth: PixelSize;

type PixelSize = number
fillOpacity
Opacity
The opacity of the fill for the bars.
Default: 1
fillOpacity: Opacity;

type Opacity = number
strokeOpacity
Opacity
The opacity of the stroke for the bars.
Default: 1
strokeOpacity: Opacity;

type Opacity = number
lineDash
PixelSize[]
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. 
lineDash: PixelSize[];

type PixelSize = number
lineDashOffset
PixelSize
The initial offset of the dashed line in pixels.
Default: 0
lineDashOffset: PixelSize;

type PixelSize = number
shadow
AgDropShadowOptions
Configuration for the shadow used behind the chart series. 
shadow: AgDropShadowOptions;

interface AgDropShadowOptions {
  // Whether or not the shadow is visible. 
  enabled?: boolean;
  // The colour of the shadow. 
  color?: CssColor;
  // The horizontal offset in pixels for the shadow. 
  xOffset?: PixelSize;
  // The vertical offset in pixels for the shadow. 
  yOffset?: PixelSize;
  // The radius of the shadow's blur, given in pixels. 
  blur?: PixelSize;
}

type CssColor = string

type PixelSize = number
label
AgBarSeriesLabelOptions
Configuration for the labels shown on bars. 
label: AgBarSeriesLabelOptions;

interface AgBarSeriesLabelOptions {
  // Where to render series labels relative to the segments. 
  placement?: AgBarSeriesLabelPlacement;
  // Function used to turn 'yKey' values into text to be displayed by a label. By default the values are simply stringified. 
  formatter?: (params: AgCartesianSeriesLabelFormatterParams) => string;
  // Whether or not the labels should be shown. 
  enabled?: boolean;
  // The font style to use for the labels. 
  fontStyle?: FontStyle;
  // The font weight to use for the labels. 
  fontWeight?: FontWeight;
  // The font size in pixels to use for the labels. 
  fontSize?: FontSize;
  // The font family to use for the labels. 
  fontFamily?: FontFamily;
  // The colour to use for the labels. 
  color?: CssColor;
}

type AgBarSeriesLabelPlacement = 'inside' | 'outside'

interface AgCartesianSeriesLabelFormatterParams {
  // The ID of the series. 
  seriesId: string;
  // The value of yKey as specified on series options. 
  value: number;
}

type FontStyle = 
      'normal' 
    | 'italic' 
    | 'oblique'


type FontWeight = 
      'normal' 
    | 'bold' 
    | 'bolder' 
    | 'lighter' 
    | '100' 
    | '200' 
    | '300' 
    | '400' 
    | '500' 
    | '600' 
    | '700' 
    | '800' 
    | '900'


type FontSize = number

type FontFamily = string

type CssColor = string
tooltip
AgBarSeriesTooltip
Series-specific tooltip configuration. 
tooltip: AgBarSeriesTooltip;

interface AgBarSeriesTooltip {
  // Function used to create the content for tooltips. 
  renderer?: (params: AgBarSeriesTooltipRendererParams) => string | AgTooltipRendererResult;
  // Whether or not to show tooltips when the series are hovered over. 
  enabled?: boolean;
  // The position of the tooltip. By default the tooltip follows the mouse pointer. 
  position?: AgTooltipPositionOptions;
  // Configuration for tooltip interaction. 
  interaction?: AgSeriesTooltipInteraction;
}

interface AgBarSeriesTooltipRendererParams {
  stackGroup?: string;
  // xKey as specified on series options. 
  xKey: string;
  // xValue as read from series data via the xKey property. 
  xValue?: any;
  // xName as specified on series options. 
  xName?: string;
  // yKey as specified on series options. 
  yKey: string;
  // yValue as read from series data via the yKey property. 
  yValue?: any;
  // yName as specified on series options. 
  yName?: string;
  // Datum from the series data array that the tooltip is being rendered for. 
  datum: any;
  // Series title or yName depending on series configuration. 
  title?: string;
  // Series primary colour, as selected from the active theme, series options or formatter. 
  color?: CssColor;
  // The ID of the series. 
  seriesId: string;
}

type CssColor = string

interface AgTooltipRendererResult {
  // Title text for the tooltip header. 
  title?: string;
  // Content text for the tooltip body. 
  content?: string;
  // Tooltip title text color. 
  color?: string;
  // Tooltip title background color. 
  backgroundColor?: string;
}

type AgTooltipPositionOptions = 
      AgMovingTooltipPositionOptions


interface AgMovingTooltipPositionOptions {
  // The type of positioning for the tooltip. By default, the tooltip follows the pointer. 
  type: AgTooltipPositionType;
  // The horizontal offset in pixels for the position of the tooltip. 
  xOffset?: PixelSize;
  // The vertical offset in pixels for the position of the tooltip. 
  yOffset?: PixelSize;
}

type AgTooltipPositionType = 'pointer' | 'node'

type PixelSize = number

interface AgSeriesTooltipInteraction {
  // Set to true to keep the tooltip open when the mouse is hovering over it, and enable clicking tooltip text 
  enabled: boolean;
}
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: AgBarSeriesFormatterParams<DatumType>
) => AgBarSeriesFormat;

interface AgBarSeriesFormatterParams<DatumType> {
  datum: DatumType;
  fill?: CssColor;
  stroke?: CssColor;
  strokeWidth: PixelSize;
  highlighted: boolean;
  xKey: string;
  yKey: string;
  seriesId: string;
  stackGroup?: string;
}

type CssColor = string

type PixelSize = number

interface AgBarSeriesFormat {
  fill?: CssColor;
  stroke?: CssColor;
  strokeWidth?: PixelSize;
}
listeners
AgSeriesListeners<DatumType>
A map of event names to event listeners. 
listeners: AgSeriesListeners<DatumType>;

interface AgSeriesListeners<DatumType> {
  // The listener to call when a node (marker, column, bar, tile or a pie sector) in the series is clicked. 
  nodeClick?: (params: AgSeriesNodeClickParams<DatumType>) => void;
  // The listener to call when a node (marker, column, bar, tile or a pie sector) in the series is double clicked. 
  nodeDoubleClick?: (params: AgSeriesNodeClickParams<DatumType>) => void;
}

interface AgSeriesNodeClickParams<DatumType> {
  // Event type. 
  type: 'nodeClick';
  // Series ID, as specified in series.id (or generated if not specified) 
  seriesId: string;
  // Datum from the series data array. 
  datum: DatumType;
  // xKey as specified on series options 
  xKey?: string;
  // yKey as specified on series options 
  yKey?: string;
  // sizeKey as specified on series options 
  sizeKey?: string;
  // labelKey as specified on series options 
  labelKey?: string;
  // colorKey as specified on series options 
  colorKey?: string;
  // angleKey as specified on series options 
  angleKey?: string;
  // calloutLabelKey as specified on series options 
  calloutLabelKey?: string;
  // sectorLabelKey as specified on series options 
  sectorLabelKey?: string;
  // radiusKey as specified on series options 
  radiusKey?: string;
}
id
string
Primary identifier for the series. This is provided as seriesId in user callbacks to differentiate multiple series. Auto-generated ids are subject to future change without warning, if your callbacks need to vary behaviour by series please supply your own unique id value.
Default: auto-generated value
data
DatumType[]
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.
showInLegend
boolean
Whether or not to include the series in the legend.
cursor
string
The cursor to use for hovered area markers. This config is identical to the CSS cursor property.
highlightStyle
AgSeriesHighlightStyle
Configuration for series markers and series line highlighting when a marker / data point or a legend item is hovered over. 
highlightStyle: AgSeriesHighlightStyle;

interface AgSeriesHighlightStyle {
  // Highlight style used for an individual marker when tapped or hovered over. 
  item?: AgSeriesHighlightMarkerStyle;
  // Highlight style used for whole series when one of its markers is tapped or hovered over. 
  series?: AgSeriesHighlightSeriesStyle;
}

interface AgSeriesHighlightMarkerStyle {
  // The fill colour of a marker when tapped or hovered over. Use `undefined` for no highlight. 
  fill?: CssColor;
  // The opacity of the fill for the highlighted item. 
  fillOpacity?: Opacity;
  // The stroke colour of a marker when tapped or hovered over. Use `undefined` for no highlight. 
  stroke?: CssColor;
  // The stroke width of a marker when tapped or hovered over. Use `undefined` for no highlight. 
  strokeWidth?: PixelSize;
}

type CssColor = string

type Opacity = number

type PixelSize = number

interface AgSeriesHighlightSeriesStyle {
  enabled?: boolean;
  // The opacity of the whole series (area line, area fill, labels and markers, if any) when another chart series or another stack level in the same area series is highlighted by hovering a data point or a legend item. Use `undefined` or `1` for no dimming. 
  dimOpacity?: Opacity;
  // The stroke width of the area line when one of the markers is tapped or hovered over, or when a tooltip is shown for a data point, even when series markers are disabled. Use `undefined` for no highlight. 
  strokeWidth?: PixelSize;
}
nodeClickRange
AgChartInteractionRange
Range from a node a click triggers the listener. 
nodeClickRange: AgChartInteractionRange;

type AgChartInteractionRange = 
      PixelSize 
    | 'exact' 
    | 'nearest'


type PixelSize = number