Pivot Table Web widget

Category: Widgets
Subcategory: Display widgets


Pivot table widget for web pages. This widget replaces the Pivot table widget, referenced in this documentation as the old widget.


Demo urlhttps://testpivottablewebwidget-sandbox.mxapps.io/


Pivot table widget for web pages. This widget replaces the Pivot table widget, referenced in this documentation as the old widget.


  • Use a datasource or a REST service call for the data.
  • Perform actions on the data in each cell.
  • React to click events on the cells.
  • Apply styling thresholds to highlight certain values
  • Apply custom styling to the X and Y labels
  • Export the table data as CSV
  • When there is no data, no table will be rendered but a (configurable) text will be shown.

Entity to use

Because non persistent entities are kept in the client state, these are not the preferred way when using a datasource. It is best to use persistent entities and make sure the objects are committed.

However, implementations using the old widget probably use non-persistent entities because that was the preferred way for Mendix before release 7.

Especially when using non-persistent entities it is best to use a web service rather than a datasource because the web service does not return Mendix objects but only JSON data.

Migrating from the old pivot table widget

Migration depends on whether you currently use persistent data directly in the widget.

Persistent entity

When you returned persistent objects to the old widget, just configure that entity on the datasource. Note that the datasource attributes allow retrieve over association.

Non-persistent entity

As mentioned earlier, returning a list of non-persistent data to the client causes a lot of clutter in the client state because the Mendix client keeps track of the non-persistent objects and cannot tell whether the widget is done with them.

The easiest way forward is to create a published REST service and use that in the widget. As a bonus most of the times performance will be much better.

Message definitions

You don't have to rename your existing entities to make them fit! Don't forget that Message definitions in Studio Pro can rename attributes, using the external single item name, so the export mapping will export using the names the widget expects. (See below for the expected names.)

Web service

The widget can call webservices, which can improve performance, especially for larger datasets. As no Mendix objects are transferred, only JSON, the result will not impact the client state. Combining this with OQL to aggegate your data in the backend can be a great combination. You can specify additional parameters to include on the service call.

The Data changed date attribute

Pluggable widgets are rendered really often due to the way React works. Clicking buttons, conditional visibility elsewhere on the page, changing the context object or opening a popup are examples.

To prevent lots of unnecessary server roundtrips, the widget will only call the web service to reload the data when the value of the data changed date attribute changes. So whenever you want the widget to refresh, set the attribute to current date/time in your microflow. When the date did not change, the widget will just render the data loaded in a previous render.

Only to the app backend

The widget will only call services on the app backend. If you wish to use external data, make that service call in your app logic.


Make sure that current session is (also) allowed for the web service because the widget will use the current session to authenticate.

Service parm value

The widget can pass the guid of the context object as query parameter, parameter name will be context. Useful for anonymous services or other situations where you need to know the context of the service call

Query parameters

Enter any other parameters you want to add to the service call.


The service should return a list of data items in the following format:

ElementReq.?DescriptionidValueXYID value for the X axislabelValueXLabel value for the X axis, ID value will be used if emptyclassValueXCSS class to use for the label for the X axis, ignored if emptyidValueYYID value for the Y axislabelValueYLabel value for the Y axis, ID value will be used if emptyclassValueYCSS class to use for the label for the Y axis, ignored if emptyvalue?Value, required when Cell value action is not Count

The values can either be strings or numbers, depending on the type of data returned. As JSON does not know about dates, a date is to be transmitted as UTC date string, format: 2020-09-15T09:53:56.771Z, the widget will process it as a date.

Don't forget you can change the name of the response element in the message definition in Studio Pro using the external single item name.

For ID values, it is best to format the dates in the backend as aggregation usually takes place on an entire month or year. The key is then yyyyMM or just yyyy.

The demo project has an example of the service and mappings.

Cell value actions

No cell value attribute is necessary when objects are to be counted. Decimal, integer and long can be used on any action, DateTime only for Min and Max.

Decimal precision can be set separately for the decimal cell value and for average calculation.


The pivot table widget can display an additional column and row for the totals, only for actions Count and Sum.

CSS classes

The widget renders a div with class pivotTableWidget that contains the actual table. This div will also have any classes set on the widget in Mendix.

By default cell values are centered.

Classes used by the widget

ClassDescriptionpivotTableTopLeftTopleft cellpivotTableColumnHeaderth of column header. If you set the value of classValueX in your data items or set the X-axis CSS class for the datasource the value is added to the classes on the th column headers.pivotTableRowHeaderth of row header. If you set the value of classValueY in your data items or set the Y-axis CSS class for the datasource the value is added to the classes on the th row headers.pivotTableColumnTotaltd of the column totalpivotTableRowTotaltd of the row totalpivotTableCellthe td of a cell with a valuepivotTableCellEmptythe td of a cell with no value

Classes available for use

Put the class on the widget in Mendix.

ClassDescriptionpivotTableWidgetStripedAlternating row colors.cellLeftLeft align cell datacellRightRight align cell data and column headers

Rotated column headers

Getting rotated column headers right is a little tricky because of the math involved. The demo project has a tool to generate CSS for rotated column headers.

Conditional styling

To apply styling to a cell based on its value, use the conditional styling properties. For example, give all low values a red color and the high values a green color, leaving the intermediate ones default. For each style, set a lower limit using a decimal or date value and, optionally, a class. The settings would be:


The effect is that any values lower than 100 will get class background-danger-light, no class is set for any values from 100 up to 500. Any values of 500 and over will get class background-success-light.

These classes are supplied by Atlas UI Resource in the theme folder. You can of course create your own classes and use these.

Note that the widget will order the styling items on ascending value, but for readability it is probably best if you order them on value anyway.

Styling for display action

The display action allows an additional class to be specified, containing the actual value. Most effective for a small number of unique values or enumerations. The class name will start with the fixed value display- followed by the actual value in lower case. Note that any values other than a thru z and 0 thru 9 are replaced by _ in the class name.

Click handling

When the user clicks a cell, the widget will set the X and Y id values on the context object and call the action configured on the widget.


The widget can export the table data as CSV. There are options to force a save file dialog directly from the browser. As some don't look very solid and others don't play well with React, this widget relies on the backend to handle the file creation. You will need to do the following:

  • Create an entity that inherits from FileDocument to create the CSV file.
  • Create a microflow that handles the export:
    • Create an object of the entity that inherits from FileDocument. Unless the document needs to be kept, be sure to set DeleteAfterDownload to true.
    • Use CommunityCommons.StringToFile to store the CSV data in the file document.
    • Clear the export data on the context object to reduce its size.
    • Use the Download File activity to actually download the file.

The demo project has microflow ACT_ExportToCsv that performs these actions.

Demo project


Issues, suggestions and feature requests



Version: 2.2.0
Framework Version: 9.18.0
Release Notes: Mendix 9.18. Validate properties at design time. Hide irrelevant properties.
Version: 2.1.0
Framework Version: 9.6.5
Release Notes: Dark mode icon
Version: 2.0.0
Framework Version: 9.6.0
Release Notes: *** BREAKING CHANGES *** The data changed date is no longer used when retrieving the data using a datasource, only for service calls. The widget detects datasource data changes. Other changes - Depencies updated - New icon/tile image
Version: 1.1.0
Framework Version: 9.1.0
Release Notes: Mendix 9, no changes to widget functionality
Version: 1.0.0
Framework Version: 8.15.0
Release Notes: Initial release. Note that Database and XPath datasources can cause overflows with large number of records. This is not an issue in the widget.