Guide / Controls / Charts

Network

Dots joined by lines

When to use it. An Obsidian-style force-directed graph visualization. Displays nodes and edges with physics simulation, glow effects, and interactive pan/zoom/drag. Read-only (display), optionally interactive.

Type
graph
Also titled
Graph
Default size
4 rows × 4 columns
Symbol
circle.grid.cross.fill
Docs
Docs complete
Search for it as
  • network
  • nodes
  • edges
  • diagram
  • relationships
  • links
Network: Full configuration
Rendered by the app

Fields

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

Fields
FieldTypeDefaultWhat it does
Titlelabeltext—

The name shown above the graph

Shows this text as the header above the graph in the label font size (8-24 pt).

graphConfiggraphConfigobject—

All the graph's look and behavior in one bundle

Holds every graph setting below; any setting left out uses its default.

Colortintcolor#667eea

The standby color for the dots

Colors the nodes with this hex color when graphConfig sets no node color.

attractionForcegraphConfig.attractionForcenumber0.01

How tightly linked dots hug each other

Pulls connected nodes closer together; 0.01 is gentle and larger values draw linked dots into tight clusters.

BackgroundgraphConfig.backgroundColorcolor—

The backdrop behind the network

Fills the graph canvas with this hex color; the default is a near-black navy.

centerForcegraphConfig.centerForcenumber0.02

How strongly the network gathers in the middle

Pulls every node toward the canvas center; 0.02 keeps it loose and larger values squeeze the cloud into the middle.

contentEventgraphConfig.contentEventtext—

Not used yet

Reserved for a future content-push feature, so setting it changes nothing on screen.

dampinggraphConfig.dampingnumber0–1step 0.050.9

How quickly the dots stop moving

Scales motion each tick from 0 to 1; lower values add friction so the dots stop sooner.

draggablegraphConfig.draggableon / offtrue (on)

Whether a dot can be pulled around

On lets a finger drag a single node and the rest follow; off keeps every dot where physics puts it.

Line colorgraphConfig.edgeColorcolor—

The color of the connecting lines

Colors every line between nodes with this hex color unless an edge sets its own.

Curved linesgraphConfig.edgeCurvedon / offfalse (off)

Straight or bowed connections

On bends each line into a gentle curve; off draws straight lines.

Line fadegraphConfig.edgeOpacitynumber0–1step 0.050.4

How faint the lines are

Sets line opacity from 0 (invisible) to 1 (solid); the default 0.4 keeps lines soft.

Line widthgraphConfig.edgeWidthnumber0.5–12 ptstep 0.51.0

How thick the lines are

Sets the line thickness in points, 0.5 to 12; an edge can override it.

glowColorgraphConfig.glowColorcolor—

The color of the halo around dots

Tints the glow behind nodes with this hex color; it only shows while glow is on.

GlowgraphConfig.glowEnabledon / offtrue (on)

A soft halo behind each dot

On draws a blurred glow behind every node; off leaves flat dots.

GlowgraphConfig.glowRadiusnumber0–30 ptstep 16.0

How wide the halo spreads

Sets the glow blur in points, 0 to 30; larger values spread a softer, wider halo.

groupColorsgraphConfig.groupColorsobject—

A color for each kind of dot

Maps group names to hex colors so nodes whose group matches are filled with that color.

interactivegraphConfig.interactiveon / offtrue (on)

Whether you can pan and zoom

On lets a drag move the canvas and a pinch zoom it; off freezes the view.

labelColorgraphConfig.labelColorcolor—

The color of the dot names

Colors the text under each node with this hex color.

labelOffsetgraphConfig.labelOffsetnumber0–40step 112.0

How far the name sits from its dot

Moves each label this many points away from its node center, 0 to 40.

Label sizegraphConfig.labelSizenumber8–24step 110.0

How big the dot names are

Sets the node label font size in points, 8 to 24.

nodeActiongraphConfig.nodeActionobject—

What happens when you tap a dot

Runs this action when any node is tapped, with the node id available as {{value}}; a node's own onTap wins.

