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

# Donut chart

> Show composition of a metric across a small number of categories, with the total displayed in the center.

A **donut chart** displays a single metric as segments of a ring, with each segment's size proportional to that category's share of the total. It's the same use case as a [pie chart](/widgets/widget-library/chart-widgets/pie-chart), with the addition of a value in the hollow center showing the metric total — so composition and total are both readable at a glance.

## When to use a donut chart

* **Composition of a whole** — showing shares of a metric across a small set of categories.
* **Composition plus total** — the ring shows each category's share while the center shows the aggregate.
* **Small category sets** — 4 to 8 segments is ideal. Beyond that, the chart gets crowded.

For a pie without the center total, use a [pie chart](/widgets/widget-library/chart-widgets/pie-chart). For precise comparisons across categories, a [column chart](/widgets/widget-library/chart-widgets/column-chart) is easier to read.

## Configure a donut chart

### Mandatory fields

<Steps>
  <Step title="Pick a data source">
    In the **Data sources** section, select the data source to include. Donut charts support both ad and non-ad data sources and can pull from a blended source.
  </Step>

  <Step title="Pick a Metric">
    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 ring segment and the center value — for example, Spend, Impressions, or Conversions.

    New custom metrics can be created directly from the picker panel without leaving the chart widget.
  </Step>

  <Step title="Set the Group by">
    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 segments — for example, Campaign name produces one segment per campaign. Donut 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 ring representing the metric total without splitting, select the **No grouping** option (though a donut chart with no grouping is a single unbroken ring, so most configurations use a real Group by).

    New custom breakdowns can be created directly from the picker panel without leaving the chart widget.
  </Step>
</Steps>

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 segments 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 segment.
* **Data labels** — show the value or percentage on each segment. **On by default** for donut 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 donut chart expose:

* **Chart type** — a switcher on the left of the widget header to change to another chart type.
* **Sort order** — change segment ordering inline.
* **Metric** — swap the plotted metric inline.
* **Group by** — change how the metric is split into segments 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.

## Center value

The donut's hollow center shows the total of the selected metric across every visible segment plus the aggregate residual. Font settings for the center are configurable in widget styling.

If a custom breakdown is applied, the center value is set to `0` — because a custom breakdown's per-label totals don't roll up to a single parent metric.

## Comparison mode

**Donut charts do not render comparison values.** Even when the Compare toggle is on, the donut 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, Donut chart widgets have style options unique to this widget type:

* **Metric name font** — weight, size, and HEX color for the metric name label around the donut center.
* **Metric value font** — weight, size, and HEX color for the aggregated total rendered in the donut's center hole.
* **Color type** — toggle between **Solid** and **Gradient** for the ring fill.
* **Data text** — when data labels are enabled, the **Data Label** color (HEX) and the **Data Label Stroke** (HEX + opacity + stroke weight) are configurable.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The donut is one solid ring with no segments">
    The Group by is set to **No grouping**. Set a Group by to a field like Channel to split the total into segments.
  </Accordion>

  <Accordion title="Center value shows 0">
    A custom breakdown is active. Center values only compute against the parent metric — when a custom breakdown is applied, the center is forced to `0`.
  </Accordion>

  <Accordion title="Segments are hard to distinguish">
    Too many small segments. Reduce **Number of items** in Display settings, apply a widget filter, or pick a coarser Group by.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Pie chart" href="/widgets/widget-library/chart-widgets/pie-chart">
    Same idea without the center value display.
  </Card>

  <Card title="Column chart" href="/widgets/widget-library/chart-widgets/column-chart">
    Precise comparisons across categories.
  </Card>

  <Card title="Single metric" href="/widgets/widget-library/other-widgets/single-metric">
    Show the total without segmentation.
  </Card>
</CardGroup>