Guide / Controls / Charts

Pie

Parts of a whole

When to use it. One radial control, four personalities. pieStyle picks the mode:

Type
pieChart
Also titled
Pie Chart
Default size
3 rows × 3 columns
Symbol
chart.pie.fill
Docs
Docs complete
Search for it as
  • pie
  • donut
  • doughnut
  • share
  • breakdown
  • proportion
Pie: Donut with live total
Rendered by the app

Fields

23 fields you can set on a pieChart control. Every control also takes the shared fields (id, position, span, sync, action).

Fields
FieldTypeDefaultWhat it does
haptichapticchoiceone of 10—

How a touch feels

Plays the chosen buzz on the phone when a slice is tapped or a wheel lands; none stays silent.

  • noneno buzz
  • lighta faint tick
  • mediuma normal tap
  • heavya firm thump
  • softa muffled cushioned bump
  • rigida crisp hard click
  • selectiona tiny click like scrolling a picker
  • successa short double-tap for done
  • warninga sharper alert buzz
  • errora harsh triple buzz for failure
Titlelabeltext—

The name shown under the chart

Writes this text under the chart in the title size; empty shows no title.

ShapepieStylechoiceone of 4pie

Which kind of round chart it is

Switches the control between a solid pie, a ring with a hole, a spinning wheel and a radial button pad.

  • pie defaulta solid chart with no hole
  • donuta ring with a hole and a center readout
  • wheela wheel you flick to spin and pick a winner
  • menuequal slices that each act as a button
GlowglowRadiusnumber0–30 ptstep 10

A soft halo behind the slices

Adds a blurred glow in each slice's own color that reaches this many points out, from 0 (none) to 30.

pieConfigpieConfigobject—

The detailed chart settings in one bundle

Holds the options below (hole size and gaps and labels and legend and spin and actions); each one changes the chart as listed.

Colortintcolor#667eea

The main slice color

Colors the first slice and seeds the palette used for the other slices when no colors are listed.

formatValueformatValuetext—

How numbers are written

Reformats the numbers shown on slices and in the center, for example as a currency or a rounded figure.

centerTextpieConfig.centerTexttext—

Text shown in the middle of the donut

Replaces the center readout of a donut with this text; {{total}} becomes the sum of all slices.

Slice colorspieConfig.colorsstring[]—

The colors the slices take in turn

Colors slice one with the first entry, slice two with the second and so on, repeating when slices outnumber colors.

Hole sizepieConfig.donutRationumber0–0.85step 0.05—

How big the hole in the middle is

Sets the hole width as a fraction of the radius from 0 (solid) to 0.85 (thin ring); the default depends on the shape.

Slice gappieConfig.sliceGapnumber0–12 ptstep 10

Space between slices

Leaves an even gap of this many points between neighbouring slices, from 0 to 12.

Slice cornerspieConfig.sliceCornerRadiusnumber0–16 ptstep 10

How round the slice corners are

Rounds the outer and inner corners of every slice by up to 16 points; tiny slices get less.

explodeSelectedpieConfig.explodeSelectedon / off—

Whether a tapped slice pops out

On, the tapped slice slides outward from the center; off, it only highlights.

PercentpieConfig.percenton / offfalse (off)

Numbers as shares of the whole

On, slice values read as a percentage of the total instead of raw numbers.

LabelspieConfig.showLabelson / off—

Names written on the slices

On, each slice shows its label; slices under about 4 percent of the circle hide theirs.

LegendpieConfig.showLegendon / offfalse (off)

A key of the slices under the chart

On, adds a wrapping row of colored dots with slice names below the chart.

Value labelspieConfig.showValueson / offfalse (off)

Numbers next to the slice names

On, each slice label also shows that slice's value.

sliceActionpieConfig.sliceActionobject—

What happens when a slice is chosen

Runs this action on a slice tap or wheel landing, with {{value}} set to the slice label.

spinDurationpieConfig.spinDurationnumber0.1–10step 0.14

How long the wheel keeps turning

Sets roughly how many seconds a full-strength spin takes to slow to a stop, from 0.1 to 10.

spinTickspieConfig.spinTickson / offtrue (on)

The clicks while the wheel turns

On, the phone ticks each time a slice boundary passes the pointer; off, the spin is silent.

Start anglepieConfig.startAnglenumber0–360step 10

Where the first slice begins

Rotates the whole chart so the first slice starts at this many degrees clockwise from the top, 0 to 360.

iconicontext—

The symbol in the middle of the wheel

Draws this SF Symbol in the wheel or menu hub until a result lands.

hideValuehideValueon / offfalse (off)

Hides the center number

On, removes the readout from the donut center or hub; the slices still draw.

Theme fields

Restyle one control by setting these in its theme object; a layout's theme sets them for every control.