nodeBorderColorgraphConfig.nodeBorderColorcolor—

The color of the ring around each dot

Colors the outline drawn around nodes; it only shows when the outline width is above 0.

Node outlinegraphConfig.nodeBorderWidthnumber0–5step 0.50

A ring around each dot

Draws an outline of this thickness in points, 0 to 5; 0 means no outline.

Node colorgraphConfig.nodeColorcolor—

The default fill of the dots

Fills every node with this hex color unless its group or its own color overrides it.

nodeHighlightColorgraphConfig.nodeHighlightColorcolor—

The color of the dot you touch

Switches a node to this hex color while it is active or selected.

Node sizegraphConfig.nodeSizenumber2–40 ptstep 18.0

How big the dots are

Sets the base node radius in points, 2 to 40; a node's size multiplier scales it.

particleColorgraphConfig.particleColorcolor—

Not used yet

Reserved for the particle color, so setting it changes nothing on screen.

particleSpeedgraphConfig.particleSpeednumber—

Not used yet

Reserved for the particle speed, so setting it changes nothing on screen.

repulsionForcegraphConfig.repulsionForcenumber100

How hard the dots push each other away

Pushes every pair of nodes apart; larger values spread the network out and smaller ones pack it tight.

LabelsgraphConfig.showLabelson / offtrue (on)

Names under the dots

On writes each node's label under it; off shows bare dots.

ParticlesgraphConfig.showParticleson / offfalse (off)

Little lights traveling along the lines

On animates small particles running along the edges; off leaves the lines still.

velocityDecaygraphConfig.velocityDecaynumber0–1step 0.050.6

How fast the network settles

Sets how quickly dot speed fades, 0 to 1; lower values let the layout come to rest sooner.

zoomRangegraphConfig.zoomRangeobject—

How far you can zoom out and in

Sets the smallest and largest pinch zoom as [min, max], default [0.3, 3.0].

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 nodenodetapid

the id of the node you tapped

A node's own tap behavior wins over this action

Example: Item 1

Receives

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

nodes, each with an id and an optional label, group, color and size, and edges joining two node ids

the layout settles with the new nodes and lines; nodes that are gone fade out

Example: {"nodes": [{"id": "Item 1"}, {"id": "Item 2"}], "edges": [{"from": "Item 1", "to": "Item 2"}]}

Sample

The placeholder value the editor shows before real data arrives.

  • {"nodes": [{"id": "Item 1"}, {"id": "Item 2"}, {"id": "Item 3"}], "edges": [{"from": "Item 1", "to": "Item 2"}, {"from": "Item 1", "to": "Item 3"}]} then {"nodes": [{"id": "Item 1"}, {"id": "Item 2"}, {"id": "Item 3"}, {"id": "Item 4"}], "edges": [{"from": "Item 1", "to": "Item 2"}, {"from": "Item 1", "to": "Item 3"}, {"from": "Item 3", "to": "Item 4"}]}

Examples

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

Full configuration

Demonstrates every graphConfig group together: styled nodes, curved lines, tuned physics, zoom limits and group colors fed by live data.

JSON 39 lines
{
  "type": "graph",
  "id": "network-topology",
  "position": [0, 0],
  "span": [4, 4],
  "label": "Network Topology",
  "graphConfig": {
    "nodeColor": "#667eea",
    "nodeSize": 10,
    "nodeBorderWidth": 1.5,
    "nodeBorderColor": "#FFFFFF",
    "edgeColor": "#FFFFFF",
    "edgeWidth": 1.0,
    "edgeOpacity": 0.3,
    "edgeCurved": true,
    "showLabels": true,
    "labelColor": "#AAAAAA",
    "labelSize": 9,
    "repulsionForce": 120,
    "attractionForce": 0.015,
    "centerForce": 0.03,
    "damping": 0.85,
    "velocityDecay": 0.5,
    "interactive": true,
    "draggable": true,
    "zoomRange": [0.5, 2.5],
    "backgroundColor": "#0A0A1A",
    "glowEnabled": true,
    "glowRadius": 8,
    "glowColor": "#667eea",
    "groupColors": {
      "hub": "#FF6B6B",
      "bridge": "#FFD93D",
      "device": "#6BCB77",
      "mobile": "#4D96FF"
    }
  },
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "network_graph" }, "valuePath": "graph_data" }]
}

