Charts

This section introduces the grid's integrated charting functionality, which allows users to chart directly inside the grid and supports applications that want to create pre-defined charts.

The charting functionality is deeply integrated with the grid. This integration gives users a seamless charting experience while keeping the coding required by developers to a minimum.

We are not aware of any other datagrid that provides such integration. Other companies may provide a grid library and / or a charting library, but it's up to the developer to tie the two together.

This section introduces the two ways charts can be created from the data contained in the grid:

  • User Created Charts: A user creates a chart using the grid's UI by selecting a range of cells or entering pivot mode and then creating a chart via the context menu.
  • Application Created Charts: The application requests the grid to create a chart through the grid's charting API.

Charts Module

To minimise bundle sizes for applications that do not require charting, charts are contained in a separate module, which can be imported as follows:

// import all Enterprise modules import { ModuleRegistry, AllModules } from '@ag-grid-enterprise/all-modules'; ModuleRegistry.registerModules(AllModules); // or only import minimal modules required for charts import { ModuleRegistry } from "@ag-grid-community/core"; import { ClientSideRowModelModule } from "@ag-grid-community/client-side-row-model"; import { ChartsModule } from "@ag-grid-enterprise/charts"; ModuleRegistry.registerModules([ClientSideRowModelModule, ChartsModule]);

The charts module has been built from the ground up with zero dependencies on any third party libraries.

If you are not using ES6 Modules and are instead using the bundled version of ag-Grid Enterprise, note that ag-grid-enterprise.js already contains the charting module.

Enabling Charts

To enable charting in the grid set the following grid option:

gridOptions = { enableCharts: true }

To allow users to create charts from a Range Selection and / or display the Chart Ranges in the grid, then set the following grid option:

gridOptions = { enableRangeSelection: true }

User Created Charts

User created charts are designed to provide an out-of-the box charting experience, similar to that found in spreadsheet applications such as Excel, but more compellingly it will be integrated inside your applications.

All that is required for users to create charts, from the data already contained in the grid, is to import the charts module and enable charts.

Try it out on our demo page by doing the following:

  • Select a Cell Range of numeric values in the grid by dragging the mouse over a range of cells.
  • Bring up the Context Menu and select the desired chart type from the 'Chart Range' sub menu.

User Created Charts

The animation above highlights a number of charting features. For more details on each feature follow the links provided below:

  • Chart Ranges: When a chart is created, corresponding chart ranges appear in the grid and can be adjusted via the chart range handle.
  • Categories and Series: Columns can be configured as either categories or series for charting. If not configured then the grid will infer whether a column contains category or series data.

  • Chart Toolbar: The chart toolbar is located in the top right area of the chart and allows a user to:

    • Change the chart type
    • Change the colour palette
    • Change which columns are used as categories and series
    • Format different aspects of the chart
    • Unlink the chart from the grid
    • Download the chart

By default, user created charts are displayed inside the grid's own popup windows. The windows can be moved (by mouse dragging a window's title bar) and resized (by mouse dragging a window's borders).

It is also possible to display user created charts in an another location or application dialog. For more details see the section on providing a chart container.

If using the grid's own popup window, you will probably want to use the grid option popupParent so that the popup windows are not constrained to the bounds of the grid. Typically users set popupParent=document.body to achieve this.

Application Created Charts

Charts can be pre-defined or dynamically created from within applications, and as with user created charts, these charts also benefit from the integration provided with the grid.

The dummy financial application below just touches on what is possible with the grid's integrated charting capabilities. The following should be noted:

  • Pre-Defined Chart: A pre-defined chart is shown in a separate chart container below the grid.
  • Dynamic Charts: Buttons positioned above the grid dynamically create different chart types.
  • High Performance: 100 rows are randomly updated 10 times a second (1,000 updates per second). Try updating the example via Plunker with higher update frequencies and more data.

To learn how to create charts in your applications see the following sections for details:

  • Chart Range API: Used to create charts programmatically inside applications.
  • Provide a Chart Container: Used to target chart containers inside the application instead of the popup window provided by the grid.

Chart Customisation

Before each chart is created, the developer can perform fine-grained Chart Customisation to change the chart's appearance and behaviour. For example, you can change the thickness of the lines, or customise the formatting of the axis labels.

The section Chart Customisation outlines all the items that can be customised for each chart type.

Next Up

Continue to the next section to learn about the: Range Chart.