Guide / Controls / Charts

Chart

Lines or bars over time

When to use it. The cartesian workhorse: bar, line, area, scatter, histogram, and waterfall series on one canvas — grouped or stacked, vertical or horizontal, straight or smoothed. Datasets push over Sync as natural JSON and every datum is tappable, so a bar chart can double as a live voting panel, a queue selector, or a preset picker. Histogram series bin raw samples client-side; waterfall series accumulate signed deltas with hand-off connectors.

Type
chart
Default size
3 rows × 4 columns
Symbol
chart.bar.xaxis
Docs
Docs complete
Search for it as
  • graph
  • plot
  • line chart
  • bar chart
  • trend
  • timeline
Chart: Live multi-series telemetry
Rendered by the app

Fields

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

Fields
FieldTypeDefaultWhat it does
haptichapticchoiceone of 10—

The tap buzz on the phone

Plays a vibration of the chosen strength when someone touches the chart on supported phones.

  • noneno vibration
  • lighta faint tap
  • mediuma clear tap
  • heavya strong thump
  • softa muffled cushioned tap
  • rigida sharp crisp tap
  • selectionthe tiny tick used for scrolling pickers
  • successa short double pulse for good news
  • warninga firm pulse for caution
  • errora harsh triple pulse for failure
Titlelabeltext—

The heading above the plot

Shows this text at the top left of the chart; the selected reading appears beside it.

chartConfigchartConfigobject—

All the look and behavior settings in one bundle

Groups the axis, series, streaming and tap options below; any entry left out uses its default.

Colortintcolor#667eea

The main color of the chart

Colors the first series and seeds the colors of the rest, as any hex color.

formatValueformatValuetext—

How numbers are written on the axis and readout

Formats the axis labels and the selection readout, for example with units or fixed decimals.

Bar roundnesschartConfig.barCornerRadiusnumber0–30 ptstep 13

How round the bar tops are

Rounds the corners of every bar from square (0) to 30 points.

Histogram binschartConfig.binsnumber1–50step 1—

How many buckets a histogram has

Splits the histogram samples into 1 to 50 bars; left unset it uses about the square root of the sample count.

Series colorschartConfig.colorsstring[]—

The colors the series take in turn

Gives series one, two, three and so on these hex colors in order; a color set on a series itself wins.

datumActionchartConfig.datumActionobject—

What happens when a bar or point is tapped

Runs this action on tap with the tapped datum as JSON in the value placeholder.

horizontalchartConfig.horizontalon / offfalse (off)

Bars lying sideways

Turns the bars to run left to right with the categories listed down the left edge.

Line widthchartConfig.lineWidthnumber0.5–12 ptstep 0.52

How thick the lines are

Sets the stroke of line and area series from 0.5 to 12 points.

GlowglowRadiusnumber0–30 ptstep 10

A soft halo around bars lines and points

Adds a glow behind the marks in their own colors, 0 (off) to 30 points wide.

Line endslineCapchoiceone of 3round

The shape of the line ends

Rounds, flattens or squares the ends of line strokes.

  • round defaultsoft half-circle ends and the default
  • buttflat ends cut exactly at the last point
  • squareflat ends that extend a little past the last point
Time windowchartConfig.maxPointsnumber10–1000step 10100

How many recent points are kept

Caps a streaming series at 10 to 1000 points so the oldest drop off as new ones are appended.

negativeColorchartConfig.negativeColorcolor—

The color of falling steps in a waterfall

Paints waterfall bars with a negative change in this color instead of system red.

Point sizechartConfig.pointSizenumber2–20step 16

How big the dots are

Sets the diameter of scatter points and line vertex dots from 2 to 20 points.

positiveColorchartConfig.positiveColorcolor—

The color of rising steps in a waterfall

Paints waterfall bars with a positive change in this color instead of system green.

scrubchartConfig.scrubon / offfalse (off)

Drag your finger along the chart to read values

When on, dragging shows a dashed crosshair and a live readout with a tick at each point instead of tap selection.

GridchartConfig.showGridon / offtrue (on)

The faint guide lines behind the plot

Shows or hides the horizontal grid lines across the plot.

LegendchartConfig.showLegendon / offfalse (off)

A key naming each series

Shows or hides a row under the plot listing every series with its color.

Value labelschartConfig.showValueson / offfalse (off)

Numbers printed on the marks

Prints each value above its bar or on its line vertex when on.

X axischartConfig.showXAxison / offtrue (on)

The labels along the bottom

Shows or hides the category labels along the bottom (down the left edge for horizontal bars).

Y axischartConfig.showYAxison / offtrue (on)

The number scale on the left

Shows or hides the value labels in the left gutter.

SmoothingchartConfig.smoothon / offfalse (off)

Curved instead of angular lines

Draws line and area series as smooth curves rather than straight segments.

