Chart
Widget

Displays a chart generated from data. Charts are rendered using the third-party Chart.js library (MIT license).

Chart types

The following chart types are supported:

line
bar (vertical and horizontal)
pie
donut (nested pie chart)
scatter (X/Y chart)
bubble (scatter chart with varying bubble sizes)
radar

Configuring data

The chart requires labels and one or more data series to be defined in order to display data. Series are specified as DataSeries objects. In a line chart, each line is one series. Each series normally gets its own color in the chart, except in the case of pie and donut charts, where each series is one full ring, and the colors are assigned to slices (data points) instead.

Data is provided to the chart using the data config. This should be an array of data Models or objects. Data points are drawn from individual fields in the records according to how the series of the chart are configured. For example, one line (series) in a line chart might show data values from the records' field FY2023, and a second line might show values from the field FY2024. In that case there would be two series defined on the chart, each with its field property set to "FY2023" or "FY2024" accordingly.

For chart types that combine multiple data values into a single series, like scatter or bubble, each series must also specify its role and seriesIndex. See DataSeries.

For charts with an X-axis (such as line and bar charts), the labels configuration specifies the data series to use as the ticks on the X-axis. For pie and donut charts, labels defines the slice labels.

The data config is also required; these are the records that supply the actual data values used in the chart.

Customizing appearance

Various configuration options allow you to change the look and feel of the chart. Chart elements can be turned on and off using showTitle, showSubtitle, showLegend, showAxes, and showControls. Spacing can be adjusted with chartPadding, titlePadding, and subtitlePadding. Fonts can be set with titleFont and subtitleFont. Data series line thickness, dash, and opacity can also be configured.

Try using the controls in the demo below to fine-tune the Chart appearance. To enable similar chart customization UI in your app, see the ChartDesigner widget.

Interactivity

By default, the chart can be downloaded as an image file using a button at the top right of the chart. To hide the download button, set showControls to false.

Tooltips appear as you mouse over data points on the chart. They can be disabled using showTooltips.

Animation

Animation is enabled by default. To disable animation, set animate to false.

Fields

Fields belong to a Model class and define the Model data structure

barWidth : Number

(Optional) For 'bar' charts, the amount of the available bar area each bar in this series should occupy, from 0 to 1. Default: 0.9.
field : String

The name of the record field containing the data for this series.
fillColorField : String

(Optional) The name of a field in the chart data to use as the background color for each data element (e.g. bar).
label : String

The name of the series to display in the legend.
role : DataSeriesRole

(Optional) Required when using certain chart types, for example scatter, where series can be arbitrarily assigned to different axes. The role determines how this series is used in the chart.

Configs

Configs are options you supply in a configuration object when creating an instance of this class

chartType : 'line'/'bar'/'pie'/'donut'/'scatter'+ 2 moreline

Basic type of chart.

Has a corresponding runtime chartType property.
subtitle : String

The chart subtitle.

Has a corresponding runtime subtitle property.
title : String

The chart title.

Has a corresponding runtime title property.
max : Number

Max value for the Y axis, for chart types that have one.

Has a corresponding runtime max property.
min : Number

Min value for the Y axis, for chart types that have one.

Has a corresponding runtime min property.
showTicks : Booleantrue

Whether to show tick marks and labels on the chart axes.

Has a corresponding runtime showTicks property.
tickFont : Font
The font to use for tick labels on the chart axes.

Default:
```
{
   size      : 14,
}
```
Has a corresponding runtime tickFont property.
tickMarkColor : String

Set the color of the tick mark lines in the axis area, or null to default to axisColor.

Has a corresponding runtime tickMarkColor property.
legendPosition : 'top'/'right'/'bottom'/'left'/'inline-start'+ 1 morebottom

Where the chart's legend should appear relative to the main chart content. Options inline-start and inline-end function as in CSS, with horizontal positioning controlled by RTL mode.

Has a corresponding runtime legendPosition property.
legendScale : Number1

Optional scale factor to increase or decrease the size of the chart legend.

Has a corresponding runtime legendScale property.
showAxes : Boolean/Arraytrue

private

Whether to show all chart axes (true), hide all axes (false), or an array indicating which axes to show. If array, valid elements are 'x' and 'y'.

