Fields 23 fields you can set on a pieChart control. Every control also takes the shared fields (id, position, span, sync, action).
Fields Field Type Default What it does haptic hapticchoice one 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.
none no buzz light a faint tick medium a normal tap heavy a firm thump soft a muffled cushioned bump rigid a crisp hard click selection a tiny click like scrolling a picker success a short double-tap for done warning a sharper alert buzz error a harsh triple buzz for failure Title labeltext — The name shown under the chart
Writes this text under the chart in the title size; empty shows no title.
Shape pieStylechoice one of 4 pieWhich 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 default a solid chart with no hole donut a ring with a hole and a center readout wheel a wheel you flick to spin and pick a winner menu equal slices that each act as a button Glow glowRadiusnumber 0–30 pt step 1 0A 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.
pieConfig pieConfigobject — 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.
Color tintcolor #667eeaThe main slice color
Colors the first slice and seeds the palette used for the other slices when no colors are listed.
formatValue formatValuetext — How numbers are written
Reformats the numbers shown on slices and in the center, for example as a currency or a rounded figure.
centerText pieConfig.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 colors pieConfig.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 size pieConfig.donutRationumber 0–0.85 step 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 gap pieConfig.sliceGapnumber 0–12 pt step 1 0Space between slices
Leaves an even gap of this many points between neighbouring slices, from 0 to 12.
Slice corners pieConfig.sliceCornerRadiusnumber 0–16 pt step 1 0How round the slice corners are
Rounds the outer and inner corners of every slice by up to 16 points; tiny slices get less.
explodeSelected pieConfig.explodeSelectedon / off — Whether a tapped slice pops out
On, the tapped slice slides outward from the center; off, it only highlights.
Percent pieConfig.percenton / off false (off) Numbers as shares of the whole
On, slice values read as a percentage of the total instead of raw numbers.
Labels pieConfig.showLabelson / off — Names written on the slices
On, each slice shows its label; slices under about 4 percent of the circle hide theirs.
Legend pieConfig.showLegendon / off false (off) A key of the slices under the chart
On, adds a wrapping row of colored dots with slice names below the chart.
Value labels pieConfig.showValueson / off false (off) Numbers next to the slice names
On, each slice label also shows that slice's value.
sliceAction pieConfig.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.
spinDuration pieConfig.spinDurationnumber 0.1–10 step 0.1 4How 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.
spinTicks pieConfig.spinTickson / off true (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 angle pieConfig.startAnglenumber 0–360 step 1 0Where the first slice begins
Rotates the whole chart so the first slice starts at this many degrees clockwise from the top, 0 to 360.
icon icontext — The symbol in the middle of the wheel
Draws this SF Symbol in the wheel or menu hub until a result lands.
hideValue hideValueon / off false (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 Field Type Default What it does surfacePrimary theme.surfacePrimarycolor #FFFFFF0FThe card's fill color
Fills the card behind the chart; it is also the hairline color between slices.
secondaryColor theme.secondaryColorcolor #FFFFFF99Space 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 Sends When Type What it sends When you tap a slice slicetap string 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 Takes From Type What it does slices showhub, mqtt, http, store, default json 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.
JSON 10 lines Copy {
"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 ↗
Rendered by the app Light Dark JSON 13 lines Copy {
"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 ↗
Rendered by the app Light Dark JSON 13 lines Copy {
"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 ↗
Rendered by the app Light Dark 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 Copy {
"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 ↗
Rendered by the app Light Dark 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 Copy {
"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 ↗
Rendered by the app Light Dark 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 Copy {
"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 ↗
Rendered by the app Light Dark 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.
Install the Python kit.
Copy pip install carterkit Show “Donut with live total” on your phone.
Copy carterkit demo pieChart --example 'Donut with live total' 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.
Recommended Size
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 .