stackedchartConfig.stackedon / offfalse (off)

Piling series on top of each other

Stacks bar and area series so they add up, instead of sitting side by side or overlapping.

totalColorchartConfig.totalColorcolor—

The color of the running-total bars in a waterfall

Paints waterfall total bars in this color instead of the series color.

Axis topchartConfig.yMaxnumber—

The top of the value scale

Fixes the highest value on the vertical axis instead of fitting the data.

Axis bottomchartConfig.yMinnumber—

The bottom of the value scale

Fixes the lowest value on the vertical axis instead of fitting the data.

namedata.series.nametext—

The series name

Labels the series in the legend and is the key a streamed append uses to find it.

typedata.series.typechoiceone of 6bar

What kind of marks a series draws

Draws that series as bars, a line, a filled area, dots, binned bars or a waterfall; series of different kinds share one chart.

  • bar defaultvertical bars and the default
  • linea line joining the points
  • areaa line with the space beneath it filled
  • scatterloose dots at x and y positions
  • histogramraw samples grouped into frequency bars
  • waterfallbars that step up and down from a running level
colordata.series.colorcolor—

The color of one series

Paints that series in this hex color, overriding the color list.

valuesdata.series.valuesnumber[]—

The numbers to plot

Gives the height at each position in order lined up with the categories; null leaves a gap.

pointsdata.series.pointslist—

Exact x and y positions

Places each mark at its own x and y pair, for scatter or unevenly spaced data.

sizesdata.series.sizesnumber[]—

Dot sizes for a bubble plot

Scales each scatter dot by the matching multiplier, so 2 draws twice the normal size.

totalsdata.series.totalsnumber[]—

Which waterfall steps are totals

Draws the bars at these positions as running totals from zero instead of changes.

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 bar or pointdatumtapjson

the tapped bar or point, as JSON with its series, category, index and numbers

Example: {"index": 1, "y": 3, "series": "Series 1", "category": "Item 2"}

Receives

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

series: a list of numbers (or x and y points) each, with optional category names

the lines and bars redraw to the new numbers; a missing number leaves a gap

Example: {"categories": ["Item 1", "Item 2", "Item 3"], "series": [{"name": "Series 1", "values": [1, 3, 2]}]}

Sample

The placeholder value the editor shows before real data arrives.

  • {"categories": ["Item 1", "Item 2", "Item 3"], "series": [{"name": "Series 1", "values": [1, 3, 2]}]} then {"categories": ["Item 1", "Item 2", "Item 3"], "series": [{"name": "Series 1", "values": [3, 1, 2]}]}

Examples

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

Live multi-series telemetry

JSON 10 lines
{
  "type": "chart",
  "id": "cpu-chart",
  "position": [0, 0],
  "span": [3, 4],
  "label": "CPU / GPU",
  "chartConfig": { "showLegend": true, "smooth": true, "maxPoints": 60 },
  "defaultValue": "{\"series\":[{\"name\":\"CPU\",\"type\":\"area\",\"values\":[42,51,38,64,55]},{\"name\":\"GPU\",\"type\":\"line\",\"values\":[20,34,28,41,36]}]}",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "telemetry" }, "valuePath": "chart" }]
}

Open in CAR-TER

Chart: Live multi-series telemetry
Rendered by the app

Tappable bar chart (voting panel)

JSON 14 lines
{
  "type": "chart",
  "id": "poll",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Vote for lunch",
  "chartConfig": {
    "showValues": true,
    "barCornerRadius": 6,
    "datumAction": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "vote", "choice": "{{value}}" } }
  },
  "defaultValue": "{\"categories\":[\"Pizza\",\"Sushi\",\"Tacos\"],\"series\":[{\"values\":[3,5,2]}]}",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "poll_update" }, "valuePath": "results" }]
}

Open in CAR-TER

Chart: Tappable bar chart (voting panel)
Rendered by the app

Static horizontal bars

JSON 9 lines
{
  "type": "chart",
  "id": "storage",
  "position": [0, 0],
  "span": [2, 4],
  "label": "Storage by volume",
  "chartConfig": { "horizontal": true, "showValues": true, "showGrid": false },
  "defaultValue": "{\"categories\":[\"System\",\"Media\",\"Docs\"],\"series\":[{\"values\":[128,412,64]}]}"
}

Open in CAR-TER

Each example below shows one capability and the effect to expect on the phone.

Chart: Static horizontal bars
Rendered by the app

Stacked areas, smoothed

Demonstrates stacked, smooth and colors: two area series pile into one curved band, tinted from the color list.

JSON 9 lines
{
  "type": "chart",
  "id": "traffic",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Traffic",
  "chartConfig": { "stacked": true, "smooth": true, "colors": ["#667eea", "#f6ad55"], "showLegend": true },
  "defaultValue": "{\"categories\":[\"Mon\",\"Tue\",\"Wed\"],\"series\":[{\"name\":\"Web\",\"type\":\"area\",\"values\":[10,14,12]},{\"name\":\"API\",\"type\":\"area\",\"values\":[5,8,9]}]}"
}

