---
product: "AG Studio"
title: "Proportional Charts"
description: "Build pie and donut charts in AG Studio to show how a whole splits into parts: which fields they need, data labels, legends and Format settings."
framework: react
version: "3.1.0"
related:
    - title: "Bar and Column Charts"
      url: "https://www.ag-grid.com/studio/analysts/bar-and-column-charts/"
    - title: "Line and Area Charts"
      url: "https://www.ag-grid.com/studio/analysts/line-and-area-charts/"
    - title: "Combo Charts"
      url: "https://www.ag-grid.com/studio/analysts/combo-charts/"
    - title: "Scatter Charts"
      url: "https://www.ag-grid.com/studio/analysts/scatter-charts/"
    - title: "Polar Charts"
      url: "https://www.ag-grid.com/studio/analysts/polar-charts/"
    - title: "Progression Charts"
      url: "https://www.ag-grid.com/studio/analysts/progression-charts/"
    - title: "Hierarchical Charts"
      url: "https://www.ag-grid.com/studio/analysts/hierarchical-charts/"
    - title: "Statistical Charts"
      url: "https://www.ag-grid.com/studio/analysts/statistical-charts/"
llms: "https://www.ag-grid.com/studio/llms.txt"
---

# Proportional Charts

Proportional Charts show how a whole splits into parts.

**Pie Chart** divides a circle into slices to show simple part-to-whole proportions.

**Donut Chart** is a Pie Chart with a hollow centre, leaving room for a central metric or label.

The example below places a Pie Chart beside a Donut Chart splitting the same annual revenue across sales channels, so the hollow centre is the only difference between them.

#### Proportional Chart

```ts
import {
  AgReportState,
  AgStudioApi,
  AgStudioProperties,
  createStudio,
  enableStudioDevValidations,
} from "ag-studio";
import { getData } from "./data.ts";

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

const initialState: AgReportState = {
  pages: [
    {
      id: "page1",
      widgets: {
        "pie-chart": {
          type: "pie-chart",
          dataMapping: {
            categoryKey: [{ id: "sales.channel" }],
            valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
            tooltipKey: [],
          },
          format: {
            title: {
              enabled: true,
              text: "Pie Chart",
            },
            subtitle: {
              enabled: true,
              text: "Share of annual revenue by sales channel",
            },
            style: {
              theme: {
                common: {
                  legend: {
                    position: "right",
                  },
                },
              },
            },
          },
        },
        "donut-chart": {
          type: "donut-chart",
          dataMapping: {
            categoryKey: [{ id: "sales.channel" }],
            valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
            tooltipKey: [],
          },
          format: {
            title: {
              enabled: true,
              text: "Donut Chart",
            },
            subtitle: {
              enabled: true,
              text: "Share of annual revenue by sales channel",
            },
            style: {
              theme: {
                common: {
                  legend: {
                    position: "right",
                  },
                },
              },
            },
          },
        },
      },
      widgetLayout: {
        "pie-chart": { xTrack: 0, yTrack: 0, xSpan: 12, ySpan: 22 },
        "donut-chart": { xTrack: 12, yTrack: 0, xSpan: 12, ySpan: 22 },
      },
    },
  ],
  selectedPageId: "page1",
  panels: {
    filters: {
      collapsed: true,
    },
    data: {
      collapsed: true,
    },
    edit: {
      collapsed: true,
    },
  },
};

const studioProperties: AgStudioProperties = {
  mode: "edit",
  initialState,
  data: getData(),
};

let studioApi: AgStudioApi;

// setup Studio after the page has finished loading
const studioDiv = document.querySelector<HTMLElement>("#myStudio")!;
studioApi = createStudio(studioDiv, studioProperties);
```