Open in CAR-TER

Network: Full configuration
Rendered by the app

Minimal (all defaults)

Demonstrates the defaults: glowing blue dots with labels, straight faint lines, and pan, zoom and drag, filled from live data.

JSON 8 lines
{
  "type": "graph",
  "id": "simple-graph",
  "position": [0, 0],
  "span": [4, 4],
  "label": "Connections",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "graph_update" }, "valuePath": "data" }]
}

Open in CAR-TER

Network: Minimal (all defaults)
Rendered by the app

Static graph (no sync, default value)

Demonstrates a fixed network from defaultValue with interactive off, so the view stays put and glows red.

JSON 12 lines
{
  "type": "graph",
  "id": "static-graph",
  "position": [0, 0],
  "span": [4, 4],
  "defaultValue": "{\"nodes\":[{\"id\":\"a\",\"label\":\"Hub\"},{\"id\":\"b\",\"label\":\"Light\"},{\"id\":\"c\",\"label\":\"Sensor\"}],\"edges\":[{\"from\":\"a\",\"to\":\"b\"},{\"from\":\"a\",\"to\":\"c\"}]}",
  "graphConfig": {
    "interactive": false,
    "glowEnabled": true,
    "glowColor": "#FF6B6B"
  }
}

Open in CAR-TER

Network: Static graph (no sync, default value)
Rendered by the app

Curved lines, no labels

Demonstrates edgeCurved and showLabels: connections bow into soft curves and the dots appear bare, for a decorative network.

JSON 13 lines
{
  "type": "graph",
  "id": "curved-graph",
  "position": [0, 0],
  "span": [4, 4],
  "graphConfig": {
    "edgeCurved": true,
    "showLabels": false,
    "edgeWidth": 2,
    "edgeOpacity": 0.6
  },
  "defaultValue": "{\"nodes\":[{\"id\":\"a\"},{\"id\":\"b\"},{\"id\":\"c\"}],\"edges\":[{\"from\":\"a\",\"to\":\"b\"},{\"from\":\"b\",\"to\":\"c\"},{\"from\":\"c\",\"to\":\"a\"}]}"
}

Open in CAR-TER

Network: Curved lines, no labels
Rendered by the app

Flat dots, particles and outlines

Demonstrates glowEnabled, showParticles, nodeBorderWidth and nodeHighlightColor: dots lose their halo, get a white ring, and small lights travel along the lines.

JSON 14 lines
{
  "type": "graph",
  "id": "particle-graph",
  "position": [0, 0],
  "span": [4, 4],
  "graphConfig": {
    "glowEnabled": false,
    "showParticles": true,
    "nodeBorderWidth": 2,
    "nodeBorderColor": "#FFFFFF",
    "nodeHighlightColor": "#FFD93D"
  },
  "defaultValue": "{\"nodes\":[{\"id\":\"a\",\"label\":\"A\"},{\"id\":\"b\",\"label\":\"B\"}],\"edges\":[{\"from\":\"a\",\"to\":\"b\"}]}"
}

Open in CAR-TER

Network: Flat dots, particles and outlines
Rendered by the app

Node tap action

Demonstrates nodeAction: tapping any dot sends its id to the hub as a select_device message.

JSON 17 lines
{
  "type": "graph",
  "id": "device-graph",
  "position": [0, 0],
  "span": [4, 4],
  "label": "Devices",
  "graphConfig": {
    "nodeAction": {
      "type": "action",
      "method": "meshsocket",
      "mode": "broadcast",
      "event": "route_msg_noreply",
      "payload": { "target_name": "home-hub", "type": "select_device", "payload": { "device": "{{value}}" } }
    }
  },
  "defaultValue": "{\"nodes\":[{\"id\":\"lamp\",\"label\":\"Lamp\"},{\"id\":\"fan\",\"label\":\"Fan\"}],\"edges\":[{\"from\":\"lamp\",\"to\":\"fan\"}]}"
}