Has a corresponding runtime showAxes property.
data : Model[]/Object[][]

The data records or objects containing data to display in the chart.

Has a corresponding runtime data property.
labels : DataSeries

For line and bar charts, this series defines the data values to use as ticks for the x-axis. For pie and donut chart, it defines the data values to use as slice labels.

Has a corresponding runtime labels property.
series : DataSeries[]

One or more data series to display in the chart.

Has a corresponding runtime series property.
chartTooltip : ChartTooltipConfig

Chart tooltip configuration object. Configures the tooltip that appears when hovering over chart data points. This follows the Chartjs tooltip configuration specification. This will only be applied if showTooltips is true.

Has a corresponding runtime chartTooltip property.
interactive : Booleantrue

Whether to do dynamic highlighting and other interactivity as the mouse cursor moves over the chart.

Has a corresponding runtime interactive property.
showTooltips : Booleantrue

Whether to show tooltips when the mouse cursor hovers over chart elements.

Has a corresponding runtime showTooltips property.
animate : Booleantrue

Whether to animate chart data changes.

Has a corresponding runtime animate property.
animationDuration : Number400

Set the duration in milliseconds for all animations.

Has a corresponding runtime animationDuration property.
barDirection : 'vertical'/'horizontal'vertical

Layout direction for the bar chart type.

Has a corresponding runtime barDirection property.
showControls : Booleantrue

Whether to show the chart's control button menu, for example, the download button.

Has a corresponding runtime showControls property.
bubbleScaleFactor : Number1

Scale factor to apply to the computed size of bubbles in the bubble chart type.

Has a corresponding runtime bubbleScaleFactor property.
pointSize : Number

Radius of data points, in pixels.

Has a corresponding runtime pointSize property.
showPoints : Booleantrue

Whether to show data point markers on the chart.

Has a corresponding runtime showPoints property.

Properties

Properties are getters/setters or publicly accessible variables on this class

isChart : Booleantrue

READONLY

static

ADVANCED

Identifies an object as an instance of Chart class, or subclass thereof.

chartType : 'line'/'bar'/'pie'/'donut'/'scatter'+ 2 moreline

Basic type of chart.

Has a corresponding chartType config.
subtitle : String

The chart subtitle.

Has a corresponding subtitle config.
title : String

The chart title.

Has a corresponding title config.
max : Number

Max value for the Y axis, for chart types that have one.

Has a corresponding max config.
min : Number

Min value for the Y axis, for chart types that have one.

Has a corresponding min config.
showTicks : Booleantrue

Whether to show tick marks and labels on the chart axes.

Has a corresponding showTicks config.
tickFont : Font
The font to use for tick labels on the chart axes.

Default:
```
{
   size      : 14,
}
```
Has a corresponding tickFont config.
tickMarkColor : String

Set the color of the tick mark lines in the axis area, or null to default to axisColor.

Has a corresponding tickMarkColor config.
legendPosition : 'top'/'right'/'bottom'/'left'/'inline-start'+ 1 morebottom

Where the chart's legend should appear relative to the main chart content. Options inline-start and inline-end function as in CSS, with horizontal positioning controlled by RTL mode.

Has a corresponding legendPosition config.
legendScale : Number1

Optional scale factor to increase or decrease the size of the chart legend.

Has a corresponding legendScale config.
showAxes : Boolean/Arraytrue

private

Whether to show all chart axes (true), hide all axes (false), or an array indicating which axes to show. If array, valid elements are 'x' and 'y'.

Has a corresponding showAxes config.
isChart : Booleantrue

READONLY

ADVANCED

Identifies an object as an instance of Chart class, or subclass thereof.
data : Model[]/Object[][]

The data records or objects containing data to display in the chart.

Has a corresponding data config.
labels : DataSeries

For line and bar charts, this series defines the data values to use as ticks for the x-axis. For pie and donut chart, it defines the data values to use as slice labels.

Has a corresponding labels config.
series : DataSeries[]

One or more data series to display in the chart.

Has a corresponding series config.
chartTooltip : ChartTooltipConfig

Chart tooltip configuration object. Configures the tooltip that appears when hovering over chart data points. This follows the Chartjs tooltip configuration specification. This will only be applied if showTooltips is true.

