Guide / Controls / Charts

Timeline

Tasks laid out over time

When to use it. A project timeline: one horizontal bar per task from start to end, with an optional progress fill, milestone diamonds, and a dashed today marker when the timeline is date-based. The hidden edge: with editable: true, dragging along a bar sets that task's progress — the chart becomes a bank of per-task progress sliders that write back into the dataset and fire taskAction on release.

Type
gantt
Also titled
Gantt
Default size
3 rows × 4 columns
Symbol
chart.bar.doc.horizontal
Docs
Docs complete
Search for it as
  • schedule
  • timeline
  • project
  • tasks
  • plan
  • bars
Timeline: Sprint board (server-pushed)
Rendered by the app

Fields

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

Fields
FieldTypeDefaultWhat it does
haptichapticchoiceone of 10—

The buzz you feel on a touch

Plays this haptic on the phone when you tap or drag on the timeline.

  • noneno vibration
  • lighta small soft tap
  • mediuma medium tap
  • heavya strong thud
  • softa muted cushioned tap
  • rigida firm sharp click
  • selectionthe faint tick of picking an item
  • successthe double tap of a success
  • warninga two-pulse warning
  • errora sharp triple buzz of an error
Titlelabeltext—

The title above the chart

Shows this text as the header over the timeline; the selected task's name and percent appear beside it.

ganttConfigganttConfigobject—

All the timeline settings

Groups the options that change how the bars, axis and dragging behave; every setting inside is optional.

Colortintcolor#667eea

The main color

Colors the first task's bar and seeds the colors of the rest.

Bar roundnessganttConfig.barCornerRadiusnumber0–30 ptstep 15

How round the bar ends are

Rounds the corners of every bar; 0 is square and higher is pill-like.

Bar colorsganttConfig.colorsstring[]—

A color for each task

Cycles through these colors down the rows; a task's own color overrides it.

editableganttConfig.editableon / offfalse (off)

Let people drag progress

Dragging along a bar sets that task's progress, saves it and fires the task action when you let go.

Row heightganttConfig.rowHeightnumber12–100 ptstep 130

How tall each row is

Sets the height of every task row, so the whole chart grows or shrinks with the task count.

scrubganttConfig.scrubon / offfalse (off)

Slide to browse rows

When the chart is not editable, dragging sweeps the selected row with a haptic tick; the action still fires on tap.

Time axisganttConfig.showAxison / offtrue (on)

Show the time labels

Draws the time labels along the top of the chart when on, hides them when off.

Grid linesganttConfig.showGridon / offtrue (on)

Show the grid lines

Draws faint vertical lines at each axis label when on.

Progress fillganttConfig.showProgresson / offtrue (on)

Show how far along

Fills each bar to its progress and shows the percent readout when on.

Today lineganttConfig.showTodayon / offtrue (on)

Show a line for now

Draws a dashed line at the current time on date-based timelines; number timelines never show it.

stepganttConfig.stepnumber0–1step 0.050.05

How coarse dragging is

Rounds dragged progress to multiples of this size (0.05 is 5 percent steps), with a tick at each notch.

taskActionganttConfig.taskActionobject—

What a tap or drag sends

The action fired when a task is tapped or a progress drag ends; {{value}} carries the task as JSON.

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 faintest text and ink on the chart.

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 tasktasktapjson

the task as its name, its place in the list and its progress from 0 to 1

With Editable on it also sends when you let go after dragging a bar to set progress

Example: {"name": "Item 1", "index": 0, "progress": 0.5}

Receives

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

tasks with a name, a start and an end (dates or plain numbers, not mixed) and optional progress, color or milestone flag

the bars are redrawn on the new time axis; a milestone shows as a single point

Example: {"tasks": [{"name": "Item 1", "start": 0, "end": 3, "progress": 0.5}]}

Sample

The placeholder value the editor shows before real data arrives.

  • {"tasks": [{"name": "Item 1", "start": 0, "end": 3, "progress": 1}, {"name": "Item 2", "start": 2, "end": 6, "progress": 0.4}, {"name": "Item 3", "start": 5, "end": 8, "progress": 0}]} then {"tasks": [{"name": "Item 1", "start": 0, "end": 3, "progress": 1}, {"name": "Item 2", "start": 2, "end": 6, "progress": 0.8}, {"name": "Item 3", "start": 5, "end": 8, "progress": 0.2}]}

Examples

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

