> For the complete documentation index, see [llms.txt](https://docs.gridmate.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gridmate.io/advanced-guides/grid-charts.md).
# Grid - Charts
GridMate **Charts** feature allows you to display aggregated data from your grid in a graphical format. It helps users understand their filtered data at a glance. The Chart feature is available for **GridMate Smart Grids**.
## Enable Charts
To enable the **Charts** option:
1. Edit the Lightning page in the App Builder.
2. Select the Grid.
3. Scroll down until you see the **"Charts"** property.
4. Paste in your charts configuration.
## Charts Configuration
The **Charts** property accepts a JSON array, where each object in the array defines a single chart. You can configure as many charts as you'd like.
Each chart object is built from a few required fields that describe *what* to display, plus optional fields for labeling and fine-tuning the visual output.
### **Required fields**
* `title` — The heading displayed above the chart. This is what users see, so make it descriptive (e.g., `"Revenue by Stage"` rather than `"Chart 1"`).
* `chartType` — The visualization style. Supported values are `"pie"`, `"bar"`, and `"donut"`. The chart type determines the default orientation and shape; see the `options` field below for variations like horizontal bars.
* `groupByField` — The Salesforce field API name used to group records into chart segments or categories. Each unique value in this field becomes a slice (pie/donut) or a bar. For example, using `"StageName"` on Opportunities produces one segment per stage.
* `aggregateField` — The Salesforce field API name whose values are aggregated within each group. This is the numeric or currency field that determines the size of each segment.
* `aggregateOp` — The aggregation operation applied to `aggregateField`. Common values include `"SUM"`, `"COUNT"`, `"AVG"`, `"MIN"`, and `"MAX"`.
* `aggregateType` — The data type of the aggregated value, used for formatting labels and tooltips. Use `"currency"` for monetary values, `"number"` for plain numerics, and `"percent"` for percentages.
### **Optional fields**
* `datasetLabel` — A label shown in the chart's legend or tooltip describing the dataset (e.g., `"Sum of Amount"`). Useful when the title alone doesn't make the metric explicit.
* `options` — A nested object passed through to the underlying chart renderer for advanced customization. The most common use is flipping a bar chart's orientation:
```json
"options": {
"indexAxis": "y"
}
```
{% hint style="info" %}
Setting `indexAxis` to `"y"` produces a horizontal bar chart; the default `"x"` produces a vertical one.
{% endhint %}
Below is a configuration example👇.
```json
[
{
"title": "Revenue by Stage (pie)",
"chartType": "pie",
"groupByField": "StageName",
"aggregateField": "Amount",
"aggregateOp": "SUM",
"aggregateType": "currency"
},
{
"title": "Revenue by Stage (H-Bar)",
"chartType": "bar",
"groupByField": "StageName",
"aggregateField": "Amount",
"aggregateOp": "SUM",
"aggregateType": "currency",
"datasetLabel": "Sum of Amount"
},
{
"title": "Revenue by Stage (V-Bar)",
"chartType": "donut",
"groupByField": "StageName",
"aggregateField": "Amount",
"aggregateOp": "SUM",
"aggregateType": "currency",
"datasetLabel": "Sum of Amount",
"options": {
"indexAxis": "y"
}
}
]
```
## Charts Setup
Below is a step by step tutorial to configure the **Grid - Charts** 👇.
{% embed url="" %}
## Charts Scope
Each chart has a **Scope** that decides which records it aggregates. Scope is available on **Field Set**, **List View**, **Related List** and **User Grids**.
| Scope | JSON value | The chart aggregates |
| ------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **All records** (default) | `all` | The grid's full filtered query, on the server, beyond pagination and the row limit. A page of 50 rows still charts every matching record. |
| **Displayed records** | `displayed` | Only the rows currently loaded in the grid, with their filters, pagination or scroll position, and interactive filters. Group and summary rows are left out. An empty grid gives an empty chart. |
Existing charts have no scope and behave as **All records**.
### Set the scope on a User Grid
1. Open the User Grid record and click **Config. Wiz**.
2. Click the **Charts** tab.
3. Fill in the chart, then pick a **Scope**: **All records** or **Displayed records**.
4. Click **Add Chart**. The scope appears as a column in the saved charts list.
5. Click **Save**.
### Set the scope in the Charts property
On Field Set, List View and Related List grids, add `scope` to each chart in the **Charts** property:
```json
[
{
"title": "Stage · All records",
"chartType": "doughnut",
"groupByField": "StageName",
"aggregateField": "Amount",
"aggregateOp": "SUM",
"aggregateType": "currency",
"scope": "all"
},
{
"title": "Stage · This page",
"chartType": "doughnut",
"groupByField": "StageName",
"aggregateField": "Amount",
"aggregateOp": "SUM",
"aggregateType": "currency",
"scope": "displayed"
}
]
```
{% hint style="info" %}
A chart loads its data when the **Charts** tab opens. After you change the page, a filter or the search, close and reopen the **Grid Explorer** to refresh it.
{% endhint %}
## Charts Scope Demo
After configuring a chart with each **Scope** on your grid, you're ready to compare them. The video below provides a step-by-step tutorial on how to use the **Grid - Charts Scope** 👇
{% embed url="" %}
Grid - Charts Scope
{% endembed %}