Has a corresponding chartTooltip config.
interactive : Booleantrue

Whether to do dynamic highlighting and other interactivity as the mouse cursor moves over the chart.

Has a corresponding interactive config.
showTooltips : Booleantrue

Whether to show tooltips when the mouse cursor hovers over chart elements.

Has a corresponding showTooltips config.
animate : Booleantrue

Whether to animate chart data changes.

Has a corresponding animate config.
animationDuration : Number400

Set the duration in milliseconds for all animations.

Has a corresponding animationDuration config.
barDirection : 'vertical'/'horizontal'vertical

Layout direction for the bar chart type.

Has a corresponding barDirection config.
showControls : Booleantrue

Whether to show the chart's control button menu, for example, the download button.

Has a corresponding showControls config.
bubbleScaleFactor : Number1

Scale factor to apply to the computed size of bubbles in the bubble chart type.

Has a corresponding bubbleScaleFactor config.
pointSize : Number

Radius of data points, in pixels.

Has a corresponding pointSize config.
showPoints : Booleantrue

Whether to show data point markers on the chart.

Has a corresponding showPoints config.

Functions

Functions are methods available for calling on the class

applyFont( optionsNode, font )

private

Apply a Font to the ChartJS options for a specific element.
download( filename )

Download the chart as a PNG image with the given filename (if any).
setData( data, skipAnimationfalse )

Set data for the chart, an alternative to setting the data config for when you want control over if the chart animates the change or not.

Note that a chart configured with animate: false will never animate, even if you call this method with skipAnimation set to false.

Type definitions

Font
A font configuration for display.
Properties
- family : String
  
  The CSS font family name, e.g. "Arial Narrow".
- size : Number
  
  The font size in points (pts).
- bold : Boolean
  
  Whether the font weight is bold (true) or regular (false).
- weight : Number
  
  Specific font weight, e.g. 400 for regular, 700 for bold. Overrules bold.
- italic : Boolean
  
  Whether the font is italic (true) or regular (false).
- underline : Boolean
  
  Whether the font is underlined.
- color : String
  
  The font text CSS color, e.g. "#ff0000".
- darkColor : String
  
  The font text CSS color to use in dark themes, e.g. "#ff0000".
DataSeries
Defines a data series for use in a chart.
Properties
- field : String
  
  The name of the record field containing the data for this series.
- label : String
  
  The name of the series to display in the legend.
- role : DataSeriesRole
  
  Required when using certain chart types, for example scatter, where series can be arbitrarily assigned to different axes. The role determines how this series is used in the chart.
- fillColorField : String
  
  The name of a field in the chart data to use as the background color for each data point.
- pointRadiusField : String
  
  The name of a field in the chart data to use as the radius for each data point.
- fillColor : String
  
  Static background color to use for the bars etc. (depending on type of chart)
- strokeColor : String
  
  Static border color to use for the bars etc. (depending on type of chart)
- strokeWidth : Number
  
  Static border width to use for the bars etc. (depending on type of chart)
- borderRadius : Number
  
  Static border radius to use for the bars etc. (depending on type of chart)
- stepped : Boolean
  
  Set to true to draw a stepped line.
- fill : Boolean
  
  Set to true to fill the area under the line.
- borderDash : Number[]
  
  Set to an array of numbers to draw a dashed line. For example, [5, 5] will draw a dashed line with 5px dashes and 5px gaps.
- barWidth : Number
  
  For 'bar' charts, a number between zero and one that specifies the proportion of the available bar area the bars for this series should fill - 0 for none, 1 for all space. Default: 0.9.
DataSeriesRole
An object that defines the role a given DataSeries plays in defining data series, when the chart type allows series to be assigned to different axes.
Properties
- axis : 'x'/'y'/'size'
  
  The axis along which values in this series will be plotted. size is applicable only to the bubble chart type.
- seriesIndex : Number
  
  When multiple data points are combined into a single series (for example x, y, and size roles), this property indicates the series to which this role belongs.
ChartTooltipCallbacks
Chart tooltip callback functions configuration object. Refer to the ChartJS tooltip callbacks documentation for details.
Properties
- beforeTitle : Function
  
  Callback for customizing tooltip title before rendering
