Components · Pies

Donut with total

A donut with a headline figure in the centre.

Open in playground

Preview

Revenue by region

Usage

tsx
import {
  ChartsProvider,
  DonutLabelChart,
  dimension,
  measure,
  results,
} from 'em-kit';

const region = dimension({ name: 'region', title: 'Region' });
const revenue = measure({
  name: 'revenue',
  title: 'Revenue',
  inputs: { currency: 'USD', abbreviateLargeNumber: true },
});

export const Example = () => (
  <ChartsProvider>
    <div style={{ height: 480 }}>
      <DonutLabelChart
        title="Revenue by region"
        dimension={region}
        measure={revenue}
        results={results(rows)}
        innerLabelMeasure={revenue}
        innerLabelText="Total"
        resultsInnerLabel={results(totalRows)}
      />
    </div>
  </ChartsProvider>
);

const rows = [
  { region: 'North America', revenue: 324606 },
  { region: 'Europe', revenue: 221197 },
  { region: 'Asia Pacific', revenue: 146411 },
  { region: 'Latin America', revenue: 84145 },
  { region: 'Middle East', revenue: 61120 },
];

const totalRows = [{ revenue: 837479 }];

Install with npm install em-kit. Needs <ChartsProvider> once and a parent with a height: Quick start.

Examples

Percentages

The total in the centre and each segment’s share around it. showValueAsPercentage is a field option on the measure; the centre still shows the total.

tsxDiffers from Usage
Show full code (50 lines)
import {
  ChartsProvider,
  DonutLabelChart,
  dimension,
  measure,
  results,
} from 'em-kit';

const region = dimension({ name: 'region', title: 'Region' });
const revenue = measure({
  name: 'revenue',
  title: 'Revenue',
  inputs: { currency: 'USD', decimalPlaces: 0 },
});

export const Example = () => (
  <ChartsProvider>
    <div style={{ height: 480 }}>
      <DonutLabelChart
        title="Revenue by region"
        dimension={region}
        measure={{
          ...revenue,
          inputs: { ...revenue.inputs, showValueAsPercentage: true },
        }}
        results={results(rows)}
        innerLabelMeasure={{
          ...revenue,
          inputs: {
            ...revenue.inputs,
            abbreviateLargeNumber: true,
            decimalPlaces: undefined,
          },
        }}
        innerLabelText="Total"
        resultsInnerLabel={results(totalRows)}
      />
    </div>
  </ChartsProvider>
);

const rows = [
  { region: 'North America', revenue: 324606 },
  { region: 'Europe', revenue: 221197 },
  { region: 'Asia Pacific', revenue: 146411 },
  { region: 'Latin America', revenue: 84145 },
  { region: 'Middle East', revenue: 61120 },
];

const totalRows = [{ revenue: 837479 }];
const revenue = measure({
  name: 'revenue',
  title: 'Revenue',
  inputs: { currency: 'USD', decimalPlaces: 0 },
});

<DonutLabelChart
  title="Revenue by region"
  dimension={region}
  measure={{
    ...revenue,
    inputs: { ...revenue.inputs, showValueAsPercentage: true },
  }}
  results={results(rows)}
  innerLabelMeasure={{
    ...revenue,
    inputs: {
      ...revenue.inputs,
      abbreviateLargeNumber: true,
      decimalPlaces: undefined,
    },
  }}
  innerLabelText="Total"
  resultsInnerLabel={results(totalRows)}
/>

A count in full

A smaller figure written out in full in the centre: the inner label takes its own measure and rows. innerLabelMeasure and resultsInnerLabel are separate from the donut’s own measure and rows.

tsxDiffers from Usage
Show full code (36 lines)
import {
  ChartsProvider,
  DonutLabelChart,
  dimension,
  measure,
  results,
} from 'em-kit';

const region = dimension({ name: 'region', title: 'Region' });
const customers = measure({ name: 'customers', title: 'Customers' });

export const Example = () => (
  <ChartsProvider>
    <div style={{ height: 480 }}>
      <DonutLabelChart
        title="Customers by region"
        dimension={region}
        measure={customers}
        results={results(rows)}
        innerLabelMeasure={customers}
        innerLabelText="Total"
        resultsInnerLabel={results(totalRows)}
      />
    </div>
  </ChartsProvider>
);

const rows = [
  { region: 'North America', customers: 985 },
  { region: 'Europe', customers: 709 },
  { region: 'Asia Pacific', customers: 451 },
  { region: 'Latin America', customers: 240 },
  { region: 'Middle East', customers: 188 },
];

const totalRows = [{ customers: 2573 }];
const customers = measure({ name: 'customers', title: 'Customers' });

<DonutLabelChart
  title="Customers by region"
  dimension={region}
  measure={customers}
  results={results(rows)}
  innerLabelMeasure={customers}
  innerLabelText="Total"
  resultsInnerLabel={results(totalRows)}
/>

const totalRows = [{ customers: 2573 }];

Props

Not listed: showValueLabelsAsPercentage, which the type accepts and the component does not read. Keyboard and screen readers: Accessibility.

PropTypeDefaultDescription
dimensionrequiredDimensionThe field whose values label the axis or the segments. Its name is the row key.
measurerequiredMeasureThe numeric field to plot. Its inputs (prefix, suffix, decimalPlaces) set the formatting.
innerLabelMeasurerequiredMeasureThe measure shown in the centre of the donut, read from resultsInnerLabel.
resultsrequiredDataResponseYour query’s state: { isLoading, data, error }, where data is your rows. results(rows) builds it from an array.
resultsInnerLabelrequiredDataResponseA one-row result whose value is shown in the centre of the donut.
maxLegendItemsnumber10Show at most this many segments. The rest are added up into one “Other” segment.
showLegendbooleantrueShow the legend. Entries wrap onto more lines when they do not fit.
showTooltipsbooleantrueShow a formatted tooltip on hover.
showValueLabelsbooleantruePrint each value on the chart.
onSegmentClick(args: PieChartClickArg) => voidCalled with the clicked segment’s dimension value. Use it as a filter. A click on the “Other” segment reports the first of the rows it adds up, so ignore that one.PieChartClickArg = { dimensionValue: string | undefined; dimensionTimeRange: TimeRange; }
componentNamestringA name for this component, included in the interaction events it dispatches on the DOM, for your analytics.
trackingIdstringAn id included in the same events, to tell two instances apart.
titlestringThe card’s title. A "key|fallback" string is looked up in your translations.
descriptionstringSmaller text under the title. Translates like title.
tooltipstringText for an info icon beside the title.
hideMenubooleanfalseHide the card’s header: the title, description and menu.
menuOptions("csv" | "xlsx" | "png" | "maximize")[]["csv", "xlsx", "png", "maximize"]Which entries the card menu offers. Pass [] for none.
innerLabelTextstringThe caption under the centre value.

A blank default means the prop is unset unless you pass it.

TypeDefinition
TimeRange{ from: Date | undefined; to: Date | undefined; relativeTimeString?: string; } | undefinedWhat a click’s TimeRange holds: Events.

Field options

Set in a field’s inputs, beside the common options:

OptionTypeSet onDescription
showValueAsPercentagebooleanmeasureLabel each value with its share of the total. The tooltip shows both. Default: false.