[Live example: Proportional Chart](https://www.ag-grid.com/studio/examples/proportional-charts/proportional-chart/typescript/)

## Setup

| Slot | Required | Accepts | What it does |
| --- | --- | --- | --- |
| Label | Yes | One category | Adds one slice for each value of the field, and names it in the legend. |
| Angle | Yes | One numeric field | Sets the size of each slice, as its share of the total. |
| Tooltip | No | Any fields | Shows the fields in the tooltip without plotting them. |

Each Pie or Donut Chart shows one numeric field, so to compare several fields, add a chart for each.

In the example above, Sales Channel is in the Label slot and Revenue is in the Angle slot.

### Tooltip

The tooltip shows each slice's value and its share of the total. Fields in the Tooltip slot are added to the tooltip but are not plotted. Use the slot for context that would clutter the chart, such as the number of units behind each revenue figure.

In the example below, each slice shows revenue for a product category, and the Setup tab is open beside the chart. Hover over a slice to see its Units Sold and Returns, which are in the Tooltip slot.

#### Tooltip

```ts
import {
  AgReportState,
  AgStudioApi,
  AgStudioProperties,
  createStudio,
  enableStudioDevValidations,
} from "ag-studio";
import { getData } from "./data.ts";

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

const initialState: AgReportState = {
  pages: [
    {
      id: "page1",
      widgets: {
        "revenue-by-category": {
          type: "pie-chart",
          dataMapping: {
            categoryKey: [{ id: "sales.category" }],
            valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
            tooltipKey: [
              { id: "sales.units", aggregation: "sum" },
              { id: "sales.returns", aggregation: "sum" },
            ],
          },
          format: {
            title: {
              enabled: true,
              text: "Revenue by Product Category",
            },
          },
        },
      },
      widgetLayout: {
        "revenue-by-category": { xTrack: 0, yTrack: 0, xSpan: 24, ySpan: 24 },
      },
      selection: { type: "widget", id: "revenue-by-category" },
    },
  ],
  selectedPageId: "page1",
};

const studioProperties: AgStudioProperties = {
  mode: "edit",
  initialState,
  panels: {
    edit: {
      right: ["edit"],
    },
  },
  data: getData(),
};

let studioApi: AgStudioApi;

// setup Studio after the page has finished loading
const studioDiv = document.querySelector<HTMLElement>("#myStudio")!;
studioApi = createStudio(studioDiv, studioProperties);
```

[Live example: Tooltip](https://www.ag-grid.com/studio/examples/proportional-charts/proportional-tooltip/typescript/)

## Format

Pie and Donut Charts have these settings of their own on the Format tab, beside the title and appearance settings every chart has. Your developer can change the defaults shown.

| Setting | Where | Default | What it does |
| --- | --- | --- | --- |
| Legend | Elements | On | Shows the legend, with one item for each slice. **Position** places it around the chart, at the bottom by default. |
| Data Labels | Elements | Off | Labels each slice. **Position** puts the label outside or inside the slice. **Format** shows the value or the percentage of the total. **Category** adds the slice's name. **Font** and **Color** change the label text. |
| Total Label | Elements | Off | Donut Chart only. Shows the total of the numeric field in the hollow centre. **Font** and **Color** change the text. |
| Segment Borders | Elements | Off | Draws a border around each slice. **Width** and **Color** change the border. |

When you turn on Data Labels, they start outside the slices and show each slice's percentage of the total, without its name.

Segment Borders keep slices with similar colours distinct. The border is 1 pixel wide and matches the page's Widget background colour until you change it. Slices are separated by a thin gap even with Segment Borders off; turn them on to widen or recolour that edge.

The example below shows each setting turned on in its own chart, over the same data. The first four charts show the Data Labels options on a Pie Chart. The Donut Chart next to the Total Label one shows data labels around a ring.

#### Format

```ts
import {
  AgReportState,
  AgStudioApi,
  AgStudioProperties,
  createStudio,
  enableStudioDevValidations,
} from "ag-studio";
import { getData } from "./data.ts";

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

const initialState: AgReportState = {
  pages: [
    {
      id: "page1",
      widgets: {
        "pie-data-labels": {
          type: "pie-chart",
          dataMapping: {
            categoryKey: [{ id: "sales.channel" }],
            valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
            tooltipKey: [],
          },
          format: {
            title: {
              enabled: true,
              text: "Pie: Data Labels",
            },
            subtitle: {
              enabled: true,
              text: "Elements > Data Labels on",
            },
            style: {
              theme: {
                common: {
                  legend: {
                    position: "right",
                  },
                },
              },
              custom: {
                pieDataLabel: {
                  enabled: true,
                },
              },
            },
          },
        },
        "pie-labels-inside": {
          type: "pie-chart",
          dataMapping: {
            categoryKey: [{ id: "sales.channel" }],
            valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
            tooltipKey: [],
          },
          format: {
            title: {
              enabled: true,
              text: "Pie: Labels Inside",
            },
            subtitle: {
              enabled: true,
              text: "Elements > Data Labels > Position Inside",
            },
            style: {
              theme: {
                common: {
                  legend: {
                    position: "right",
                  },
                },
              },
              custom: {
                pieDataLabel: {
                  enabled: true,
                  position: "inside",
                },
              },
            },
          },
        },
        "pie-labels-value": {
          type: "pie-chart",
          dataMapping: {
            categoryKey: [{ id: "sales.channel" }],
            valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
            tooltipKey: [],
          },
          format: {
            title: {
              enabled: true,
              text: "Pie: Labels as Values",
            },
            subtitle: {
              enabled: true,
              text: "Elements > Data Labels > Format Value",
            },
            style: {
              theme: {
                common: {
                  legend: {
                    position: "right",
                  },
                },
              },
              custom: {
                pieDataLabel: {
                  enabled: true,
                  format: "value",
                },
              },
            },
          },
        },
        "pie-labels-category": {
          type: "pie-chart",
          dataMapping: {
            categoryKey: [{ id: "sales.channel" }],
            valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
            tooltipKey: [],
          },
          format: {
            title: {
              enabled: true,
              text: "Pie: Labels with Category",
            },
            subtitle: {
              enabled: true,
              text: "Elements > Data Labels > Category on",
            },
            style: {
              theme: {
                common: {
                  legend: {
                    position: "right",
                  },
                },
              },
              custom: {
                pieDataLabel: {
                  enabled: true,
                  category: true,
                },
              },
            },
          },
        },
        "donut-data-labels": {
          type: "donut-chart",
          dataMapping: {
            categoryKey: [{ id: "sales.channel" }],
            valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
            tooltipKey: [],
          },
          format: {
            title: {
              enabled: true,
              text: "Donut: Data Labels",
            },
            subtitle: {
              enabled: true,
              text: "Elements > Data Labels on",
            },
            style: {
              theme: {
                common: {
                  legend: {
                    position: "right",
                  },
                },
              },
              custom: {
                pieDataLabel: {
                  enabled: true,
                },
              },
            },
          },
        },
        "donut-total-label": {
          type: "donut-chart",
          dataMapping: {
            categoryKey: [{ id: "sales.channel" }],
            valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
            tooltipKey: [],
          },
          format: {
            title: {
              enabled: true,
              text: "Donut: Total Label",
            },
            subtitle: {
              enabled: true,
              text: "Elements > Total Label on",
            },
            style: {
              theme: {
                common: {
                  legend: {
                    position: "right",
                  },
                },
              },
              custom: {
                totalLabel: {
                  enabled: true,
                },
              },
            },
          },
        },
        "pie-segment-borders": {
          type: "pie-chart",
          dataMapping: {
            categoryKey: [{ id: "sales.channel" }],
            valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
            tooltipKey: [],
          },
          format: {
            title: {
              enabled: true,
              text: "Pie: Segment Borders",
            },
            subtitle: {
              enabled: true,
              text: "Elements > Segment Borders on, Width 2",
            },
            style: {
              theme: {
                common: {
                  legend: {
                    position: "right",
                  },
                },
              },
              custom: {
                seriesStroke: {
                  enabled: true,
                  strokeWidth: 2,
                },
              },
            },
          },
        },
        "donut-legend-position": {
          type: "donut-chart",
          dataMapping: {
            categoryKey: [{ id: "sales.channel" }],
            valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
            tooltipKey: [],
          },
          format: {
            title: {
              enabled: true,
              text: "Donut: Legend Position",
            },
            subtitle: {
              enabled: true,
              text: "Elements > Legend > Position Left",
            },
            style: {
              theme: {
                common: {
                  legend: {
                    enabled: true,
                    position: "left",
                  },
                },
              },
            },
          },
        },
      },
      widgetLayout: {
        "pie-data-labels": { xTrack: 0, yTrack: 0, xSpan: 12, ySpan: 22 },
        "pie-labels-inside": { xTrack: 12, yTrack: 0, xSpan: 12, ySpan: 22 },
        "pie-labels-value": { xTrack: 0, yTrack: 22, xSpan: 12, ySpan: 22 },
        "pie-labels-category": { xTrack: 12, yTrack: 22, xSpan: 12, ySpan: 22 },
        "donut-data-labels": { xTrack: 0, yTrack: 44, xSpan: 12, ySpan: 22 },
        "donut-total-label": { xTrack: 12, yTrack: 44, xSpan: 12, ySpan: 22 },
        "pie-segment-borders": { xTrack: 0, yTrack: 66, xSpan: 12, ySpan: 22 },
        "donut-legend-position": {
          xTrack: 12,
          yTrack: 66,
          xSpan: 12,
          ySpan: 22,
        },
      },
    },
  ],
  selectedPageId: "page1",
  panels: {
    filters: {
      collapsed: true,
    },
    data: {
      collapsed: true,
    },
    edit: {
      collapsed: true,
    },
  },
};

const studioProperties: AgStudioProperties = {
  mode: "edit",
  initialState,
  data: getData(),
};

let studioApi: AgStudioApi;

// setup Studio after the page has finished loading
const studioDiv = document.querySelector<HTMLElement>("#myStudio")!;
studioApi = createStudio(studioDiv, studioProperties);
```

[Live example: Format](https://www.ag-grid.com/studio/examples/proportional-charts/proportional-format/typescript/)