Open in CAR-TER

Chart: Stacked areas, smoothed
Rendered by the app

Scatter with bubble sizes

Demonstrates points, sizes and pointSize: loose dots at exact x and y positions, the larger multipliers drawing bigger bubbles.

JSON 9 lines
{
  "type": "chart",
  "id": "bubbles",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Latency vs load",
  "chartConfig": { "pointSize": 8 },
  "defaultValue": "{\"series\":[{\"name\":\"Hosts\",\"type\":\"scatter\",\"points\":[[1,20],[2,35],[4,50]],\"sizes\":[1,2,3]}]}"
}

Open in CAR-TER

Chart: Scatter with bubble sizes
Rendered by the app

Histogram of samples

Demonstrates the histogram series and bins: raw samples are grouped into six frequency bars.

JSON 9 lines
{
  "type": "chart",
  "id": "latency-hist",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Response times",
  "chartConfig": { "bins": 6 },
  "defaultValue": "{\"series\":[{\"type\":\"histogram\",\"values\":[42.1,38.9,44.6,51.2,40.3,43.8,47.5]}]}"
}

Open in CAR-TER

Chart: Histogram of samples
Rendered by the app

Waterfall

Demonstrates waterfall, totals, positiveColor, negativeColor and totalColor: green rises, red falls, and the first and last bars are totals.

JSON 9 lines
{
  "type": "chart",
  "id": "cashflow",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Cash flow",
  "chartConfig": { "positiveColor": "#48bb78", "negativeColor": "#f56565", "totalColor": "#667eea", "showValues": true },
  "defaultValue": "{\"categories\":[\"Start\",\"Sales\",\"Refunds\",\"Costs\",\"Net\"],\"series\":[{\"type\":\"waterfall\",\"values\":[1200,480,-160,-390,0],\"totals\":[0,4]}]}"
}

Open in CAR-TER

Chart: Waterfall
Rendered by the app

Scrub crosshair with pinned axis

Demonstrates scrub, yMin, yMax and formatValue: dragging shows a dashed crosshair with a live readout, on a value axis fixed from 0 to 100.

JSON 11 lines
{
  "type": "chart",
  "id": "battery-trend",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Battery",
  "haptic": "selection",
  "formatValue": "%.0f%%",
  "chartConfig": { "scrub": true, "yMin": 0, "yMax": 100, "showGrid": false },
  "defaultValue": "{\"series\":[{\"type\":\"line\",\"values\":[92,88,80,71,65,52]}]}"
}

Open in CAR-TER

Chart: Scrub crosshair with pinned axis
Rendered by the app

Streaming append

Demonstrates maxPoints and the append push: each tick adds a reading, and the oldest drop off past 30 points. The payload below is what the server pushes over Sync.

JSON 10 lines
{
  "type": "chart",
  "id": "live-cpu",
  "position": [0, 0],
  "span": [3, 4],
  "label": "CPU live",
  "chartConfig": { "maxPoints": 30, "smooth": true },
  "defaultValue": "{\"series\":[{\"name\":\"CPU\",\"type\":\"line\",\"values\":[40,44]}]}",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "cpu_tick" }, "valuePath": "append" }]
}

Open in CAR-TER

Chart: Streaming append
Rendered by the app

Glow, line ends and thick lines

Demonstrates glowRadius, lineCap, lineWidth and tint: a thick glowing line with flat ends.

JSON 12 lines
{
  "type": "chart",
  "id": "neon",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Neon trend",
  "tint": "#00e5ff",
  "glowRadius": 10,
  "lineCap": "butt",
  "chartConfig": { "lineWidth": 4, "showGrid": false },
  "defaultValue": "{\"series\":[{\"type\":\"line\",\"values\":[3,7,4,9,6]}]}"
}

Open in CAR-TER

Chart: Glow, line ends and thick lines
Rendered by the app

Themed chart

Demonstrates the theme fields: a squarer card with a heavier border, tinted background and softer axis text.

JSON 9 lines
{
  "type": "chart",
  "id": "themed-chart",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Themed",
  "theme": { "cornerRadius": 4, "borderWidth": 2, "borderColor": "#667eea", "surfacePrimary": "#667eea22", "secondaryColor": "#A0AEC0", "labelFontSize": 14 },
  "defaultValue": "{\"categories\":[\"A\",\"B\",\"C\"],\"series\":[{\"values\":[4,6,5]}]}"
}

Open in CAR-TER

The chart has no look variants that change its type and no long-press detail; a tap or scrub drag is its only interaction (see the voting example above for datumAction).