Open in CAR-TER

Network: Node tap action
Rendered by the app

Group colors and physics

Demonstrates groupColors, repulsionForce, attractionForce and centerForce: nodes take their group's color and the layout spreads wide but stays centered.

JSON 13 lines
{
  "type": "graph",
  "id": "grouped-graph",
  "position": [0, 0],
  "span": [4, 4],
  "graphConfig": {
    "groupColors": { "controls": "#667eea", "models": "#FF6B6B" },
    "repulsionForce": 200,
    "attractionForce": 0.02,
    "centerForce": 0.05
  },
  "defaultValue": "{\"nodes\":[{\"id\":\"b\",\"label\":\"Button\",\"group\":\"controls\"},{\"id\":\"s\",\"label\":\"State\",\"group\":\"models\"}],\"edges\":[{\"from\":\"b\",\"to\":\"s\"}]}"
}

Open in CAR-TER

Network: Group colors and physics
Rendered by the app

Graph with long-press detail

Demonstrates longPressGroup: holding the graph opens a popup with a note about what the network shows.

JSON 18 lines
{
  "type": "graph",
  "id": "detail-graph",
  "position": [0, 0],
  "span": [4, 4],
  "label": "Network",
  "defaultValue": "{\"nodes\":[{\"id\":\"a\",\"label\":\"Hub\"},{\"id\":\"b\",\"label\":\"Light\"}],\"edges\":[{\"from\":\"a\",\"to\":\"b\"}]}",
  "longPressGroup": {
    "position": [0, 0],
    "span": [2, 1],
    "id": "graph-detail",
    "label": "About this network",
    "grid": { "columns": 2, "rows": 1 },
    "children": [
      { "type": "label", "id": "graph-note", "position": [0, 0], "span": [2, 1], "text": "Hub connects every light" }
    ]
  }
}

Open in CAR-TER

Network: Graph with long-press detail
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 “Full configuration” on your phone.

    carterkit demo graph --example 'Full configuration'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

This control is visually large. Use a span of at least [4, 4] (full width, 4 rows) for readability.

GraphConfig

All fields are optional with sensible defaults.

Node Tap Behavior

Field Type Default Description
nodeAction ActionDefinition — Default action fired when any node is tapped (node ID as {{value}})
contentEvent string — (Reserved) Event for content-push model

Node Appearance

Field Type Default Description
nodeColor string "#667eea" Default node fill color (hex)
nodeSize number 8.0 Base node radius in points
nodeHighlightColor string — Color when node is active/selected
nodeBorderWidth number 0 Border stroke width around nodes
nodeBorderColor string "#FFFFFF" Border stroke color

Edge Appearance

Field Type Default Description
edgeColor string "#FFFFFF" Default edge line color
edgeWidth number 1.0 Edge line width
edgeOpacity number 0.4 Edge line opacity (0-1)
edgeCurved bool false Use curved (quadratic) edges instead of straight

Labels

Field Type Default Description
showLabels bool true Show text labels under nodes
labelColor string "#CCCCCC" Label text color
labelSize number 10.0 Label font size
labelOffset number 12.0 Distance from node center to label

Physics Simulation

Field Type Default Description
repulsionForce number 100 How strongly nodes push apart
attractionForce number 0.01 How strongly connected nodes pull together
centerForce number 0.02 How strongly nodes are pulled toward center
damping number 0.9 Velocity dampening per tick (0-1, lower = more friction)
velocityDecay number 0.6 Velocity decay rate (0-1, lower = faster settling)

Interaction

Field Type Default Description
interactive bool true Allow pan and zoom
draggable bool true Allow dragging individual nodes
zoomRange [min, max] [0.3, 3.0] Pinch zoom limits