- title : Function
  
  Callback for customizing tooltip title
- afterTitle : Function
  
  Callback for customizing tooltip title after rendering
- beforeBody : Function
  
  Callback for customizing tooltip body before rendering
- beforeLabel : Function
  
  Callback for customizing individual labels before rendering
- label : Function
  
  Callback for customizing individual labels (most commonly used)
- labelColor : Function
  
  Callback for customizing label colors
- labelTextColor : Function
  
  Callback for customizing label text colors
- labelPointStyle : Function
  
  Callback for customizing label point styles
- afterLabel : Function
  
  Callback for customizing individual labels after rendering
- afterBody : Function
  
  Callback for customizing tooltip body after rendering
- beforeFooter : Function
  
  Callback for customizing tooltip footer before rendering
- footer : Function
  
  Callback for customizing tooltip footer
- afterFooter : Function
  
  Callback for customizing tooltip footer after rendering
ChartTooltipConfig
Chart tooltip configuration object that defines the appearance and behavior of chart tooltip. See the ChartJS documentation for more information.
Properties
- external : Function
  
  External tooltip function. See ChartJS external tooltip documentation
- mode : 'point'/'nearest'/'index'/'dataset'/'x'+ 1 more
  
  Sets which elements appear in the tooltip
- position : 'average'/'nearest'
  
  The mode for positioning the tooltip. average mode will place the tooltip at the average position of the items displayed in the tooltip. 'nearest' will place the tooltip at the position of the element closest to the event position.
- callbacks : ChartTooltipCallbacks
  
  Tooltip callback functions
- itemSort : Function
  
  Function to sort tooltip items
- filter : Function
  
  Function to filter tooltip items
- backgroundColor : String
  
  Background color of the tooltip
- titleColor : String
  
  Color of title text
- titleFont : Font
  
  Font configuration for title
- titleAlign : 'left'/'center'/'right'
  
  Horizontal alignment of title text
- titleSpacing : Number
  
  Spacing to add to top and bottom of each title line
- titleMarginBottom : Number
  
  Margin to add on bottom of title section
- bodyColor : String
  
  Color of body text
- bodyFont : Font
  
  Font configuration for body
- bodyAlign : 'left'/'center'/'right'
  
  Horizontal alignment of body text
- bodySpacing : Number
  
  Spacing to add to top and bottom of each tooltip item
- footerColor : String
  
  Color of footer text
- footerFont : Font
  
  Font configuration for footer
- footerAlign : 'left'/'center'/'right'
  
  Horizontal alignment of footer text
- footerSpacing : Number
  
  Spacing to add to top and bottom of each footer line
- footerMarginTop : Number
  
  Margin to add before drawing the footer
- padding : Number/Object
  
  Padding inside the tooltip
- caretPadding : Number
  
  Extra distance to move the end of tooltip arrow away from tooltip point
- caretSize : Number
  
  Size, in px, of the tooltip arrow
- cornerRadius : Number/Object
  
  Radius of tooltip corner curves
- multiKeyBackground : String
  
  Color to draw behind colored boxes when multiple items are in tooltip
- displayColors : Boolean
  
  If true, color boxes are shown in the tooltip
- boxWidth : Number
  
  Width of the color box if displayColors is true
- boxHeight : Number
  
  Height of the color box if displayColors is true
- boxPadding : Number
  
  Padding between the color box and the text
- usePointStyle : Boolean
  
  Use corresponding point style instead of color boxes
- borderColor : String
  
  Color of the border
- borderWidth : Number
  
  Size of the border
- xAlign : 'left'/'center'/'right'
  
  Position of tooltip caret in X direction
- yAlign : 'top'/'center'/'bottom'
  
  Position of tooltip caret in Y direction

Chart
Widget

Chart types

Configuring data

Customizing appearance

Interactivity

Animation

Fields

Configs

Properties

Functions

Type definitions

Properties

Properties

Properties

Properties

Properties

Source path

Inheritance tree4

Mixins6

Contents

Chart Widget

Chart types

Configuring data

Customizing appearance

Interactivity

Animation

Fields

Configs

Properties

Functions

Type definitions

Properties

Properties

Properties

Properties

Properties

Source path

Inheritance tree4

Mixins6

Contents

Chart
Widget