> 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/filters-and-data/grid-charts.md).

# Grid - Charts

Display aggregated grid data as pie, bar and doughnut charts, scoped to all or displayed records.

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:

{% stepper %}
{% step %}

### Open the page

Edit the Lightning page in the App Builder.
{% endstep %}

{% step %}

### Select the grid

Select the Grid.
{% endstep %}

{% step %}

### Find the Charts property

Scroll down until you see the **"Charts"** property.
{% endstep %}

{% step %}

### Paste the configuration

Paste in your charts configuration.
{% endstep %}
{% endstepper %}

<figure><img src="https://4046919449-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MEsSbGy_U_OhthKUpxu%2Fuploads%2FwQHfOy5mT0v0JuABt3kq%2FScreenshot%202026-04-29%20at%2011.09.59.png?alt=media&#x26;token=258f064a-d94d-4194-91be-d02e62ecbeda" alt=""><figcaption></figcaption></figure>

## 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 `"doughnut"`. 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/doughnut) 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 (V-Bar)",
        "chartType": "bar",
        "groupByField": "StageName",
        "aggregateField": "Amount",
        "aggregateOp": "SUM",
        "aggregateType": "currency",
        "datasetLabel": "Sum of Amount"
    },
    {
        "title": "Revenue by Stage (H-Bar)",
        "chartType": "bar",
        "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="<https://youtu.be/zxh8i7c4fQg>" %}

## 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**.

{% tabs %}
{% tab title="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**.
   {% endtab %}

{% tab title="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"
    }
]
```

{% endtab %}
{% endtabs %}

{% 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 %}

## Next steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>User Grid</strong></td><td>Create and configure your own grids from the Config Wiz.</td><td><a href="/product-tour/grids/user-grid.md">User Grid</a></td></tr><tr><td><strong>Grid - Grid Explorer</strong></td><td>Filter, pick columns, sort and group grid data, and save templates.</td><td><a href="/advanced-guides/grid-setup/grid-grid-explorer.md">Grid - Grid Explorer</a></td></tr><tr><td><strong>Field Set Grid</strong></td><td>Build a grid from a field set, including parent fields.</td><td><a href="/product-tour/grids/field-set-grid.md">Field Set Grid</a></td></tr></tbody></table>

## 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="<https://youtu.be/Vei7-MoKsEo>" %}
Grid - Charts Scope
{% endembed %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.gridmate.io/advanced-guides/filters-and-data/grid-charts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.