Charts

Last modified: October 28, 2026

Introduction

The Charts module contains widgets that plot and compare your data in different chart types. The widgets are based on the Plotly JavaScript library.

For more examples of what Charts widgets can do, see the following documents:

Chart Types

The Charts module contains these widgets:

Area, bar, bubble, column, line, and time series charts share the series-based properties described in Common Chart Properties. Heat map and pie chart use a single data source instead of a series list. For properties unique to each chart type, see the page for that chart type.

Common Chart Properties

Data Source Section

Series

The Series property contains the list of data series that the chart shows. Each series is drawn as a separate line, set of bars, or set of bubbles. The order of the list influences how series overlay one another: the first series in the list is drawn lowest, and the series after it are drawn on top.

Series list on the General tab with three single series named Alpha, Beta, and Gamma, and the New, Delete, Edit, Move Up, and Move Down buttons

You do not need to put a chart into a data view to feed data into a widget. To add a series, click New in the Series list. To change a series, select it and click Edit. The Edit Series Item dialog box has four tabs: General, Appearance, Events, and Advanced.

General Tab
General tab of the Edit Series Item dialog box with Data set set to Single series, a microflow data source, and the series name Alpha

The General tab has these properties:

  • Data set – Defines how the series gets its data:
    • Single series – One data source draws one series. This is a good option to start with. To show more data, add more Single series items to the list.
    • Multiple series – One data source draws several series, split by the Group by attribute. This is useful if you have a more complex data model or a microflow that returns the data for all series at once.
  • Data source – The source of the data points for the series. Click Edit to set the data source type and the entity. For a Database data source, you can also add an XPath constraint.
  • Group by – The attribute used to split data points into groups. Each group becomes one series. This property is visible only when Data set is set to Multiple series.
  • Series name – The series name shown in the legend. When Data set is set to Multiple series, use an attribute of the group in this text template, so each series gets its own name.
  • X axis attribute – The attribute used for the value on the X axis.
  • Y axis attribute – The attribute used for the value on the Y axis.
  • Aggregation function – Defines how data is aggregated when multiple Y values are available for a single X value. Possible values are None, Count, Sum, Average, Minimum, Maximum, Median, Mode, First, and Last.
  • Tooltip hover text – The text template for the message shown when the user hovers over a data point.
Appearance Tab

The Appearance tab contains the styling properties for the current series, such as line, marker, bar, or fill colors. These properties differ per chart type. For details, see Chart-Specific Settings.

Color properties on this tab accept a CSS color value, such as blue, #48B0F7, or rgb(72, 176, 247).

Appearance tab of the Edit Series Item dialog box for a line chart, with Line style set to Line with markers and the Line color and Marker color properties
Events Tab

The Events tab contains the On click action property. This action runs when the user clicks a data point in this series. The action runs in the context of the object behind the data point.

Advanced Tab

The Advanced tab contains the Custom series options property. This property holds a JSON object with advanced configuration for this series. For more information, see Custom Series Settings. This property is visible only when Enable advanced options is set to Yes.

Refresh Time (in Seconds)

The Refresh time (in seconds) property reloads a chart's data automatically. It is the last property in the Data source section. It is available for all chart types except Custom chart.

  • 0 (default) – Automatic refresh is disabled.
  • Greater than 0 – The chart reloads all of its data sources this number of seconds after its last data update.

Keep the following in mind:

  • The timer restarts every time the chart's data is updated. This means the chart reloads a set time after the most recent update, not at a fixed clock interval.
  • If a data source is still loading when the timer ends, it is not reloaded again.
  • The chart keeps showing its current data while it reloads, so it does not go blank between refreshes.

Use this property when a chart cannot detect that its data has changed, for example when it shows data from a view entity or aggregated data.

General Section

Enable Advanced Options

If set to Yes, the chart shows the properties on its Advanced tab and the Custom series options property on the Advanced tab of each series. The default value is No.

Show Playground Slot

If set to Yes, the chart shows a Playground slot in the page editor. Place a Chart playground widget in this slot to edit the chart's layout, configuration, and series settings live while the app runs. For more information, see Fine-Tune a Chart with Chart Playground.

Line chart in the page editor with Show playground slot enabled, showing an empty Playground slot drop zone above the chart

X Axis Label and Y Axis Label

These two properties set the labels for the X and Y axis.

Show Legend

Column chart with Alpha and Beta series. The legend on the right side is highlighted with a red square.

This setting controls the visibility of a chart's legend block (highlighted in the picture above). If set to No, the legend block is hidden.

Grid Lines

This property controls the horizontal and vertical grid lines of the chart:

  • None – No grid lines are visible.
  • Horizontal – Only horizontal grid lines are visible.
  • Vertical – Only vertical grid lines are visible.
  • Both – Both horizontal and vertical grid lines are visible.

Dimensions Section

The Dimensions tab sets the size of the chart on the page.

Width Unit

This property sets the unit for the widget width:

  • Percentage – Width is a percentage of the parent width.
  • Pixels – Width is an absolute number of pixels.

Width

This property sets the width of the widget. The default value is 100.

Height Unit

This property sets the unit for the widget height:

  • Percentage of width – Height is a percentage of the widget width. Use this mode to keep the aspect ratio of the chart.
  • Pixels – Height is an absolute number of pixels. This is a good option for most cases.
  • Percentage of parent – Height is a percentage of the parent height. This only works when the parent has a CSS height value.

Height

This property sets the height of the widget. The default value is 75.

Advanced Section

The properties in this section are visible only when Enable advanced options is set to Yes.

Enable Theme Folder Config Loading

If set to Yes, this widget loads global chart settings from the theme/web/com.mendix.charts.json file. Before using this feature, make sure this file is present in your app. For more information, see Use the Charts Theme.

Custom Layout

For more information, see the Custom Layout section below.

Custom Configurations

For more information, see the Custom Configurations section below.

Chart-Specific Settings

Each chart type has its own properties in addition to the common properties above. For details, see the page for each chart type:

Chart Customization

Custom Series Settings

The Plotly library allows you to configure each series in a chart individually.

To add custom settings to a series, do the following:

  1. On the General tab of the chart, set Enable advanced options to Yes.

  2. On the same tab, go to Data source > Series.

  3. Select the series you want to configure, then click Edit.

  4. Open the Advanced tab and paste your custom series settings object in JSON format into Custom series options:

    Series list with the first series, Alpha, selected and the Edit button enabled
    Advanced tab of the Edit Series Item dialog box with a JSON object in Custom series options that sets the line width, line dash, and marker size

To see available series options, see the JavaScript Figure Reference in the Plotly documentation.

Custom Layout

This property allows you to save custom layout settings for this widget.

To save custom layout settings, go to the Advanced tab of the chart and paste your JSON into Custom layout:

Settings dialog box with Advanced tab being active. Tab includes two text area on of which is focused.

These layout settings are passed to the Plotly library. To see available options, see the Layout section of the Plotly documentation.

Custom Configurations

This property allows you to save custom configuration settings for this widget.

This object is merged with the default settings and passed to the Plotly JavaScript library. To see available settings and examples, see Configuration Options in JavaScript in the Plotly documentation.

Settings dialog box with Advanced tab being active. Tab includes two text area on of which is focused.

Legacy Chart Widget Documentation

Charts versions below 3.0.0 use a different set of properties, such as the Data points tab, the REST endpoint data source, and the Mode option. For the configuration options of these versions, see Chart Configuration and Advanced Configuration Settings in the mendixlabs/charts repository.