PlPieChart

Parts of a whole, at a glance. The narrowest chart in the library and the easiest one to misuse. A pie is right for exactly one question: is one of these most of it?

React

import { PlPieChart } from 'plass-ui';

<PlPieChart data={traffic} categories={sources} />;

import 'package:plass_ui/plass_ui.dart';

PlPieChart(data: traffic, categories: sources);

An angle is a poor thing to compare. Two slices within a few percent of each other are indistinguishable, and a reader cannot rank six of them. Anything finer than "is one of these most of it", and anything past six slices, is a bar chart.

Props

Prop	Type	Default	Description
data *	readonly PlassChartDatum[]	—	The slices. One list of them rather than a list of series
categories	readonly PlassChartCategory[]	—	What each slice is called
shape	'pie' | 'donut' | 'semi'	'pie'	A filled disc, a ring with the middle open, or half a ring opened along the bottom
startAngle	number	0	Where the first slice starts, in degrees clockwise from twelve. Ignored by semi
center	ReactNode	—	What goes in the hole — the one figure the ring was drawn around
valueLabels	'none' | 'all'	'none'	Writes each slice's share on it — the share and not the value. A label that does not fit is dropped
legend	PlassChartLegend	—	The legend
tooltip	PlassChartTooltip	—	The tooltip
height	number | string	—	How tall the drawing is
format	Intl.NumberFormatOptions	—	How a value is written
label	string	'Chart'	What the whole drawing is called
empty	ReactNode	—	What is drawn when there is nothing to draw
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Type scale and plot height

Prop	Type	Default	Description
data *	List<PlassChartDatum>	—	The slices. One list of them rather than a list of series
categories	List<PlassChartCategory>?	—	What each slice is called
shape	PlPieShape	PlPieShape.pie	A filled disc, a ring with the middle open, or half a ring opened along the bottom
startAngle	double	0	Where the first slice starts, in degrees clockwise from twelve. Ignored by semi
center	Widget?	—	What goes in the hole — the one figure the ring was drawn around
valueLabels	PlPieLabels	PlPieLabels.none	Writes each share on its slice. A two-member enum: last and extremes have nothing to mean on a pie
legend	PlChartLegend	PlChartLegend()	The legend
tooltip	PlChartTooltip	PlChartTooltip()	The tooltip
height	double?	—	How tall the drawing is
format	String Function(double)?	—	How a value is written
semanticLabel	String?	'Chart'	What the whole drawing is called
empty	Widget?	—	What is drawn when there is nothing to draw
sizeshared	PlassSize	PlassSize.md	Type scale and plot height

The data is one list of slices rather than a list of series, because that is what a pie is: the slices are the entities here. Each one takes a palette slot of its own, the legend lists them, and the colour follows the slice rather than its size, so a chart that is refiltered or resorted keeps every category the colour it had.

A null and a zero are both left undrawn. Neither has an angle, and a slice of no width is a slice a reader cannot point at.

What the shared props mean across the library is in prop conventions.

Examples

shape

React

import { PlPieChart } from 'plass-ui';

const spend = [46, 31, 23];

const teams = ['Engineering', 'Marketing', 'Support'];