Visual Effects

Field Type Default Description
backgroundColor string "#0D0D1A" Graph canvas background
showParticles bool false Animated particles travelling along edges
particleColor string — (Reserved) Particle color
particleSpeed number — (Reserved) Particle animation speed
glowEnabled bool true Node glow effect
glowRadius number 6.0 Glow blur radius
glowColor string "#667eea" Glow color

Group Colors

Map group names to colors. Nodes with a matching group field use this color:

"groupColors": {
  "controls": "#667eea",
  "models": "#FF6B6B",
  "views": "#34C759",
  "services": "#FF9500"
}

Sync Payload Structure

The graph receives its data as a JSON string via Sync:

{
  "nodes": [
    { "id": "button", "label": "Button", "group": "controls", "size": 1.2 },
    { "id": "toggle", "label": "Toggle", "group": "controls" },
    { "id": "grid-renderer", "label": "GridRenderer", "group": "views", "size": 1.5 },
    { "id": "app-state", "label": "AppState", "group": "models", "color": "#FFD700", "size": 2.0 }
  ],
  "edges": [
    { "from": "grid-renderer", "to": "button" },
    { "from": "grid-renderer", "to": "toggle" },
    { "from": "app-state", "to": "grid-renderer", "width": 2.0, "color": "#FFD700" },
    { "from": "button", "to": "app-state", "label": "action" }
  ]
}

Node Fields

Field Type Required Description
id string yes Unique node identifier
label string no Display text under the node
color string no Override color for this node (hex)
size number no Size multiplier (1.0 = base size)
group string no Group name for color coding via groupColors
icon string no (Reserved) SF Symbol rendered in the node
onTap NodeTapBehavior no Per-node tap behavior (overrides graphConfig.nodeAction)

NodeTapBehavior

Each node can define what happens when tapped. Two types:

Action — fires a MeshSocket action with the node's ID:

"onTap": {
  "type": "action",
  "method": "meshsocket",
  "mode": "broadcast",
  "event": "route_msg_noreply",
  "payload": { "target_name": "home-hub", "type": "select_device", "payload": { "device": "{{value}}" } }
}

route_msg_noreply resolves the hub by its registered name and delivers a select_device frame to it. (route_msg would need the hub's live relay-assigned target_id, not a name.)

Content — requests markdown content from the server and opens it in a scrollable markdown sheet. event is sent verbatim as the frame type and the reply is awaited, so it must be route_msg (the only relay verb that carries a reply back) aimed at the server's live relay-assigned target_id; the relay delivers the inner payload to that peer as a get_doc request. A name is not resolved here, so this suits layouts a server generates after it connects:

"onTap": {
  "type": "content",
  "event": "route_msg",
  "payload": { "target_id": "<relay id>", "type": "get_doc", "payload": { "path": "controls/button.md" } }
}

The server should respond with:

{
  "title": "Button",
  "content": "# Button\n\nA tappable action trigger..."
}

Or simply a string (the raw markdown), in which case the node's label is used as the title.

Edge Fields

Field Type Required Description
from string yes Source node ID
to string yes Target node ID
color string no Override color for this edge
width number no Override width for this edge
label string no (Reserved) Text along the edge

Behavior

  • Physics simulation runs at 60fps via TimelineView
  • Nodes settle into a stable arrangement based on force parameters
  • Dragging a node pins it temporarily; releasing lets it rejoin the simulation
  • Pinch to zoom, drag canvas to pan
  • New nodes animate in from random positions; removed nodes disappear
  • Graph data can update via sync — the simulation adapts incrementally (no full reset)

Notes

  • The size field on nodes is a multiplier, not an absolute value. size: 2.0 = twice the base nodeSize
  • For dense graphs (50+ nodes), consider reducing repulsionForce and increasing damping for faster settling
  • The canvas uses Canvas (immediate mode drawing) for performance — handles hundreds of nodes smoothly
  • Fields marked (Reserved) are defined in the schema but not yet rendered

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