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
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
Field
Type
Default
What it does
haptichaptic
choiceone 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
Titlelabel
text
—
The heading above the plot
Shows this text at the top left of the chart; the selected reading appears beside it.
chartConfigchartConfig
object
—
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.
Colortint
color
#667eea
The main color of the chart
Colors the first series and seeds the colors of the rest, as any hex color.
formatValueformatValue
text
—
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.barCornerRadius
number0–30 ptstep 1
3
How round the bar tops are
Rounds the corners of every bar from square (0) to 30 points.
Histogram binschartConfig.bins
number1–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.colors
string[]
—
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.datumAction
object
—
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.horizontal
on / off
false(off)
Bars lying sideways
Turns the bars to run left to right with the categories listed down the left edge.
Line widthchartConfig.lineWidth
number0.5–12 ptstep 0.5
2
How thick the lines are
Sets the stroke of line and area series from 0.5 to 12 points.
GlowglowRadius
number0–30 ptstep 1
0
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 endslineCap
choiceone of 3
round
The shape of the line ends
Rounds, flattens or squares the ends of line strokes.
rounddefaultsoft 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.maxPoints
number10–1000step 10
100
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.negativeColor
color
—
The color of falling steps in a waterfall
Paints waterfall bars with a negative change in this color instead of system red.
Point sizechartConfig.pointSize
number2–20step 1
6
How big the dots are
Sets the diameter of scatter points and line vertex dots from 2 to 20 points.
positiveColorchartConfig.positiveColor
color
—
The color of rising steps in a waterfall
Paints waterfall bars with a positive change in this color instead of system green.
scrubchartConfig.scrub
on / off
false(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.showGrid
on / off
true(on)
The faint guide lines behind the plot
Shows or hides the horizontal grid lines across the plot.
LegendchartConfig.showLegend
on / off
false(off)
A key naming each series
Shows or hides a row under the plot listing every series with its color.
Value labelschartConfig.showValues
on / off
false(off)
Numbers printed on the marks
Prints each value above its bar or on its line vertex when on.
X axischartConfig.showXAxis
on / off
true(on)
The labels along the bottom
Shows or hides the category labels along the bottom (down the left edge for horizontal bars).
Y axischartConfig.showYAxis
on / off
true(on)
The number scale on the left
Shows or hides the value labels in the left gutter.
SmoothingchartConfig.smooth
on / off
false(off)
Curved instead of angular lines
Draws line and area series as smooth curves rather than straight segments.
stackedchartConfig.stacked
on / off
false(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.totalColor
color
—
The color of the running-total bars in a waterfall
Paints waterfall total bars in this color instead of the series color.
Axis topchartConfig.yMax
number
—
The top of the value scale
Fixes the highest value on the vertical axis instead of fitting the data.
Axis bottomchartConfig.yMin
number
—
The bottom of the value scale
Fixes the lowest value on the vertical axis instead of fitting the data.
namedata.series.name
text
—
The series name
Labels the series in the legend and is the key a streamed append uses to find it.
typedata.series.type
choiceone of 6
bar
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.
bardefaultvertical 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.color
color
—
The color of one series
Paints that series in this hex color, overriding the color list.
valuesdata.series.values
number[]
—
The numbers to plot
Gives the height at each position in order lined up with the categories; null leaves a gap.
pointsdata.series.points
list
—
Exact x and y positions
Places each mark at its own x and y pair, for scatter or unevenly spaced data.
sizesdata.series.sizes
number[]
—
Dot sizes for a bubble plot
Scales each scatter dot by the matching multiplier, so 2 draws twice the normal size.
totalsdata.series.totals
number[]
—
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
Sends
When
Type
What it sends
When you tap a bar or pointdatum
tap
json
the tapped bar or point, as JSON with its series, category, index and numbers
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.
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).
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.
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)
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:
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