Guide / Controls / Charts

Connections

How things connect to each other

When to use it. Who talks to whom: groups as arcs around a circle, relationships as ribbons through the middle, ribbon width ∝ flow. Feed it a matrix — service-to-service traffic, team hand-offs, trade between regions. Tapping an arc spotlights that group's ribbons (the rest fade to a whisper) and fires arcAction with the group's total, so the diagram doubles as a focus picker.

Type
chord
Also titled
Chord
Default size
3 rows × 3 columns
Symbol
circle.hexagonpath.fill
Docs
Docs complete
Search for it as
  • relationships
  • connections
  • circular
  • flow
  • matrix
Connections: Service mesh traffic
Rendered by the app

Fields

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

Fields
FieldTypeDefaultWhat it does
haptichapticchoiceone of 10—

Buzz when you tap

Plays this vibration when you tap an arc, on supported phones.

  • noneno vibration
  • lighta gentle tap
  • mediuma firm tap
  • heavya strong thump
  • softa muted, cushioned tap
  • rigida sharp, hard tap
  • selectiona tiny tick like scrolling a picker
  • successa double tap for done
  • warninga sharp double tap for caution
  • errora buzzy triple tap for failure
Titlelabeltext—

The title above the chart

Shows this text as the header above the diagram, with the selected group's readout beside it.

chordConfigchordConfigobject—

All the chart settings in one place

Groups the arc, ribbon, color and action settings for the diagram; every part is optional.

Colortintcolor#667eea

The main color

Colors the first group and seeds the palette for the rest when no colors list is given.

formatValueformatValuetext—

How totals are written

Formats the group total shown in the selection readout, for example as a number or percent.

arcActionchordConfig.arcActionobject—

What happens when you tap a group

Runs this action when you tap an arc; the value sent is the group's label and total.

Arc colorschordConfig.colorsstring[]—

The colors for each group

Colors the arcs in order and repeats the list if there are more groups; colors in the data take priority.

Arc gapchordConfig.padnumber0–20 degstep 0.52.5

Gap between arcs

Leaves this many degrees of empty space between neighbouring arcs, from 0 to 20 (default 2.5).

Ribbon strengthchordConfig.ribbonOpacitynumber0–1step 0.050.4

How solid the ribbons look

Sets how opaque the ribbons are from 0 to 1 (default 0.4); ribbons of the selected group brighten.

scrubchordConfig.scrubon / offfalse (off)

Drag around the ring to focus

When on, dragging around the ring moves the spotlight from group to group with a tick at each one; tapping still runs the action.

LabelschordConfig.showLabelson / offtrue (on)

Show group names

Writes each group's name around the outside of the ring; turn off to hide them.

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
secondaryColortheme.secondaryColorcolor#FFFFFF99

Dimmed text color

Colors the group names that are dimmed while another group is spotlighted.

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 an arcarctapjson

the tapped group's label and total flow, as JSON

Dragging with scrub on only moves the spotlight; nothing sends until you tap

Example: {"label": "Sample A", "total": 3}

Receives

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

a name per group and a square grid of numbers, where row one column two is the flow from group one to group two

arcs and ribbons resize to the new flows; a new set of labels redraws the ring

Example: {"labels": ["Sample A", "Sample B"], "matrix": [[0, 3], [2, 0]]}

Sample

The placeholder value the editor shows before real data arrives.

  • {"labels": ["Sample A", "Sample B", "Sample C"], "matrix": [[0, 5, 3], [5, 0, 1], [3, 1, 0]]} then {"labels": ["Sample A", "Sample B", "Sample C"], "matrix": [[0, 2, 4], [2, 0, 3], [4, 3, 0]]}

Examples

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

Service mesh traffic

A live matrix of service calls arrives over the socket and fills the ring.

JSON 8 lines
{
  "type": "chord",
  "id": "mesh-traffic",
  "position": [0, 0],
  "span": [3, 3],
  "label": "Calls/min",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "mesh_matrix" }, "valuePath": "chord" }]
}

Open in CAR-TER

Connections: Service mesh traffic
Rendered by the app

Tap-to-focus hand-off board

Tapping a team's arc broadcasts which team to focus on.

JSON 11 lines
{
  "type": "chord",
  "id": "handoffs",
  "position": [0, 0],
  "span": [3, 3],
  "label": "Hand-offs",
  "chordConfig": {
    "arcAction": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "focus_team", "team": "{{value}}" } }
  },
  "defaultValue": "{\"labels\":[\"Design\",\"Build\",\"QA\"],\"matrix\":[[0,6,1],[2,0,5],[1,3,0]]}"
}

Open in CAR-TER

Connections: Tap-to-focus hand-off board
Rendered by the app

Dial-style relationship map

A fixed matrix with wider gaps, softer ribbons and a drag-to-scrub spotlight.

JSON 11 lines
{
  "type": "chord",
  "id": "regions",
  "position": [0, 0],
  "span": [3, 3],
  "label": "Trade",
  "tint": "#34C759",
  "haptic": "selection",
  "chordConfig": { "scrub": true, "pad": 6, "ribbonOpacity": 0.3, "showLabels": true },
  "defaultValue": "{\"labels\":[\"EU\",\"US\",\"Asia\"],\"matrix\":[[0,4,2],[4,0,3],[2,3,0]]}"
}

Open in CAR-TER

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 “Service mesh traffic” on your phone.

    carterkit demo chord --example 'Service mesh traffic'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

Square — [3, 3]. The control keeps itself round and leaves a rim gutter for labels.

ChordConfig

Field Type Default Description
showLabels bool true Group names around the rim
pad number 2.5 Degrees of breathing room between arcs
ribbonOpacity number 0.4 Ribbon opacity (selection brightens involved ribbons)
colors string[] built-in palette Group color cycle (payload colors wins)
arcAction ActionDefinition — Fired on arc tap; {{value}} = {"label", "total"}
scrub bool false Drag around the ring sweeps the spotlight arc-to-arc like a dial, with haptic ticks (the action still fires on tap)

Sync Payload Structure

Labels plus a square matrix — matrix[i][j] is the flow from group i to group j. A symmetric matrix reads as undirected relationship strength:

{
  "labels": ["API", "Web", "DB", "Cache"],
  "colors": ["#667eea", "#34C759", "#FF9500", "#BF5AF2"],
  "matrix": [
    [0, 5, 3, 2],
    [5, 0, 1, 0],
    [3, 1, 0, 4],
    [2, 0, 4, 0]
  ]
}

Arc size ∝ the group's row sum (pure receivers use their incoming total so they still show). Each ribbon end is sized by that direction's flow, so an asymmetric matrix tapers honestly.

Behavior

  • Arcs start at 12 o'clock and run clockwise; labels stay horizontal, anchored away from the rim
  • Tap an arc to spotlight its ribbons + fire arcAction; tap again or tap outside the ring to clear
  • scrub: true turns the ring into a dial — dragging sweeps the spotlight with a tick at every arc boundary
  • Ribbons blend a gradient between their two group colors
  • Dataset pushes animate via the control's animation profile

Notes

  • 3–8 groups read best; the rim gets crowded past that
  • Self-flows (matrix[i][i]) are ignored
  • For staged/directional flow use Value labels; for arbitrary topology use Particles

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