Sprint board (server-pushed)

Shows a timeline whose tasks are pushed by your server as a sprint_plan broadcast.

JSON 8 lines
{
  "type": "gantt",
  "id": "sprint",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Sprint 12",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "sprint_plan" }, "valuePath": "gantt" }]
}

Open in CAR-TER

Timeline: Sprint board (server-pushed)
Rendered by the app

Editable progress tracker

Lets you drag along a bar to set progress, then broadcasts the task that changed.

JSON 12 lines
{
  "type": "gantt",
  "id": "tracker",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Drag to update",
  "ganttConfig": {
    "editable": true,
    "taskAction": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "task_progress", "task": "{{value}}" } }
  },
  "defaultValue": "[{\"name\":\"Prep\",\"start\":0,\"end\":3,\"progress\":0.5},{\"name\":\"Run\",\"start\":2,\"end\":8,\"progress\":0.1}]"
}

Open in CAR-TER

Timeline: Editable progress tracker
Rendered by the app

Quiet timeline with milestones

Draws a compact, colored plan with no grid or axis fill, using the built-in task list.

JSON 16 lines
{
  "type": "gantt",
  "id": "launch-plan",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Launch plan",
  "tint": "#34C759",
  "ganttConfig": {
    "showGrid": false,
    "showToday": false,
    "rowHeight": 36,
    "barCornerRadius": 12,
    "colors": ["#34C759", "#FF9500", "#5AC8FA"]
  },
  "defaultValue": "{\"tasks\":[{\"name\":\"Draft\",\"start\":\"2026-07-01\",\"end\":\"2026-07-06\",\"progress\":1},{\"name\":\"Review\",\"start\":\"2026-07-05\",\"end\":\"2026-07-10\",\"progress\":0.3},{\"name\":\"Launch\",\"start\":\"2026-07-12\",\"milestone\":true}]}"
}

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 “Sprint board (server-pushed)” on your phone.

    carterkit demo gantt --example 'Sprint board (server-pushed)'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

Full-width: [3, 4] and up. The control sizes its own height from the task count (rowHeight × tasks), so in a flow grid no controlHeight is needed.

GanttConfig

Field Type Default Description
showAxis bool true Time labels along the top
showGrid bool true Vertical gridlines at the axis ticks
showToday bool true Dashed "now" line (date timelines only)
showProgress bool true Progress fill inside bars + % readout
rowHeight number 30 Points per task row
barCornerRadius number 5 Bar corner rounding
colors string[] built-in palette Per-task color cycle (task color wins)
taskAction ActionDefinition — Fired on tap / drag release; {{value}} = the task as JSON
editable bool false Drag along a bar to set its progress
step number 0.05 Progress snap while dragging
scrub bool false When not editable: drag sweeps the row selection with haptic ticks (the action still fires on tap)

Sync Payload Structure

A task list — natural JSON or an encoded string. A bare array is shorthand for {"tasks": …}:

{
  "tasks": [
    { "name": "Design",  "start": "2026-07-01", "end": "2026-07-05", "progress": 1.0 },
    { "name": "Build",   "start": "2026-07-04", "end": "2026-07-12", "progress": 0.4, "color": "#FF9500" },
    { "name": "Ship",    "start": "2026-07-14", "milestone": true }
  ]
}

Task Fields

Field Type Required Description
name string yes Row label in the leading gutter
start string | number yes "yyyy-MM-dd", ISO 8601 datetime, or a plain number (any unit)
end string | number yes* Same forms as start (*not needed for milestones)
progress number no 0–1 fill inside the bar
color string no Bar color (hex)
milestone bool no Draw a diamond at start instead of a bar

Dates and numbers share one axis — don't mix them in one payload.

Behavior

  • Tap a bar to select it (header shows name %); tap empty space to clear
  • Dragging (when editable) snaps to step with a selection tick per notch, updates the stored dataset on release so state readback round-trips, then fires the action with {"name", "index", "progress"}
  • Axis labels adapt to the span: hours under 2 days, day/month under ~10 months, month/year beyond
  • Milestones ignore end and can't be progress-dragged
  • Without editable, scrub: true lets a drag sweep the row selection fluidly instead

Notes

  • Keep names short — the leading gutter is ~25% of the width, capped at 110 pt
  • ~10 tasks fit comfortably; the control grows taller with more
  • Dependencies/arrows are out of scope v1 — encode ordering with dates

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