> 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/package-reference/components-library/grids/gm-apex-data-grid.md).

# GM - Apex Data Grid

(gmpkg:ApexDataGridComponent)

## **Documentation**

**GM - Apex Data Grid** component is used to display the rows returned by your own Apex class instead of records from a query: data from an external system or a callout, computed rows, or aggregates. GridMate renders them with the grid experience: search, sort, totals, grouping, cell coloring, frozen columns, fullscreen, actions and export.

**Use case:** Display an **Account Health** grid computed by an Apex class from the opportunities and cases of each account, see [GM - Apex Data Grid](https://docs.gridmate.io/product-tour/grids/apex-data-grid.md).

{% hint style="info" %}
The grid is read-only: there is no inline editing, record creation, deletion or mass update. Because the rows don't come from a query, your Apex class handles search, filter, sort and the row count itself. See [Building a Provider](#building-a-provider).
{% endhint %}

## **Specification**

<table data-full-width="true"><thead><tr><th width="220.203125">Property</th><th width="104.33333333333331">Type</th><th width="501.37931315104174">Description</th></tr></thead><tbody><tr><td>recordId</td><td>String</td><td>recordId to use. Keep this empty if you want to use the current record.</td></tr><tr><td>Provider Class*</td><td>String</td><td>The name of the Apex class that implements <code>gmpkg.IApexDataGridProvider</code>.</td></tr><tr><td>DataGrid Code</td><td>String</td><td>The code to identify the data grid.</td></tr><tr><td>Custom Label</td><td>String</td><td>Override the label of the data grid. Set it: the grid has no object label to fall back on.</td></tr><tr><td>Custom Icon</td><td>String</td><td>Customize the data grid icon. All Lightning icons are supported, for example <code>standard:account</code>.</td></tr><tr><td>Row Limit</td><td>Integer</td><td>The maximum number of rows to fetch. The default value is 5000.</td></tr><tr><td>Page Size</td><td>Integer</td><td>The number of rows to fetch per step. The default value is 10.</td></tr><tr><td>Enable Pagination</td><td>Boolean</td><td>Check this option to enable pagination instead of scrolling. The grid calls <code>getItemsCount</code> for the total.</td></tr><tr><td>Grid Height</td><td>Integer</td><td>Set the grid height.</td></tr><tr><td>Filter</td><td>String</td><td>JSON filter criteria, sent to your Apex class as <code>filterBy</code>. <code>$recordId</code> is replaced with the current record Id. Ex. <code>{"Health":"At Risk"}</code></td></tr><tr><td>Search Fields</td><td>String</td><td><code>,</code> separated search fields. The search terms reach your Apex class inside <code>filterBy</code>.</td></tr><tr><td>Wildcard Search</td><td>Boolean</td><td>Check this option to use wildcard search. The default value is checked.</td></tr><tr><td>Sort</td><td>String</td><td>The column to sort the data grid on the initial load. Ex. <code>OpenPipeline</code></td></tr><tr><td>Order</td><td>String</td><td>Asc or Desc order for sorting.</td></tr><tr><td>Aggregate</td><td>String</td><td>JSON string to define the aggregate columns. The component supports <code>sum</code>, <code>min</code> and <code>max</code>. Ex. <code>{"OpenPipeline":"sum"}</code></td></tr><tr><td>Group By</td><td>String</td><td><code>,</code> separated list of columns to group by.</td></tr><tr><td>Collapse Groups</td><td>Boolean</td><td>Check this option to collapse groups by default.</td></tr><tr><td>Multi Level Grouping</td><td>Boolean</td><td>Check this option to enable multi level grouping.</td></tr><tr><td>Show Aggregate Header</td><td>Boolean</td><td>Check this option to show the aggregate header as a card on top of the grid. The default value is checked.</td></tr><tr><td>Enable Freeze Columns</td><td>Boolean</td><td>Check this option if you want to freeze columns. The default value is checked.</td></tr><tr><td>Frozen Columns</td><td>Integer</td><td># of columns to freeze.</td></tr><tr><td>Enable Toggle Fullscreen</td><td>Boolean</td><td>Check this option if you want to enable toggle fullscreen.</td></tr><tr><td>Enable Interactive Filters</td><td>Boolean</td><td>Check this option if you want to enable interactive filters.</td></tr><tr><td>Hidden Columns</td><td>String</td><td><code>,</code> separated list of hidden columns.</td></tr><tr><td>Column Style</td><td>String</td><td>JSON string to define column styles. Ex. <code>{"Name":"width:240px"}</code></td></tr><tr><td>Custom Field Labels</td><td>String</td><td><code>{name:label}</code> custom field labels map.</td></tr><tr><td>Cell Coloring</td><td>String</td><td>JSON conditions for cell coloring.</td></tr><tr><td>Show Border</td><td>Boolean</td><td>Check this option to show a border around the grid. The default value is checked.</td></tr><tr><td>Show Column Border</td><td>Boolean</td><td>Check this option to show column borders. The default value is checked.</td></tr><tr><td>Hide Row Numbers</td><td>Boolean</td><td>Check this option to hide row numbers.</td></tr><tr><td>Auto Select 1st Row</td><td>Boolean</td><td>Check this option to select the first row automatically.</td></tr><tr><td>Total Color</td><td>String</td><td>Total row text color. The default value is <code>#FFFFFF</code>.</td></tr><tr><td>Total Background</td><td>String</td><td>Total row background color. The default value is <code>#0176D2</code>.</td></tr><tr><td>Density</td><td>String</td><td>Grid density: comfy | compact.</td></tr><tr><td>Disable Refresh View</td><td>Boolean</td><td>Check this option to disable the view refresh after an update.</td></tr><tr><td>Actions</td><td>String</td><td>JSON string to initialize the list of available actions from the data grid. See <a href="#export">Export</a>.</td></tr><tr><td>Show Actions as Buttons</td><td>Boolean</td><td>Use buttons for actions instead of icons.</td></tr><tr><td>Custom Visible Actions</td><td>Integer</td><td># of visible custom actions.</td></tr></tbody></table>

## **API Reference**

{% tabs fullWidth="true" %}
{% tab title="ApexDataGridComponent.design" %}

```xml
<design:component label="GM - Apex Data Grid">
    <design:attribute name="recordId" label="recordId"
                      description="recordId to use. Keep this empty if you want to use the current record"/>
    <design:attribute name="providerClass" label="Provider Class"
                      description="Apex class name implementing IApexDataGridProvider"/>
    <design:attribute name="dataGridCode" label="DataGrid Code"
                      description="The code to identify the DataGrid"/>
    <design:attribute name="displayLabel" label="Custom Label"
                      description="Override the label of the data grid"/>
    <design:attribute name="customIcon" label="Custom Icon"
                      description="Customize the data grid icon. All lightning icons are supported. You can get the icon name from https://lightningdesignsystem.com/icons/"/>
    <design:attribute name="rowLimit" label="Row Limit"
                      description="The maximum number of rows to fetch"/>
    <design:attribute name="pageSize" label="Page Size"
                      description="The number of rows to fetch per step"/>
    <design:attribute name="paginationEnabled" label="Enable Pagination"
                      description="Check this option to enable pagination instead of scrolling. Can be combined with interactive filters"/>
    <design:attribute name="height" label="Grid Height"
                      description="Set the grid height"/>
    <design:attribute name="filter" label="Filter"
                      description="Json string to define filter criteria. Don't forget __c for custom fields. Ex. {'StageName':'Needs Analysis'}"/>
    <design:attribute name="jsonSearchFields" label="Search Fields"
                      description="',' separated search fields"/>
    <design:attribute name="wildCardSearch" label="Wildcard Search"
                      description="Use wildcard search"/>
    <design:attribute name="sort" label="Sort"
                      description="The field to sort the data grid on initial load. Don't forget __c for custom fields. Ex. Amount"/>
    <design:attribute name="order" label="Order"
                      description="Asc or Desc order for sorting"/>
    <design:attribute name="aggregate" label="Aggregate"
                      description="Json string to define aggregate fields. Supports 'sum', 'min' and 'max'. Don't forget __c for custom fields. Ex. {'Amount':'sum'}"/>
    <design:attribute name="groupBy" label="Group By"
                      description="',' separated list of fields to group by"/>
    <design:attribute name="collapseGroups" label="Collapse Groups"
                      description="Collapse groups by default"/>
    <design:attribute name="multiLevelGrouping" label="Multi Level Grouping"
                      description="Enable multi level grouping"/>
    <design:attribute name="showAggregateHeader" label="Show Aggregate Header"
                      description="Show the aggregate header as a card on top of the grid"/>
    <design:attribute name="canFreeze" label="Enable Freeze Columns"
                      description="Check this option if you want to freeze columns"/>
    <design:attribute name="frozenColumns" label="Frozen Columns"
                      description="# of columns to freeze"/>
    <design:attribute name="canToggleFullscreen" label="Enable Toggle Fullscreen"
                      description="Check this option if you want to enable toggle fullscreen"/>
    <design:attribute name="canInMemFilter" label="Enable Interactive Filters"
                      description="Check this option if you want to enable interactive filters"/>
    <design:attribute name="hiddenColumns" label="Hidden Columns"
                      description="',' separated list of hidden columns"/>
    <design:attribute name="columnStyles" label="Column Style"
                      description="Json string to define column styles. Don't forget __c for custom fields. Ex. {'StageName':'width:200px'}"/>
    <design:attribute name="fieldLabels" label="Custom Field Labels"
                      description="{name:label} custom field labels map"/>
    <design:attribute name="coloring" label="Cell Coloring"
                      description="JSON conditions for cell coloring"/>
    <design:attribute name="showBorder" label="Show Border"
                      description="Show border around the grid"/>
    <design:attribute name="showColumnBorder" label="Show Column Border"
                      description="Show column borders"/>
    <design:attribute name="noRowNumber" label="Hide Row Numbers"
                      description="Check this option to hide row numbers"/>
    <design:attribute name="selectFirstRow" label="Auto Select 1st Row"
                      description="Automatically select the first row. Applicable only if dynamic interaction is enabled"/>
    <design:attribute name="TotalColor" label="Total Color"
                      description="Total row text color"/>
    <design:attribute name="TotalBgColor" label="Total Background"
                      description="Total row background color"/>
    <design:attribute name="density" label="Density"
                      description="Grid density: comfy | compact"/>
    <design:attribute name="inline" label="Disable Refresh View"
                      description="Check this option to disable the view refresh after an update"/>
    <design:attribute name="jsonActions" label="Actions"
                      description="Json string to initialize the list of available actions from the data grid"/>
    <design:attribute name="buttonActions" label="Show Actions as Buttons"
                      description="Use buttons for actions instead of icons"/>
    <design:attribute name="visibleActions" label="Custom Visible Actions"
                      description="# of visible custom actions"/>
</design:component>
```

{% endtab %}
{% endtabs %}

## Building a Provider

A provider is an Apex class that implements the GridMate interface **gmpkg.IApexDataGridProvider**:

```java
global interface IApexDataGridProvider {
    Map<String, Object> getDataGridMetadata();
    Object[] getItems(String filterBy, String sortBy, String orderBy, Integer rowLimit, Integer rowOffset);
    Integer getItemsCount(String filterBy);
}
```

* **getDataGridMetadata** returns the grid name, its label and its columns. Build it with **gmpkg.ApexDataGridBuilder.buildGridMetadata**.
* **getItems** returns the rows: one `Map<String, Object>` per row, keyed by column name.
* **getItemsCount** returns the number of rows that match `filterBy`. It is used by pagination.

{% hint style="warning" %}
The apex class should be declared as global. If not we will not be able to instantiate the class from the managed package. A `public` provider fails with *Attempt to de-reference a null object*.
{% endhint %}

### Columns

Build the columns with **gmpkg.ApexDataGridBuilder**:

| Factory                                                             | Column type             |
| ------------------------------------------------------------------- | ----------------------- |
| `text(name, label, length)`                                         | Text                    |
| `longText(name, label, length)`                                     | Long text               |
| `richText(name, label, length)`                                     | Rich text               |
| `number(name, label, precision, scale)`                             | Number                  |
| `integer(name, label)`                                              | Integer                 |
| `currency(name, label, precision, scale)`                           | Currency                |
| `percent(name, label, precision, scale)`                            | Percent                 |
| `date(name, label)` / `dateTime(name, label)` / `time(name, label)` | Date / Date-time / Time |
| `checkbox(name, label)`                                             | Checkbox                |
| `picklist(name, label, options)`                                    | Picklist                |
| `multiPicklist(name, label, options)`                               | Multi-select picklist   |
| `email(name, label)` / `phone(name, label)` / `url(name, label)`    | Email / Phone / URL     |

`options` is a `List<Map<String, String>>` of `{'label' => …, 'value' => …}`.

Chain these modifiers on a column:

| Modifier                                      | Effect                                                            |
| --------------------------------------------- | ----------------------------------------------------------------- |
| `withSortable(true)`                          | Users can sort on the column. Columns aren't sortable without it. |
| `withHelp(text)`                              | A help icon on the column header.                                 |
| `withRequired(Boolean)`                       | Marks the column as required.                                     |
| `withLength(Integer)` / `withPrecision(p, s)` | Changes the size of the column's values.                          |

**buildGridMetadata(name, label, columns)** returns the metadata map. It also carries your org's DataGrid Settings: export permission, CSV separator, export date formats, auto-adjusted columns and row numbers.

### Rows

* Return each row as a `Map<String, Object>` keyed by the column names.
* Always include an `Id` key. The grid uses it to tell rows apart.
* When `Id` holds a record Id, a `Name` column links to that record.

### Parameters

| Parameter   | Value                                                                                                                                                                                                                  |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filterBy`  | A JSON string in the GridMate filter format. It starts as the **Filter** property, or `{}` when it's blank. A search adds `{"or":[{"<Search Field>":{"operator":"strictLike","value":"%term%"}}, …]}` inside an `and`. |
| `sortBy`    | The column the user sorted on, or the **Sort** property.                                                                                                                                                               |
| `orderBy`   | `asc` or `desc`.                                                                                                                                                                                                       |
| `rowLimit`  | The number of rows to return.                                                                                                                                                                                          |
| `rowOffset` | The offset of the current page.                                                                                                                                                                                        |

{% hint style="info" %}
Return rows from the first one, up to `rowLimit`. The grid keeps track of the page itself, so don't skip `rowOffset` rows.
{% endhint %}

### Example

```java
global with sharing class InvoiceDataGridProvider implements gmpkg.IApexDataGridProvider {
    global Map<String, Object> getDataGridMetadata() {
        List<gmpkg.ApexDataGridBuilder.Column> columns = new List<gmpkg.ApexDataGridBuilder.Column>{
            gmpkg.ApexDataGridBuilder.text('InvoiceNumber', 'Invoice #', 20).withSortable(true),
            gmpkg.ApexDataGridBuilder.currency('Amount', 'Amount', 12, 2).withSortable(true),
            gmpkg.ApexDataGridBuilder.date('InvoiceDate', 'Invoice Date').withSortable(true),
            gmpkg.ApexDataGridBuilder.picklist('Status', 'Status', new List<Map<String, String>>{
                new Map<String, String>{ 'label' => 'Paid', 'value' => 'PAID' },
                new Map<String, String>{ 'label' => 'Overdue', 'value' => 'OVERDUE' }
            })
        };
        return gmpkg.ApexDataGridBuilder.buildGridMetadata('Invoice', 'Invoices', columns);
    }

    global Object[] getItems(String filterBy, String sortBy, String orderBy, Integer rowLimit, Integer rowOffset) {
        // Call your system here (callout, custom logic…), apply filterBy and sortBy, then return the first rowLimit rows.
        List<Object> rows = new List<Object>();
        for (Integer i = 1; i <= Math.min(rowLimit, 50); i++) {
            rows.add(new Map<String, Object>{
                'Id' => 'INV-' + (1000 + i),
                'InvoiceNumber' => 'INV-' + (1000 + i),
                'Amount' => 500 * i,
                'InvoiceDate' => Date.today().addDays(-7 * i),
                'Status' => Math.mod(i, 3) == 0 ? 'OVERDUE' : 'PAID'
            });
        }
        return rows;
    }

    global Integer getItemsCount(String filterBy) {
        return 50;
    }
}
```

## Export

The grid has no built-in export button. Add the **gmpkg:ApexDataGridExportComponent** in the **Actions** property, with your provider class:

```json
[
    {
        "name": "export",
        "label": "Export",
        "global": true,
        "component": "gmpkg:ApexDataGridExportComponent",
        "attributes": { "providerClass": "InvoiceDataGridProvider" }
    }
]
```

The user picks **Comma Delimited .csv**, **Excel File** or **Formatted Excel File** and a file name. The export calls `getItems` once, from the first row, and contains every row your class returns (up to 50,000), in the visible columns.


---

# 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/package-reference/components-library/grids/gm-apex-data-grid.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.
