> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Pie chart
> Show composition of a metric across a small number of categories.
A **pie chart** displays a single metric as slices of a circle, with each slice's size proportional to that category's share of the total. Pie charts are best for showing composition at a glance — for example, how spend is distributed across channels, or how sessions are split across countries.
## When to use a pie chart
* **Composition of a whole** — showing shares of a metric across a small set of categories.
* **A quick visual read** — pie charts communicate a "biggest slice / smallest slice" idea faster than a table.
* **Small category sets** — 4 to 8 slices is ideal. Beyond that, the chart gets crowded and shares get hard to distinguish.
For larger category sets or precise value comparisons, a [column chart](/widgets/widget-library/chart-widgets/column-chart) is easier to read.
## Configure a pie chart
### Mandatory fields
In the **Data sources** section, select the data source to include. Pie charts support both ad and non-ad data sources and can pull from a blended source.
Click **Edit** on the Metric field to open the picker panel. Pick up to **20 metrics** to make available in the widget's dropdown, reorder them if needed, and set the active one shown by default. The active metric renders as the values sizing each pie slice — for example, Spend, Impressions, or Conversions.
New custom metrics can be created directly from the picker panel without leaving the chart widget.
Click **Edit** on the Group by field to open the picker panel. Pick up to **20 breakdowns** to make available in the widget's dropdown, reorder them if needed, and set the active one shown by default. The active breakdown determines how the metric is split into slices — for example, Campaign name produces one slice per campaign. Pie charts don't render time-series, so date values (Day, Week, Month, and so on) aren't valid Group by choices.
To show a single full circle representing the metric total without splitting, select the **No grouping** option (though a pie chart with no grouping is a single unbroken circle, so most configurations use a real Group by).
New custom breakdowns can be created directly from the picker panel without leaving the chart widget.
Widget changes save automatically when the settings panel closes. Persist changes to the dashboard by clicking **Save dashboard**.
### Optional fields
* **Widget filter** — narrow the data feeding the widget. See [Filters](/dashboards/filters-and-dates/filters).
* **Period** — override the dashboard's date range. See [Date ranges](/dashboards/filters-and-dates/date-ranges).
* **Hide metric value** — hide slices whose **Ad Spend**, **Impressions**, or **Link Clicks** meet a threshold. Two blocks are available: a preset "Value = 0" checkbox per metric, and a custom threshold block with an operator (default `≤`) and value. Both can be combined.
* **Display settings** — controls **Number of items** (All, 5, 10, 15, 20; default 10), **Sort order**, and a Hide "others" toggle for the aggregate residual slice.
* **Data labels** — show the value or percentage on each slice. **On by default** for pie charts.
* **Chart controls** — toggle whether Chart controls render on this widget. On by default.
## Chart controls
Chart controls are toggled on or off per widget from the **Chart controls** switch in the widget settings panel. When off, Chart controls don't render on the widget; when on, the dropdowns configured below appear on the widget.
Some key settings can be updated directly from the widget header without opening the settings panel. The **Chart controls** on a pie chart expose:
* **Chart type** — a switcher on the left of the widget header to change to another chart type.
* **Sort order** — change slice ordering inline.
* **Metric** — swap the plotted metric inline.
* **Group by** — change how the metric is split into slices inline.
Changes made in the Chart controls **aren't saved automatically** — click **Save dashboard** to persist them. Chart controls are read-only when viewing a shared dashboard. In shared dashboards, Chart controls show only the items selected in each field, matching what the dashboard owner configured.
## Comparison mode
**Pie charts do not render comparison values.** Even when the Compare toggle is on, the pie chart draws only the primary window.
For a chart with comparison support, use a [column chart](/widgets/widget-library/chart-widgets/column-chart), [horizontal column chart](/widgets/widget-library/chart-widgets/horizontal-column-chart), or [line chart](/widgets/widget-library/chart-widgets/line-chart).
## Widget styling
Global widget style settings — font, border, background, and color themes — apply to every widget through the [Dashboard style settings](/dashboards/building/dashboard-style-settings#global-widget-settings). On top of those, Pie chart widgets have style options unique to this widget type:
* **Metric name font** — weight, size, and HEX color for the metric name label.
* **Metric value font** — weight, size, and HEX color for the aggregated value shown on the widget.
* **Color type** — toggle between **Solid** and **Gradient** for the slice fill.
* **Data text** — when data labels are enabled, the label color (HEX) and stroke color (HEX + opacity) are configurable.
## Troubleshooting
The Group by is set to **No grouping** — the metric is shown as its total without segmentation. Set a Group by to a field like Channel to split the total into slices.
Too many small slices. Reduce **Number of items** in Display settings, apply a widget filter, or pick a coarser Group by to consolidate small categories into fewer larger slices.
A long-tail category set — most categories are small enough to fall into others. Increase **Number of items**, narrow with a widget filter, or turn off Hide "others" to see the aggregate residual.
## Related
Same idea with a hollow center that shows the metric total.
Precise comparisons across categories.
Show the total without slices.