Chart: Themed chart
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 “Live multi-series telemetry” on your phone.

    carterkit demo chart --example 'Live multi-series telemetry'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

Plots read best wide: [3, 4] or larger. In a flow grid the chart auto-sizes to a 16:10 landscape cell.

ChartConfig

All fields optional with sensible defaults.

Axes & Chrome

Field Type Default Description
showXAxis bool true Category/x labels along the bottom (leading edge when horizontal)
showYAxis bool true Value labels down the left gutter
showGrid bool true Horizontal grid lines
showLegend bool false Series legend under the plot
showValues bool false Numeric value above each bar / on each vertex
yMin / yMax number data range Pin the value axis (bars baseline at 0 by default)

Series Presentation

Field Type Default Description
stacked bool false Stack bar/area series instead of grouping/overlaying
horizontal bool false Horizontal bars — categories run down the leading edge
smooth bool false Catmull-Rom curve smoothing for line/area series
barCornerRadius number 3 Bar corner rounding
lineWidth number 2 Line/area stroke width
pointSize number 6 Scatter point / vertex dot diameter
colors string[] built-in palette Series color cycle (per-series color wins)

Streaming

Field Type Default Description
maxPoints number 100 Rolling window applied to {"append": …} pushes

Statistical Series

Field Type Default Description
bins number √n (5–20) Bin count for histogram series
positiveColor string system green Rising waterfall delta
negativeColor string system red Falling waterfall delta
totalColor string series color Waterfall running-total bars

Interaction

Field Type Default Description
datumAction ActionDefinition — Fired when a bar/point is tapped; {{value}} = the datum as JSON {"series", "category", "index", "x", "y"}
scrub bool false Drag shows a dashed crosshair + live readout (with a selection tick)

If datumAction is omitted, a tap falls back to the control's own action.

Sync Payload Structure

The chart receives its dataset via Sync. The payload can be a natural JSON object (no string-encoding needed) or an encoded string — both work:

{
  "categories": ["Mon", "Tue", "Wed", "Thu", "Fri"],
  "series": [
    { "name": "CPU", "type": "line", "color": "#667eea", "values": [42, 51, 38, 66, 47] },
    { "name": "Jobs", "type": "bar", "values": [4, 7, 2, 9, 5] }
  ]
}

Shorthands: {"values": [1, 2, 3]} or a bare [1, 2, 3] render one anonymous series.

Series Fields

Field Type Required Description
name string no Legend name + append routing key
type string no bar (default), line, area, scatter, histogram, waterfall — mix the cartesian four freely
color string no Series color (hex)
values number[] no* Y values at implicit x = 0, 1, 2, … (aligned with categories); a null is a gap (no bar or point; a line bridges it). For histogram: the raw samples to bin. For waterfall: the signed deltas
points [x, y][] no* Explicit pairs for scatter / unevenly sampled series
sizes number[] no Per-point size multipliers (bubble scatter)
totals number[] no Waterfall only: indices drawn as running totals from zero (their value is ignored)

*One of values or points per series.

Histogram & Waterfall

{ "series": [ { "type": "histogram", "values": [42.1, 38.9, 44.6, 51.2, 40.3] } ] }

The chart bins the samples (chartConfig.bins, default √n) into contiguous bars; tap payloads carry {"binStart", "binEnd", "count"}.

{ "categories": ["Start", "Sales", "Refunds", "Costs", "Net"],
  "series": [ { "type": "waterfall", "values": [1200, 480, -160, -390, 0], "totals": [0, 4] } ] }

Deltas step from each running level with dashed connectors; totals indices render as full bars from zero — with value 0 they checkpoint the running level (a "Net" bar), with a nonzero value they anchor it (an opening balance, as with Start above). Tap payloads carry {"delta"|"total", "level"}. Both are single-series statisticals — give each its own chart rather than mixing them with other series types.

Streaming Append

Servers streaming one reading per tick don't resend history — push an append op and the device merges it into the stored dataset, trimmed to maxPoints:

{ "append": { "CPU": 63.2, "GPU": 41.0 }, "category": "12:05" }

Forms: {"CPU": 63.2} (per-series by name — unknown names create new series), [63.2, 41.0] (positional), or a bare number (first series). The optional category string appends an x label alongside.

Behavior

  • Dataset changes animate smoothly (bars grow, lines morph) via the control's animation profile
  • Tap near a datum to select it: bars highlight the whole column, points ring; the header shows the reading
  • scrub: true swaps tap-selection for a drag crosshair with haptic ticks per datum
  • Append pushes ride the same coalesced sync path as sparklines — high-rate streams stay smooth

Notes

  • The control's value is the dataset JSON — selection never overwrites it, so state readback round-trips
  • For quartile/density views of a distribution use Whiskers; the histogram series here shows binned frequency shape
  • For a single fast-scrolling series, Title is lighter

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