---
title: "Range Chart API"
enterprise: true
framework: angular
version: "36.1.0"
---

# Range Chart API

This section shows how Range Charts can be created via the Grid API.

## Creating Range Charts

Range Charts can be created through `gridApi.createRangeChart()` as shown below:

```ts
this.gridApi.createRangeChart({
    chartType: 'groupedColumn',
    cellRange: {
        rowStartIndex: 0,
        rowEndIndex: 4,
        columns: ['country', 'gold', 'silver'],
    },
    // other options...
});
```

The snippet above creates a Range Chart with the `groupedColumn` chart type using data from the first 4 and the `country`, `gold`, `silver` columns. For a full list of options see [Range Chart API](https://www.ag-grid.com/angular-data-grid/integrated-charts-api-range-chart/#range-chart-api).

The following example demonstrates how Range Charts can be created programmatically via `gridApi.createRangeChart()`. Note the following:

- Clicking **'Top 5 Medal Winners'** will chart the first five rows of Gold and Silver medals by Country.
- Clicking **'Bronze Medals by Country'** will chart Bronze by Country using all rows (the provided cell range does not specify rows).
- Note the **'Bronze Medals by Country'** chart is unlinked from the grid as `unlinkChart=true`. Notice that sorting in the grid does not affect the chart and there is no chart range in the grid.

#### Charts in Grid Popup Window

```ts
import { Component, ViewChild } from "@angular/core";
import { AgGridAngular } from "ag-grid-angular";
import "./style.css";
import { AgChartsEnterpriseModule } from "ag-charts-enterprise";
import {
  CellSelectionOptions,
  ClientSideRowModelModule,
  ColDef,
  ColGroupDef,
  GridApi,
  GridOptions,
  GridReadyEvent,
  ModuleRegistry,
  NumberEditorModule,
  NumberFilterModule,
  TextEditorModule,
  TextFilterModule,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnMenuModule,
  ContextMenuModule,
  IntegratedChartsModule,
  RowGroupingModule,
} from "ag-grid-enterprise";
import { getData } from "./data";
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

ModuleRegistry.registerModules([
  NumberEditorModule,
  TextEditorModule,
  TextFilterModule,
  NumberFilterModule,
  ClientSideRowModelModule,
  IntegratedChartsModule.with(AgChartsEnterpriseModule),
  ColumnMenuModule,
  ContextMenuModule,
  RowGroupingModule,
]);

@Component({
  selector: "my-app",
  standalone: true,
  imports: [AgGridAngular],
  template: `<div class="outer-div">
    <div class="button-bar">
      <button (click)="onChart1()">Top 5 Medal Winners</button>
      <button (click)="onChart2()">Bronze Medals by Country</button>
    </div>
    <div class="grid-wrapper">
      <ag-grid-angular
        style="width: 100%; height: 100%;"
        [columnDefs]="columnDefs"
        [defaultColDef]="defaultColDef"
        [cellSelection]="true"
        [enableCharts]="true"
        [popupParent]="popupParent"
        [rowData]="rowData"
        (gridReady)="onGridReady($event)"
      />
    </div>
  </div> `,
})
export class AppComponent {
  private gridApi!: GridApi;

  columnDefs: ColDef[] = [
    { field: "country", width: 150, chartDataType: "category" },
    { field: "gold", chartDataType: "series", sort: "desc" },
    { field: "silver", chartDataType: "series", sort: "desc" },
    { field: "bronze", chartDataType: "series" },
  ];
  defaultColDef: ColDef = {
    editable: true,
    flex: 1,
    minWidth: 100,
    filter: true,
  };
  popupParent: HTMLElement | null = document.body;
  rowData!: any[];

  onChart1() {
    this.gridApi.createRangeChart({
      cellRange: {
        rowStartIndex: 0,
        rowEndIndex: 4,
        columns: ["country", "gold", "silver"],
      },
      chartType: "groupedColumn",
      chartThemeOverrides: {
        common: {
          title: {
            enabled: true,
            text: "Top 5 Medal Winners",
          },
        },
      },
    });
  }

  onChart2() {
    this.gridApi.createRangeChart({
      cellRange: {
        columns: ["country", "bronze"],
      },
      chartType: "groupedBar",
      chartThemeOverrides: {
        common: {
          title: {
            enabled: true,
            text: "Bronze Medal by Country",
          },
        },
      },
      unlinkChart: true,
    });
  }

  onGridReady(params: GridReadyEvent) {
    this.gridApi = params.api;

    getData().then((rowData) => params.api.setGridOption("rowData", rowData));
  }
}
```

[Live example: Charts in Grid Popup Window](https://www.ag-grid.com/examples/integrated-charts-api-range-chart/chart-api/angular)

## Range Chart Dashboard

The following example passes a [Chart Container](https://www.ag-grid.com/angular-data-grid/integrated-charts-container/) to the API to place the chart in a location other than the grid's popup window. Note the following:

- The charts are placed in `div` elements outside the grid.
- The two pie charts are showing aggregations rather than charting individual rows.
- The bar chart is sensitive to changes in the rows. For example if you sort, the chart updates to always chart the first five rows.
- All data is editable in the grid. Changes to the grid data is reflected in the charts.
- The pie charts have legends on the right side. This is configured in the `chartThemeOverrides`.
- The chart menu has been [hidden](https://www.ag-grid.com/angular-data-grid/integrated-charts-menu/#hiding-the-chart-menu) in the example below.

#### Charts in Dashboard

```ts
import { Component, ViewChild } from "@angular/core";
import { AgGridAngular } from "ag-grid-angular";
import { AgChartsEnterpriseModule } from "ag-charts-enterprise";
import {
  CellSelectionOptions,
  ChartToolPanelsDef,
  ClientSideRowModelModule,
  ColDef,
  ColGroupDef,
  FirstDataRenderedEvent,
  GetChartToolbarItems,
  GridApi,
  GridOptions,
  GridReadyEvent,
  ModuleRegistry,
  NumberEditorModule,
  NumberFilterModule,
  TextEditorModule,
  TextFilterModule,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnMenuModule,
  ContextMenuModule,
  IntegratedChartsModule,
  RowGroupingModule,
} from "ag-grid-enterprise";
import { getData } from "./data";
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

ModuleRegistry.registerModules([
  NumberEditorModule,
  TextEditorModule,
  TextFilterModule,
  NumberFilterModule,
  ClientSideRowModelModule,
  IntegratedChartsModule.with(AgChartsEnterpriseModule),
  ColumnMenuModule,
  ContextMenuModule,
  RowGroupingModule,
]);

@Component({
  selector: "my-app",
  standalone: true,
  imports: [AgGridAngular],
  template: `<div
    style="display: flex; flex-direction: column; height: 100%; width: 100%; overflow: hidden"
  >
    <ag-grid-angular
      style="width: 100%; height: 30%;"
      [columnDefs]="columnDefs"
      [defaultColDef]="defaultColDef"
      [cellSelection]="true"
      [enableCharts]="true"
      [chartToolPanelsDef]="chartToolPanelsDef"
      [popupParent]="popupParent"
      [getChartToolbarItems]="getChartToolbarItems"
      [rowData]="rowData"
      (firstDataRendered)="onFirstDataRendered($event)"
      (gridReady)="onGridReady($event)"
    />
    <div id="chart1" class="my-chart" style="flex: 1 1 auto; height: 30%"></div>
    <div style="display: flex; flex: 1 1 auto; height: 30%; gap: 8px">
      <div
        id="chart2"
        class="my-chart"
        style="flex: 1 1 auto; width: 50%"
      ></div>
      <div
        id="chart3"
        class="my-chart"
        style="flex: 1 1 auto; width: 50%"
      ></div>
    </div>
  </div> `,
})
export class AppComponent {
  columnDefs: ColDef[] = [
    { field: "country", width: 150, chartDataType: "category" },
    { field: "group", chartDataType: "category" },
    { field: "gold", chartDataType: "series" },
    { field: "silver", chartDataType: "series" },
    { field: "bronze", chartDataType: "series" },
  ];
  defaultColDef: ColDef = {
    editable: true,
    flex: 1,
    minWidth: 100,
    filter: true,
  };
  chartToolPanelsDef: ChartToolPanelsDef = { panels: [] };
  popupParent: HTMLElement | null = document.body;
  getChartToolbarItems: GetChartToolbarItems = () => [];
  rowData!: any[];

  onFirstDataRendered(event: FirstDataRenderedEvent) {
    createGroupedBarChart(event, "#chart1", ["country", "gold", "silver"]);
    createPieChart(event, "#chart2", ["group", "gold"]);
    createPieChart(event, "#chart3", ["group", "silver"]);
  }

  onGridReady(params: GridReadyEvent) {
    getData().then((rowData) => params.api.setGridOption("rowData", rowData));
  }
}

function createGroupedBarChart(
  params: FirstDataRenderedEvent,
  selector: string,
  columns: string[],
) {
  params.api.createRangeChart({
    chartContainer: document.querySelector(selector) as HTMLElement,
    cellRange: {
      rowStartIndex: 0,
      rowEndIndex: 4,
      columns,
    },
    suppressChartRanges: true,
    chartType: "groupedBar",
  });
}
function createPieChart(
  params: FirstDataRenderedEvent,
  selector: string,
  columns: string[],
) {
  params.api.createRangeChart({
    chartContainer: document.querySelector(selector) as HTMLElement,
    cellRange: { columns },
    suppressChartRanges: true,
    chartType: "pie",
    aggFunc: "sum",
    chartThemeOverrides: {
      common: {
        padding: {
          top: 20,
          left: 10,
          bottom: 30,
          right: 10,
        },
        legend: {
          position: "right",
        },
      },
    },
  });
}
```

[Live example: Charts in Dashboard](https://www.ag-grid.com/examples/integrated-charts-api-range-chart/dashboard/angular)

## Hiding Chart Ranges

In some cases it may be desirable to hide the chart ranges in the grid, see [Combination Charts](https://www.ag-grid.com/angular-data-grid/integrated-charts-api-range-chart/#combination-charts).

To hide the chart ranges simply enable `suppressChartRanges=true` on the `ChartRangeParams`.

For more details refer to [Range Chart API](https://www.ag-grid.com/angular-data-grid/integrated-charts-api-range-chart/#range-chart-api).

## Combination Charts

It is possible to create the following combination chart types via `gridApi.createRangeChart()`:

- Column & Line (`chartType: 'columnLineCombo'`)
- Area & Column (`chartType: 'areaColumnCombo'`)
- Custom Combination (`chartType: 'customCombo'`)

When the `customCombo` chart type is specified a new `CreateRangeChartParams.seriesChartTypes` must also be supplied. Also note that when `seriesChartTypes` is present a `customCombo` chart type is assumed, regardless of which `chartType` is supplied.

The `seriesChartTypes` property accepts an array of `SeriesChartType` objects as shown below:

```ts
this.gridApi.createRangeChart({
    chartType: 'customCombo',
    cellRange: {
      columns: ['month', 'rain', 'pressure', 'temp'],
    },
    seriesChartTypes: [
      { colId: 'rain', chartType: 'groupedColumn', secondaryAxis: false },
      { colId: 'pressure', chartType: 'line', secondaryAxis: true },
      { colId: 'temp', chartType: 'line', secondaryAxis: true }
    ],
    aggFunc: 'sum',
});
```

The following series chart types are supported with combination charts:

- Line (`chartType: 'line'`)
- Area (`chartType: 'Area'`)
- Stacked Area (`chartType: 'stackedArea'`)
- Grouped Column (`chartType: 'groupedColumn'`)
- Stacked Column (`chartType: 'stackedColumn'`)

Note that only `line` and `area` series chart types can be plotted against a secondary axis.

The following example demonstrates the above configuration, note the following:

- The 'Rain' series uses a `groupedColumn` chart type and is plotted against the primary Y axis (`secondaryAxis=false`)
- 'Pressure' and 'Temp' use a `line` chart type and are plotted against separate secondary Y axes (`secondaryAxis=true`)
- Values are aggregated by the 'Month' category by setting `aggFunc: 'sum'`
- Chart Ranges are hidden using `suppressChartRanges=true`

#### Combination Chart

```ts
import { Component, ViewChild } from "@angular/core";
import { AgGridAngular } from "ag-grid-angular";
import "./style.css";
import { AgChartsEnterpriseModule } from "ag-charts-enterprise";
import { AgAxisCaptionFormatterParams } from "ag-charts-types";
import {
  AgChartThemeOverrides,
  CellSelectionOptions,
  ClientSideRowModelModule,
  ColDef,
  ColGroupDef,
  FirstDataRenderedEvent,
  GridApi,
  GridOptions,
  GridReadyEvent,
  ModuleRegistry,
  NumberEditorModule,
  NumberFilterModule,
  TextEditorModule,
  TextFilterModule,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnMenuModule,
  ContextMenuModule,
  IntegratedChartsModule,
  RowGroupingModule,
} from "ag-grid-enterprise";
import { getData } from "./data";
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

ModuleRegistry.registerModules([
  TextEditorModule,
  TextFilterModule,
  NumberEditorModule,
  NumberFilterModule,
  ClientSideRowModelModule,
  IntegratedChartsModule.with(AgChartsEnterpriseModule),
  ColumnMenuModule,
  ContextMenuModule,
  RowGroupingModule,
]);

@Component({
  selector: "my-app",
  standalone: true,
  imports: [AgGridAngular],
  template: `<div class="wrapper">
    <ag-grid-angular
      style="width: 100%; height: 100%;"
      [columnDefs]="columnDefs"
      [defaultColDef]="defaultColDef"
      [cellSelection]="true"
      [enableCharts]="true"
      [popupParent]="popupParent"
      [chartThemeOverrides]="chartThemeOverrides"
      [rowData]="rowData"
      (firstDataRendered)="onFirstDataRendered($event)"
      (gridReady)="onGridReady($event)"
    />
    <div id="myChart"></div>
  </div> `,
})
export class AppComponent {
  columnDefs: ColDef[] = [
    { field: "day", maxWidth: 120 },
    {
      field: "month",
      chartDataType: "category",
      filterParams: {
        comparator: (a: string, b: string) => {
          const months: {
            [key: string]: number;
          } = {
            jan: 1,
            feb: 2,
            mar: 3,
            apr: 4,
            may: 5,
            jun: 6,
            jul: 7,
            aug: 8,
            sep: 9,
            oct: 10,
            nov: 11,
            dec: 12,
          };
          const valA = months[a.toLowerCase()];
          const valB = months[b.toLowerCase()];
          if (valA === valB) return 0;
          return valA > valB ? 1 : -1;
        },
      },
    },
    { field: "rain", chartDataType: "series" },
    { field: "pressure", chartDataType: "series" },
    { field: "temp", chartDataType: "series" },
    { field: "wind", chartDataType: "series" },
  ];
  defaultColDef: ColDef = {
    flex: 1,
    minWidth: 100,
    editable: true,
    filter: true,
    floatingFilter: true,
  };
  popupParent: HTMLElement | null = document.body;
  chartThemeOverrides: AgChartThemeOverrides = {
    common: {
      axes: {
        number: {
          title: {
            enabled: true,
            formatter: (params: AgAxisCaptionFormatterParams) => {
              return params.boundSeries.map((s) => s.name).join(" / ");
            },
          },
        },
      },
    },
    bar: {
      series: {
        strokeWidth: 2,
        fillOpacity: 0.8,
      },
    },
    line: {
      series: {
        strokeWidth: 5,
        strokeOpacity: 0.8,
        marker: {
          enabled: false,
        },
      },
    },
  };
  rowData!: any[];

  onFirstDataRendered(params: FirstDataRenderedEvent) {
    params.api.createRangeChart({
      chartType: "customCombo",
      cellRange: {
        columns: ["month", "rain", "pressure", "temp"],
      },
      seriesChartTypes: [
        { colId: "rain", chartType: "groupedColumn", secondaryAxis: false },
        { colId: "pressure", chartType: "line", secondaryAxis: true },
        { colId: "temp", chartType: "line", secondaryAxis: true },
      ],
      aggFunc: "sum",
      suppressChartRanges: true,
      chartContainer: document.querySelector("#myChart") as any,
    });
  }

  onGridReady(params: GridReadyEvent) {
    getData().then((rowData) => params.api.setGridOption("rowData", rowData));
  }
}
```

[Live example: Combination Chart](https://www.ag-grid.com/examples/integrated-charts-api-range-chart/combination-chart/angular)

## Range Chart API

Range Charts can be created programmatically using:

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `createRangeChart` | `Function` |  |  | Used to programmatically create charts from a range. Module: [`IntegratedChartsModule`](https://www.ag-grid.com/angular-data-grid/modules/). |

Properties available on the `CreateRangeChartParams` interface.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `cellRange` | `ChartParamsCellRange` | Yes |  | Defines the range of cells to be charted. A range is normally defined with start and end rows and a list of columns. If the start and end rows are omitted, the range covers all rows (i.e. entire column contents are selected). The columns can either be defined using a start and end column (the range will cover the start and end columns and all columns in between), or columns can be supplied specifically in cases where the required columns are not adjacent to each other. See [Add Cell Range](https://www.ag-grid.com/angular-data-grid/cell-selection-api-reference/#reference-selection-addCellRange) for more information. |
| `chartType` | `ChartType` | Yes |  | The type of chart to create. |
| `suppressChartRanges` | `boolean` |  | `false` | By default, when a chart is displayed using the grid, the grid will highlight the range the chart is charting when the chart gets focus. To suppress this behaviour, set `suppressChartRanges=true`. |
| `switchCategorySeries` | `boolean` |  |  | Switch Category / Series. |
| `aggFunc` | [`string \| IAggFunc`](https://www.ag-grid.com/angular-data-grid/aggregation-custom-functions/) |  |  | 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. |
| `seriesChartTypes` | `SeriesChartType[]` |  |  | The series chart type configurations used in combination charts. |
| `seriesGroupType` | `SeriesGroupType` |  |  | Group type for chart types that support grouped series. |
| `useGroupColumnAsCategory` | `boolean` |  |  | Prefer using the auto group column as the category when grouping is active. |
| `chartThemeName` | `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](https://www.ag-grid.com/angular-data-grid/integrated-charts-customisation/#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'`. |
| `chartContainer` | [`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement) |  |  | 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`](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides) |  |  | Allows specific chart options in the current theme to be overridden. See [Overriding Existing Themes](https://www.ag-grid.com/angular-data-grid/integrated-charts-customisation/#overriding-themes) for more information. |
| `unlinkChart` | `boolean` |  | `false` | 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](https://www.ag-grid.com/angular-data-grid/integrated-charts-menu/#default-chart-menu-items) for more information. |

The API returns a `ChartRef` object when a `chartContainer` is provided. This is the same structure that is provided to the `createChartContainer(chartRef)` callback. The `ChartRef` provides the application with the `destroyChart()` method that is required when the application wants to dispose the chart.