---
title: "Aggregation - Show Values As"
enterprise: true
framework: javascript
version: "36.1.0"
---

# Aggregation - Show Values As

Show each value as a relative figure, such as a percentage of the grand total or of its parent group.

"Show Values As" displays a column's value as a share of a grand, column or group total. The underlying data is unchanged — the value is transformed only for display.

A mode can be chosen by the user from the column menu, set on the column definition, or applied through [Column State](https://www.ag-grid.com/javascript-data-grid/column-state/).

#### Show Values As Overview

```ts
import {
  ClientSideRowModelModule,
  GridApi,
  GridOptions,
  ModuleRegistry,
  NumberFilterModule,
  TextFilterModule,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnMenuModule,
  ColumnsToolPanelModule,
  ContextMenuModule,
  RowGroupingModule,
  ShowValuesAsModule,
} from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";

// Enable extended validations only for development
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

ModuleRegistry.registerModules([
  ClientSideRowModelModule,
  TextFilterModule,
  NumberFilterModule,
  ColumnMenuModule,
  ContextMenuModule,
  ColumnsToolPanelModule,
  RowGroupingModule,
  ShowValuesAsModule,
]);

let gridApi: GridApi<IOlympicData>;

const gridOptions: GridOptions<IOlympicData> = {
  columnDefs: [
    { field: "country", rowGroup: true, hide: true, enableRowGroup: true },
    { field: "year", rowGroup: true, hide: true, enableRowGroup: true },
    { field: "athlete" },
    {
      field: "total",
      headerName: "Total",
      aggFunc: "sum",
      enableValue: true,
      enableShowValuesAs: true,
    },
    {
      field: "total",
      colId: "totalPercentOfParent",
      headerName: "Total of Parent",
      aggFunc: "sum",
      showValuesAs: "percentOfParentRowTotal",
      enableValue: true,
      enableShowValuesAs: true,
    },
  ],
  defaultColDef: {
    flex: 1,
    minWidth: 130,
  },
  autoGroupColumnDef: {
    minWidth: 220,
  },
  groupDefaultExpanded: 1,
  grandTotalRow: "top",
  isGroupOpenByDefault: (params) => {
    const route = params.rowNode.getRoute();
    const destPath = ["United States", "2008"];
    return route.every((item, idx) => destPath[idx] === item);
  },
  suppressAggFuncInHeader: true,
};

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

fetch("https://www.ag-grid.com/example-assets/small-olympic-winners.json")
  .then((response) => response.json())
  .then((data: IOlympicData[]) => gridApi!.setGridOption("rowData", data));
```

[Live example: Show Values As Overview](https://www.ag-grid.com/examples/aggregation-show-values-as/show-values-as-overview/typescript)

This example groups Olympic winners by country and year, then shows raw medal totals alongside the same values as a percentage of their parent group.

> **Note**
>
> Show Values As requires the `ShowValuesAsModule` and is only supported with the [Client-Side Row Model](https://www.ag-grid.com/javascript-data-grid/row-models/#client-side).

## Column Menu

The Show Values As submenu is off by default. To let the user switch mode from the [Column Menu](https://www.ag-grid.com/javascript-data-grid/column-menu/), register the `ColumnMenuModule` and set `enableShowValuesAs: true` on the required columns. Switching mode only updates the affected column — it does not re-aggregate, re-sort or re-filter.

The effect depends on where you set it:

- **On `defaultColDef`** - the grid applies `enableShowValuesAs` selectively only to columns that have a numeric type or an `aggFunc`.
- **On a single column** - always applied, whatever the column type. Use this when the column type cannot be inferred, such as a `valueGetter` or custom `aggFunc` that returns a number from string or object data.

```js
const gridOptions = {
    // Grid-wide: offered on value/numeric columns only.
    defaultColDef: { enableShowValuesAs: true },
    columnDefs: [
        // Force the menu on a column the heuristic wouldn't include.
        { field: 'label', enableShowValuesAs: true },
    ],

    // other grid options ...
}
```

A numeric column that is not yet aggregated is promoted to a value column when a mode needing a total is chosen.

## Built-in Modes

| Mode | Shows each value as | Applies when |
| --- | --- | --- |
| `percentOfGrandTotal` | Share of the column's grand total | Value or numeric column |
| `percentOfColumnTotal` | Share of its column total | Value or numeric column |
| `percentOfRowTotal` | Share of the row total | Pivoting |
| `percentOfParentRowTotal` | Share of its parent row group | Row grouping or tree data |
| `percentOfParentColumnTotal` | Share of its parent pivot column | Pivoting |

`percentOfGrandTotal` and `percentOfColumnTotal` give the same result outside [Pivot](https://www.ag-grid.com/javascript-data-grid/pivoting/) mode, where there is a single column total. They diverge only while pivoting: `percentOfGrandTotal` keeps the whole column's grand total as the denominator, whereas `percentOfColumnTotal` uses each pivot column's own total, so every pivot column sums to 100%.

If a mode was already active when the grid left the view that supports it, the selection is kept — its cells show `#N/A`. In the column menu it appears greyed and cannot be selected.

## Setting the Mode

Set `showValuesAs` on a value column to the mode you want. Use [`initialShowValuesAs`](https://www.ag-grid.com/javascript-data-grid/column-updating-definitions/#changing-column-state) instead to set only the starting mode and leave the user free to change it from the menu.

```js
const gridOptions = {
    columnDefs: [
        { field: 'country', rowGroup: true, hide: true },
        { field: 'gold', aggFunc: 'sum', showValuesAs: 'percentOfParentRowTotal' },
        { field: 'total', aggFunc: 'sum', showValuesAs: 'percentOfGrandTotal' },
    ],

    // other grid options ...
}
```

The object form takes an optional `precision` to override the configured decimal places for that selection:

```js
const gridOptions = {
    field: 'gold',
    aggFunc: 'sum',
    showValuesAs: { type: 'percentOfGrandTotal', precision: 1 },

    // other grid options ...
}
```

### Column State

The active mode is part of [Column State](https://www.ag-grid.com/javascript-data-grid/column-state/), so a runtime change is applied through `applyColumnState` rather than by mutating the column definition. Set `showValuesAs` to a mode to enable it, or to `null` to clear it:

```js
// Enable a mode
api.applyColumnState({ state: [{ colId: 'gold', showValuesAs: 'percentOfGrandTotal' }] });

// Disable it
api.applyColumnState({ state: [{ colId: 'gold', showValuesAs: null }] });
```

The active mode is also part of [Grid State](https://www.ag-grid.com/javascript-data-grid/grid-state/), so it persists and restores through `initialState`, `api.getState()` and `api.setState()`.

### Reading the Transformed Value

The methods `api.getCellValue` and `rowNode.getDataValue` return the raw aggregate by default. To read the transformed value, pass `transformValues: true` to `api.getCellValue`, or `'transformed'` to `rowNode.getDataValue`:

```js
const shown = api.getCellValue({ rowNode, colKey: 'gold', transformValues: true });
const same = rowNode.getDataValue('gold', 'transformed');
```

## Configuration

`showValuesAsDef` configures Show Values As for a column, and deep-merges from `defaultColDef` for grid-wide settings. It controls the default `precision` (decimal places, default `2`) and `suppressHeaderIndicator` (the icon shown in the column header while a mode is active).

```js
const gridOptions = {
    defaultColDef: {
        showValuesAsDef: { precision: 1 },
    },

    // other grid options ...
}
```

To turn Show Values As off for a column, set `showValuesAsDef` to `null` — on a single column, or on `defaultColDef` for every column:

```js
const gridOptions = {
    // Disable for all columns
    defaultColDef: {
        showValuesAsDef: null,
    },
    columnDefs: [
        // Disable for this column only
        { field: 'gold', aggFunc: 'sum', showValuesAsDef: null },
    ],

    // other grid options ...
}
```

## Row Grouping

This example groups Olympic winners by country, showing gold medals as a percentage of their parent group and the medal total as a percentage of the column's grand total.

#### Show Values As with Row Grouping

```ts
import {
  ClientSideRowModelModule,
  GridApi,
  GridOptions,
  ModuleRegistry,
  NumberFilterModule,
  TextFilterModule,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnMenuModule,
  ColumnsToolPanelModule,
  ContextMenuModule,
  RowGroupingModule,
  ShowValuesAsModule,
} from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";

// Enable extended validations only for development
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

ModuleRegistry.registerModules([
  ClientSideRowModelModule,
  TextFilterModule,
  NumberFilterModule,
  ColumnMenuModule,
  ContextMenuModule,
  ColumnsToolPanelModule,
  RowGroupingModule,
  ShowValuesAsModule,
]);

let gridApi: GridApi<IOlympicData>;

const gridOptions: GridOptions<IOlympicData> = {
  columnDefs: [
    { field: "country", rowGroup: true, hide: true },
    { field: "year", filter: "agNumberColumnFilter" },
    // Each value as a share of its parent group.
    { field: "gold", aggFunc: "sum", showValuesAs: "percentOfParentRowTotal" },
    { field: "silver", aggFunc: "sum", hide: true },
    // Each value as a share of the whole column.
    { field: "total", aggFunc: "sum", showValuesAs: "percentOfGrandTotal" },
  ],
  defaultColDef: {
    flex: 1,
    minWidth: 160,
    enableValue: true,
    enableShowValuesAs: true,
    filter: true,
    floatingFilter: true,
  },
  autoGroupColumnDef: {
    minWidth: 220,
  },
  groupDefaultExpanded: 1,
  grandTotalRow: "bottom",
  sideBar: {
    toolPanels: ["columns"],
    defaultToolPanel: undefined,
  },
};

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

fetch("https://www.ag-grid.com/example-assets/small-olympic-winners.json")
  .then((response) => response.json())
  .then((data: IOlympicData[]) => gridApi!.setGridOption("rowData", data));
```

[Live example: Show Values As with Row Grouping](https://www.ag-grid.com/examples/aggregation-show-values-as/row-grouping/typescript)

## Flat Data

Show Values As does not require grouping. On a flat grid each row can be shown as a share of the column's grand total. The example below enables a [Grand Total Row](https://www.ag-grid.com/javascript-data-grid/aggregation-total-rows/) so the 100% total is visible at the bottom.

#### Show Values As on a Flat Grid

```ts
import {
  ClientSideRowModelModule,
  GridApi,
  GridOptions,
  ModuleRegistry,
  NumberFilterModule,
  TextFilterModule,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnMenuModule,
  ContextMenuModule,
  RowGroupingModule,
  ShowValuesAsModule,
} from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";

// Enable extended validations only for development
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

ModuleRegistry.registerModules([
  ClientSideRowModelModule,
  TextFilterModule,
  NumberFilterModule,
  RowGroupingModule,
  ColumnMenuModule,
  ContextMenuModule,
  ShowValuesAsModule,
]);

let gridApi: GridApi<IOlympicData>;

const gridOptions: GridOptions<IOlympicData> = {
  columnDefs: [
    { field: "athlete", minWidth: 200 },
    { field: "country" },
    { field: "year", filter: "agNumberColumnFilter" },
    // No row grouping: each row is shown as its share of the column's grand total.
    { field: "gold", aggFunc: "sum", showValuesAs: "percentOfGrandTotal" },
  ],
  defaultColDef: {
    flex: 1,
    minWidth: 130,
    enableValue: true,
    enableShowValuesAs: true,
    filter: true,
    floatingFilter: true,
  },
  grandTotalRow: "bottom",
};

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
  .then((response) => response.json())
  .then((data: IOlympicData[]) => gridApi!.setGridOption("rowData", data));
```

[Live example: Show Values As on a Flat Grid](https://www.ag-grid.com/examples/aggregation-show-values-as/flat/typescript)

## Tree Data

With [Tree Data](https://www.ag-grid.com/javascript-data-grid/tree-data/), aggregates are populated on parent nodes, so each node's value can be shown as a percentage of its parent row total.

#### Show Values As with Tree Data

```ts
import {
  ClientSideRowModelModule,
  GridApi,
  GridOptions,
  ModuleRegistry,
  TextFilterModule,
  ValueFormatterParams,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnMenuModule,
  ColumnsToolPanelModule,
  ContextMenuModule,
  ShowValuesAsModule,
  TreeDataModule,
} from "ag-grid-enterprise";
import { FileRow, getData } from "./data";

// Enable extended validations only for development
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

ModuleRegistry.registerModules([
  ClientSideRowModelModule,
  TextFilterModule,
  ColumnMenuModule,
  ContextMenuModule,
  ColumnsToolPanelModule,
  TreeDataModule,
  ShowValuesAsModule,
]);

const formatSize = (params: ValueFormatterParams) => {
  const kb = (params.value ?? 0) / 1024;
  return kb > 1024 ? `${(kb / 1024).toFixed(1)} MB` : `${kb.toFixed(0)} KB`;
};

let gridApi: GridApi<FileRow>;

const gridOptions: GridOptions<FileRow> = {
  columnDefs: [
    // Tree data populates aggregates on parent folders, so each node's size is shown
    // as a share of the folder that contains it.
    {
      field: "size",
      aggFunc: "sum",
      valueFormatter: formatSize,
      showValuesAs: "percentOfParentRowTotal",
    },
  ],
  defaultColDef: {
    flex: 1,
    minWidth: 130,
    enableValue: true,
    enableShowValuesAs: true,
    filter: true,
  },
  autoGroupColumnDef: {
    headerName: "Folder",
    minWidth: 280,
    filter: "agTextColumnFilter",
  },
  treeData: true,
  groupDefaultExpanded: 1,
  getDataPath: (data) => data.path,
  rowData: getData(),
  sideBar: "columns",
};

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);
```

[Live example: Show Values As with Tree Data](https://www.ag-grid.com/examples/aggregation-show-values-as/tree-data/typescript)

## Pivoting

In [Pivot](https://www.ag-grid.com/javascript-data-grid/pivoting/) mode each pivot column carries its own total, so a value can be shown as a share of its column.

#### Show Values As with Pivoting

```ts
import {
  ClientSideRowModelModule,
  GridApi,
  GridOptions,
  ModuleRegistry,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnMenuModule,
  ColumnsToolPanelModule,
  ContextMenuModule,
  PivotModule,
  ShowValuesAsModule,
} from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";

// Enable extended validations only for development
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

ModuleRegistry.registerModules([
  ClientSideRowModelModule,
  ColumnMenuModule,
  ContextMenuModule,
  ColumnsToolPanelModule,
  PivotModule,
  ShowValuesAsModule,
]);

let gridApi: GridApi<IOlympicData>;

const gridOptions: GridOptions<IOlympicData> = {
  columnDefs: [
    { field: "country", rowGroup: true },
    { field: "year", pivot: true },
    // In pivot mode each pivot column is shown as a share of that column's total (each column = 100%).
    { field: "gold", aggFunc: "sum", showValuesAs: "percentOfColumnTotal" },
    { field: "silver", aggFunc: "sum" },
  ],
  defaultColDef: {
    flex: 1,
    minWidth: 160,
    enableValue: true,
    enableShowValuesAs: true,
  },
  autoGroupColumnDef: {
    minWidth: 200,
  },
  pivotMode: true,
  sideBar: {
    toolPanels: ["columns"],
    defaultToolPanel: undefined,
  },
};

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
  .then((response) => response.json())
  .then((data: IOlympicData[]) => gridApi!.setGridOption("rowData", data));
```

[Live example: Show Values As with Pivoting](https://www.ag-grid.com/examples/aggregation-show-values-as/pivot/typescript)

## Filtering

Show Values As reads the column's existing aggregate, so its denominators follow the grid's [aggregation filtering](https://www.ag-grid.com/javascript-data-grid/aggregation-filtering/) rules. By default totals reflect only the rows that pass the filter, so the shown rows sum to 100%. Set `suppressAggFilteredOnly` to keep the unfiltered total in the denominator.

## API Reference

Show Values As is configured with the following column properties:

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `showValuesAs` | `ShowValuesAsType \| ShowValuesAs \| null` |  |  | The active "Show Values As" mode for this column. Shows the column's aggregated value relative to another total, for example as a percentage of the grand total, column total, row total or parent total. This changes only the displayed value; the underlying value used by `getDataValue` and charts is unchanged. Use a built-in mode name, or the object form `{ type, params, precision }`. Set `null` for no active mode. Module: [`ShowValuesAsModule`](https://www.ag-grid.com/javascript-data-grid/modules/). |
| `initialShowValuesAs` | `ShowValuesAsType \| ShowValuesAs` |  |  | Same as `showValuesAs`, except only applied when creating a new column. Module: [`ShowValuesAsModule`](https://www.ag-grid.com/javascript-data-grid/modules/). [Initial](https://www.ag-grid.com/javascript-data-grid/grid-interface/#initial-grid-options). |
| `showValuesAsDef` | `ShowValuesAsDef \| null` |  |  | Per-column "Show Values As" configuration: `precision`, `suppressHeaderIndicator`, and user-provided `modes` (custom modes / overrides of the built-ins). Deep-merges from `defaultColDef`. The active mode is the `showValuesAs` selector. `null` disables the feature for the column (useful to opt a column out via `defaultColDef`). Module: [`ShowValuesAsModule`](https://www.ag-grid.com/javascript-data-grid/modules/). |
| `enableShowValuesAs` | `boolean` |  | `false` | Shows the "Show Values As" submenu in the column menu. On `defaultColDef`, `true` shows the submenu only for value columns and numeric columns. On an individual column, `true` always shows it; use this when the grid cannot infer that the column returns numbers, for example with a `valueGetter` or custom `aggFunc`. `false` hides the submenu. This controls menu visibility only. Modes set through `showValuesAs` or Column State still apply. Module: [`ShowValuesAsModule`](https://www.ag-grid.com/javascript-data-grid/modules/). |

The transformed value can be read through the grid API:

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `getCellValue` | `Function` |  |  | Gets the cell value for the given column and `rowNode` (row). Will return the cell value or the formatted value depending on the value of `params.useFormatter`. The `params.from` option controls which value is resolved, including `'transformed'` to read the displayed [Show Values As](https://www.ag-grid.com/javascript-data-grid/aggregation-show-values-as/) value. Module: [`CellApiModule`](https://www.ag-grid.com/javascript-data-grid/modules/). |