Theme fields
FieldTypeDefaultWhat it does
surfacePrimarytheme.surfacePrimarycolor#FFFFFF0F

The card's fill color

Fills the card behind the chart; it is also the hairline color between slices.

secondaryColortheme.secondaryColorcolor#FFFFFF99

Space inside the card

Colors the title and the center readout.

Emits and receives

What this control sends when you use it, and what it can show or follow when data arrives.

Emits

Emits
SendsWhenTypeWhat it sends
When you tap a sliceslicetapstring

the tapped slice's label

On a wheel it sends when the spin stops, with the label the pointer lands on; tapping or flicking a wheel only spins it

Example: Sample A

Receives

Receives
TakesFromTypeWhat it does
slicesshowhub, mqtt, http, store, defaultjson

slices: a label and a number each (a missing number counts as 1)

bigger numbers get bigger slices; new data re-slices the chart, and a wheel keeps its place

Example: {"slices": [{"label": "Sample A", "value": 3}]}

Sample

The placeholder value the editor shows before real data arrives.

  • {"slices": [{"label": "Sample A", "value": 3}, {"label": "Sample B", "value": 2}, {"label": "Sample C", "value": 1}]} then {"slices": [{"label": "Sample A", "value": 2}, {"label": "Sample B", "value": 3}, {"label": "Sample C", "value": 1}, {"label": "Sample D", "value": 1}]}

Examples

6 examples, each one a control you can paste into a layout.

Donut with live total

JSON 10 lines
{
  "type": "pieChart",
  "id": "power-split",
  "position": [0, 0],
  "span": [3, 3],
  "label": "Power draw",
  "pieStyle": "donut",
  "pieConfig": { "centerText": "{{total}}W", "showLegend": true, "percent": true },
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "power" }, "valuePath": "split" }]
}

Open in CAR-TER

Pie: Donut with live total
Rendered by the app

Spin-to-select wheel (weighted raffle)

JSON 13 lines
{
  "type": "pieChart",
  "id": "prize-wheel",
  "position": [0, 0],
  "span": [3, 3],
  "label": "Who's on call?",
  "pieStyle": "wheel",
  "pieConfig": {
    "spinDuration": 5,
    "sliceAction": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "oncall_pick", "person": "{{value}}" } }
  },
  "defaultValue": "{\"slices\":[{\"label\":\"Ava\",\"value\":1},{\"label\":\"Ben\",\"value\":1},{\"label\":\"Cass\",\"value\":2},{\"label\":\"Drew\",\"value\":1}]}"
}

Open in CAR-TER

Pie: Spin-to-select wheel (weighted raffle)
Rendered by the app

Radial command menu

JSON 13 lines
{
  "type": "pieChart",
  "id": "scene-menu",
  "position": [0, 0],
  "span": [3, 3],
  "label": "Scenes",
  "pieStyle": "menu",
  "icon": "sparkles",
  "pieConfig": {
    "sliceAction": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "scene", "name": "{{value}}" } }
  },
  "defaultValue": "{\"slices\":[{\"label\":\"Movie\",\"icon\":\"tv\"},{\"label\":\"Focus\",\"icon\":\"moon\"},{\"label\":\"Party\",\"icon\":\"music.note\"},{\"label\":\"Off\",\"icon\":\"power\"}]}"
}

Open in CAR-TER

Pie: Radial command menu
Rendered by the app

Plain pie with fixed slices

Shows a value on screen with no data source: a solid pie of three coloured shares with a legend, so the person sees parts of a whole at a glance.

JSON 10 lines
{
  "type": "pieChart",
  "id": "budget-pie",
  "position": [0, 0],
  "span": [3, 3],
  "label": "Budget",
  "pieStyle": "pie",
  "pieConfig": { "showLegend": true, "showValues": true, "startAngle": 90 },
  "defaultValue": "{\"slices\":[{\"label\":\"Rent\",\"value\":50,\"color\":\"#FF6B6B\"},{\"label\":\"Food\",\"value\":30,\"color\":\"#667eea\"},{\"label\":\"Fun\",\"value\":20}]}"
}

Open in CAR-TER

Pie: Plain pie with fixed slices
Rendered by the app

Polished donut look

Shows the look settings together: a thin ring with rounded, separated slices and a soft glow, so the chart reads as a refined ring rather than a flat disc.

JSON 11 lines
{
  "type": "pieChart",
  "id": "polished-donut",
  "position": [0, 0],
  "span": [3, 3],
  "label": "Storage",
  "pieStyle": "donut",
  "glowRadius": 10,
  "pieConfig": { "donutRatio": 0.7, "sliceGap": 4, "sliceCornerRadius": 8, "colors": ["#4ECDC4", "#FFE66D", "#FF6B6B"], "centerText": "{{total}} GB" },
  "defaultValue": "{\"slices\":[{\"label\":\"Photos\",\"value\":64},{\"label\":\"Apps\",\"value\":32},{\"label\":\"Other\",\"value\":16}]}"
}