export default function PieChartShape() {
  return (
    <div className="grid w-full gap-6 sm:grid-cols-3">
      {(['pie', 'donut', 'semi'] as const).map((shape) => (
        <PlPieChart
          key={shape}
          data={spend}
          categories={teams}
          shape={shape}
          height={160}
          label={`Spend, ${shape}`}
          legend={false}
        />
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

const List<PlassChartDatum> _spend = <PlassChartDatum>[
  PlassChartDatum(46),
  PlassChartDatum(31),
  PlassChartDatum(23),
];

const List<PlassChartCategory> _teams = <PlassChartCategory>[
  PlassChartCategory.text('Engineering'),
  PlassChartCategory.text('Marketing'),
  PlassChartCategory.text('Support'),
];

class PieChartShape extends StatelessWidget {
  const PieChartShape({super.key});

  @override
  Widget build(BuildContext context) {
    return Row(
      children: <Widget>[
        for (final PlPieShape shape in PlPieShape.values)
          Expanded(
            child: Padding(
              padding: const EdgeInsets.symmetric(horizontal: 6),
              child: PlPieChart(
                data: _spend,
                categories: _teams,
                shape: shape,
                height: 160,
                legend: const PlChartLegend(hidden: true),
                semanticLabel: 'Spend, ${shape.name}',
              ),
            ),
          ),
      ],
    );
  }
}

semi takes the whole height as its radius rather than half of it, because it only draws the top half. Its centre then sits below the middle of the box by half a radius, which puts the arc itself in the middle of the tile.

center

React

import { PlPieChart } from 'plass-ui';

const plans = [1840, 620, 210];

const tiers = ['Starter', 'Team', 'Enterprise'];

export default function PieChartCenter() {
  return (
    <PlPieChart
      className="w-full"
      data={plans}
      categories={tiers}
      shape="donut"
      label="Accounts by plan"
      center={
        <>
          <span className="text-2xl font-semibold text-(--plass-fg)">2,670</span>
          <span className="text-xs text-(--plass-muted-fg)">accounts</span>
        </>
      }
    />
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

const List<PlassChartDatum> _plans = <PlassChartDatum>[
  PlassChartDatum(1840),
  PlassChartDatum(620),
  PlassChartDatum(210),
];

const List<PlassChartCategory> _tiers = <PlassChartCategory>[
  PlassChartCategory.text('Starter'),
  PlassChartCategory.text('Team'),
  PlassChartCategory.text('Enterprise'),
];

class PieChartCenter extends StatelessWidget {
  const PieChartCenter({super.key});

  @override
  Widget build(BuildContext context) {
    final tokens = PlassTheme.of(context);

    return PlPieChart(
      data: _plans,
      categories: _tiers,
      shape: PlPieShape.donut,
      semanticLabel: 'Accounts by plan',
      center: Column(
        mainAxisSize: MainAxisSize.min,
        children: <Widget>[
          Text(
            '2,670',
            style: TextStyle(fontSize: 24, fontWeight: FontWeight.w600, color: tokens.fg),
          ),
          Text('accounts', style: TextStyle(fontSize: 12, color: tokens.mutedFg)),
        ],
      ),
    );
  }
}

A donut with nothing in the middle is a pie with a bite out of it. The total, or the one figure the chart is about, is what the ring was drawn around. It is ignored on a pie, which has no hole to put it in.

valueLabels

React

import { PlPieChart } from 'plass-ui';

const devices = [58, 34, 8];

const kinds = ['Mobile', 'Desktop', 'Tablet'];

export default function PieChartValueLabels() {
  return (
    <PlPieChart
      className="w-full"
      data={devices}
      categories={kinds}
      shape="donut"
      valueLabels="all"
      label="Sessions by device"
    />
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

const List<PlassChartDatum> _devices = <PlassChartDatum>[
  PlassChartDatum(58),
  PlassChartDatum(34),
  PlassChartDatum(8),
];

const List<PlassChartCategory> _kinds = <PlassChartCategory>[
  PlassChartCategory.text('Mobile'),
  PlassChartCategory.text('Desktop'),
  PlassChartCategory.text('Tablet'),
];

class PieChartValueLabels extends StatelessWidget {
  const PieChartValueLabels({super.key});

  @override
  Widget build(BuildContext context) {
    return const PlPieChart(
      data: _devices,
      categories: _kinds,
      shape: PlPieShape.donut,
      valueLabels: PlPieLabels.all,
      semanticLabel: 'Sessions by device',
    );
  }
}

The number written on a slice is its share, not its value: a share is what a pie is a picture of, and the value is one hover away. A label wider than the slice it belongs to is dropped rather than clipped, so it can never end up sitting over the neighbour it would then be labelling.

startAngle

Where the first slice starts, in degrees clockwise from twelve o'clock. semi ignores it, that shape is defined by where it opens.

Accessibility

• The drawing carries the chart's name, and the reading a sighted reader takes from the angles is handed over as text: every visible slice, its value and its share.
• On React the picture is a role="img" and a tab stop, and the arrow keys walk the slices. What each one is worth is announced in a live region as the focus moves.
• On React the same numbers are also written into a table under the chart, clipped from view but never hidden from the accessibility tree.
• The legend is real buttons. Pressing one takes its slice out of the ring and shares the angle out again among the rest.
• Colour is never the only channel: every slice is named in the legend, in the readout and in the table.