Cross-filtering charts allow users to interact with data in an easy and intuitive way. Clicking on chart elements
automatically filters values in both the grid and other cross-filter charts.
This built-in feature of integrated charts is particularly useful for creating interactive reports and dashboards.
Creating cross-filter charts
Cross-Filter charts are created programmatically using createCrossFilterChart(params) on the grid's API.
| Function | Used to programmatically create cross filter charts from a range. createCrossFilterChart = (
params: CreateCrossFilterChartParams
) => ChartRef | undefined;
interface CreateCrossFilterChartParams {
// The type of cross-filter chart to create.
chartType: CrossFilterChartType;
// The range of cells to be charted. If no rows / rowIndexes are specified all rows will be included.
cellRange: ChartParamsCellRange;
// Suppress highlighting the selected range in the grid.
suppressChartRanges?: boolean;
// The aggregation function that should be applied to all series data.
aggFunc?: string | IAggFunc;
// The default theme to use, either a default option or your own custom theme.
chartThemeName?: string;
// Provide to display the chart outside of the grid in your own container.
chartContainer?: HTMLElement;
// Allows specific chart options in the current theme to be overridden.
chartThemeOverrides?: AgChartThemeOverrides;
// When enabled the chart will be unlinked from the grid after creation, any updates to the data will not be reflected in the chart.
unlinkChart?: boolean;
}
type CrossFilterChartType =
'column'
| 'bar'
| 'line'
| 'scatter'
| 'bubble'
| 'pie'
| 'doughnut'
| 'area'
type ChartParamsCellRange =
Partial<Omit<CellRangeParams, 'rowStartPinned'
| 'rowEndPinned'>>
interface ChartRef {
// The id of the created chart.
chartId: string;
// The chart instance that is produced by AG Charts which can be used to interact with the chart directly.
chart: any;
// The chart DOM element, which the application is responsible for placing into the DOM.
chartElement: HTMLElement;
// The application is responsible for calling this when the chart is no longer needed.
destroyChart: () => void;
}
|
The following snippet shows how a cross-filtering pie chart can be created:
this.gridApi.createCrossFilterChart({
chartType: 'pie',
cellRange: {
columns: ['salesRep', 'sale'],
},
aggFunc: 'sum',
});
Note in the snippet above that the sale values are aggregated by the salesRep category as aggFunc: 'sum' is specified.
A corresponding column configuration for the chart above is shown in the following snippet:
<ag-grid-vue
:columnDefs="columnDefs"
>
</ag-grid-vue>
this.columnDefs = [
{ field: 'salesRep', filter: 'agSetColumnFilter', chartDataType: 'category' },
{ field: 'sale', chartDataType: 'series' },
];
Cross-filtering requires that grid filtering is enabled with either a Set Filter or Multi Filter configured on the category column used in the chart. It is also important to define the Chart Data Type as it's not possible to infer the type when all data is filtered out..
The following example shows how to create a simple cross-filtering pie chart. Note the following:
- Click on a sector of the pie chart to filter rows in the grid by the selected sales rep.
- Ctrl (Cmd) Click on another sector to additionally adds rows corresponding to the selected sales rep.
- Click Chart Background to remove / reset the filtering in the grid to restore all rows in the grid.
Cross-filter API
The cross-filter api shares a similar api to Range Chart, however there are
different defaults which make sense for cross-filtering.
| Function | Used to programmatically create cross filter charts from a range. createCrossFilterChart = (
params: CreateCrossFilterChartParams
) => ChartRef | undefined;
interface CreateCrossFilterChartParams {
// The type of cross-filter chart to create.
chartType: CrossFilterChartType;
// The range of cells to be charted. If no rows / rowIndexes are specified all rows will be included.
cellRange: ChartParamsCellRange;
// Suppress highlighting the selected range in the grid.
suppressChartRanges?: boolean;
// The aggregation function that should be applied to all series data.
aggFunc?: string | IAggFunc;
// The default theme to use, either a default option or your own custom theme.
chartThemeName?: string;
// Provide to display the chart outside of the grid in your own container.
chartContainer?: HTMLElement;
// Allows specific chart options in the current theme to be overridden.
chartThemeOverrides?: AgChartThemeOverrides;
// When enabled the chart will be unlinked from the grid after creation, any updates to the data will not be reflected in the chart.
unlinkChart?: boolean;
}
type CrossFilterChartType =
'column'
| 'bar'
| 'line'
| 'scatter'
| 'bubble'
| 'pie'
| 'doughnut'
| 'area'
type ChartParamsCellRange =
Partial<Omit<CellRangeParams, 'rowStartPinned'
| 'rowEndPinned'>>
interface ChartRef {
// The id of the created chart.
chartId: string;
// The chart instance that is produced by AG Charts which can be used to interact with the chart directly.
chart: any;
// The chart DOM element, which the application is responsible for placing into the DOM.
chartElement: HTMLElement;
// The application is responsible for calling this when the chart is no longer needed.
destroyChart: () => void;
}
|
Properties available on the CreateCrossFilterChartParams interface.
| CrossFilterChartType | The type of cross-filtering chart to create. chartType: CrossFilterChartType;
type CrossFilterChartType =
'column'
| 'bar'
| 'line'
| 'scatter'
| 'bubble'
| 'pie'
| 'doughnut'
| 'area'
|
| ChartParamsCellRange | Defines the list of columns to be charted. Note that cross-filter charts include all rows in the grid so there is no need to specify the range of rows. cellRange: ChartParamsCellRange;
type ChartParamsCellRange =
Partial<Omit<CellRangeParams, 'rowStartPinned'
| 'rowEndPinned'>>
interface CellRangeParams {
// Start row index
rowStartIndex: number | null;
// Pinned state of start row. Either 'top', 'bottom' or null
rowStartPinned?: RowPinnedType;
// End row index
rowEndIndex: number | null;
// Pinned state of end row. Either 'top', 'bottom' or null
rowEndPinned?: RowPinnedType;
// Starting column for range
columnStart?: string | Column;
// End column for range
columnEnd?: string | Column;
// Specify Columns to include instead of using `columnStart` and `columnEnd`
columns?: (string | Column)[];
}
type RowPinnedType =
'top'
| 'bottom'
| null
| undefined
|
| boolean | By default, when a cross-filter chart is displayed using the grid, the grid will not highlight the range the chart is charting when the chart gets focus. To show the chart range set suppressChartRanges=false. Default: true |
| | The aggregation function that should be applied to all series data. The built-in aggregation functions are 'sum', 'min', 'max', 'count', 'avg', 'first', 'last'. Alternatively, custom aggregation functions can be provided if they conform to the IAggFunc interface shown here. aggFunc: string | IAggFunc;
interface IAggFunc<TData = any, TValue = any> {
(params: IAggFuncParams<TData, TValue>) : any
}
interface IAggFuncParams<TData = any, TValue = any> {
// Values to aggregate
values: TValue[];
// Column the aggregation function is working on
column: Column;
// ColDef of the aggregation column
colDef: ColDef<TData>;
// Pivot Result Column being produced using this aggregation
pivotResultColumn?: Column;
// The parent RowNode, where the aggregation result will be shown
rowNode: IRowNode<TData>;
// data (if any) of the parent RowNode
data: TData;
// The grid api.
api: GridApi<TData>;
// The column api.
columnApi: ColumnApi;
// Application context as set on `gridOptions.context`.
context: any;
}
|
| string | The default theme to use for the created chart. In addition to the default options you listed, you can also provide your own custom chart themes. Options: 'ag-default', 'ag-default-dark', 'ag-material', 'ag-material-dark', 'ag-pastel', 'ag-pastel-dark', 'ag-vivid', 'ag-vivid-dark', 'ag-solar', 'ag-solar-dark' |
| | If the chart is to be displayed outside of the grid then a chart container should be provided. If the chart is to be displayed using the grid's popup window mechanism then leave as undefined. |
| | chartThemeOverrides: AgChartThemeOverrides;
interface AgChartThemeOverrides {
}
|
| boolean | When enabled the chart will be unlinked from the grid after creation, any updates to the data will not be reflected in the chart. See Unlinking Charts. Default: false |
Cross-filter Chart Types
The following examples show the different chart types that support cross-filtering:
Example: Sales Dashboard #1
Example: Sales Dashboard #2
Example: Most Populous Cities
Next Up