Open in CAR-TER

Pie: Polished donut look
Rendered by the app

Tap a slice to act

Shows the tap action and haptic: tapping a slice pops it outward, buzzes lightly and broadcasts that slice's label, so a pie doubles as a filter picker.

JSON 14 lines
{
  "type": "pieChart",
  "id": "room-filter",
  "position": [0, 0],
  "span": [3, 3],
  "label": "Rooms",
  "pieStyle": "donut",
  "haptic": "light",
  "pieConfig": {
    "explodeSelected": true,
    "sliceAction": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "room_focus", "room": "{{value}}" } }
  },
  "defaultValue": "{\"slices\":[{\"label\":\"Kitchen\",\"value\":3},{\"label\":\"Den\",\"value\":2},{\"label\":\"Garage\",\"value\":1}]}"
}

Open in CAR-TER

Pie: Tap a slice to act
Rendered by the app

Try it on your phone

carterkit serves a small hub on your computer and pushes one example to CAR-TER on your iPhone or iPad. Pair once with the code it prints.

  1. Install the Python kit.

    pip install carterkit
  2. Show “Donut with live total” on your phone.

    carterkit demo pieChart --example 'Donut with live total'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

  • pie / donut — the classic part-of-whole chart, with tappable slices, an optional exploding selection, and a donut center readout.
  • wheel — a spin-to-select wheel: flick (or tap) to spin, physics wind it down with a haptic tick per slice, and the winning slice fires the action. Slice values become raffle weights, so a weighted giveaway is just data.
  • menu — a radial command pad: equal slices with icons, each slice a button. Eight actions in the footprint of one round control.

Square cells — [3, 3] minimum, larger for wheels with many slices. The control keeps itself round.

PieConfig

Field Type Default Description
donutRatio number per style Inner-radius fraction 0–0.85 (pie 0, donut 0.62, wheel 0.18, menu 0.3)
startAngle number 0 Degrees the first slice starts at (0 = 12 o'clock, clockwise)
showLegend bool false Wrapping dot-chip legend under the chart
showLabels bool true* Slice labels (auto-hidden on thin slices; *menu defaults false — icons lead)
showValues bool false Append each slice's value to its label
percent bool false Show values as % of the total
centerText string — Donut center text; {{total}} interpolates the slice sum
explodeSelected bool true** Tapped slice pops outward (**wheels default false)
colors string[] built-in palette Slice color cycle (per-slice color wins)
sliceAction ActionDefinition — Fired on slice tap and wheel landing; {{value}} = slice label
spinDuration number 4 Approximate seconds a full-strength spin takes to settle
spinTicks bool true Haptic tick per slice boundary while spinning

If sliceAction is omitted, taps/landings fall back to the control's own action.

Sync Payload Structure

{"slices": […]} or a bare array of slices — natural JSON or an encoded string:

{
  "slices": [
    { "label": "Heating", "value": 41, "color": "#FF6B6B" },
    { "label": "Compute", "value": 33, "color": "#667eea" },
    { "label": "Idle",    "value": 26 }
  ]
}

A grouped Local Store result ({"categories": […], "series": [{"values": […]}]}, what "groupBy": "genre" delivers) also reads: one slice per category, sized by its value.

Slice Fields

Field Type Required Description
label string yes Display name — also the {{value}} an action receives
value number no Share of the whole / raffle weight (default 1; menu mode ignores it)
color string no Slice color (hex)
icon string no SF Symbol drawn in the slice (menu mode leads with it)

Behavior

  • Slice datasets animate between pushes; taps highlight (and optionally explode) a slice
  • Wheel: flick to spin with your own force, or tap for a strong randomized spin; the pointer sits at 12 o'clock; each boundary crossing ticks; settling fires a success haptic + the action with the winner, and the hub shows the result
  • Menu: every slice is a button; the hub echoes the last pick
  • The wheel result is delivered via action only — the control's value stays the dataset, so a re-render never re-fires a pick

Notes

  • hideValue, centerText and donutRatio show nothing on a plain pie (no hole) or menu; they matter on donut and wheel hubs
  • spinDuration and spinTicks only change the wheel; the other shapes never spin
  • Wheel odds follow value weights — equal weights = fair spin, and the server can re-weight live between spins
  • Slices under ~4% of the circle drop their inline label; use showLegend for long tails
  • A polar/rose chart is a pie whose values map to radius — out of scope v1
  • Axis bottom — cartesian bar/line/area/scatter
  • Unit — single-value radial readout
  • Unit — single-fraction ring
  • Toggle expand — how slice/wheel actions fire
  • Sync — how slice data arrives

Generated from ControlDocs/pie-chart.md. Something unclear or missing? Tell me.