Linear Gauge — Chart Controls

Minimal Example

{
  "id": "budget-used",
  "type": "gauge-linear",
  "label": "Budget Used",
  "width": "full",
  "settings": {
    "min": 0,
    "max": 500000,
    "unit": "$",
    "format": "currency",
    "value": { "source": "$context", "path": "budget.spent" }
  }
}

Settings Reference

Setting	Type	Default	Description
`min`	number	0	Minimum value of the scale
`max`	number	100	Maximum value of the scale
`value`	BindingConfig \| number	—	Scalar value binding, or a static number
`direction`	`horizontal` \| `vertical`	`horizontal`	Bar orientation
`height`	string (CSS)	`"20px"`	Bar thickness (horizontal) or total height (vertical)
`showValue`	boolean	true	Show the current numeric value as a label
`showPercent`	boolean	false	Show percentage instead of raw value
`unit`	string	—	Unit suffix appended to the value label
`format`	string	—	Value format: `number`, `currency`, `percent`
`zones`	GaugeZone[]	—	Colour bands: `[{ from, to, color }]`
`thresholds`	number[]	—	Vertical marker lines at specific values (e.g. budget target)
`thresholdColor`	string	`"#ef4444"`	Colour of threshold marker lines
`barColor`	string	`"#6c8cff"`	Bar fill colour when no zones are defined
`trackColor`	string	`"#e5e7eb"`	Background track colour
`rounded`	boolean	true	Round the bar ends

Budget Tracker with Threshold

{
  "id": "budget-gauge",
  "type": "gauge-linear",
  "settings": {
    "min": 0,
    "max": 500000,
    "format": "currency",
    "showValue": true,
    "thresholds": [400000],
    "thresholdColor": "#f59e0b",
    "zones": [
      { "from": 0,      "to": 400000, "color": "#22c55e" },
      { "from": 400000, "to": 500000, "color": "#ef4444" }
    ],
    "value": { "source": "$context", "path": "budget.spent" }
  }
}

Multi-Row KPI Progress List

Combine multiple linear gauges stacked vertically for a compact KPI progress panel. Each gauge is bound to a different metric:

// Four stacked metrics — each "full" width
{
  "id": "cpu-gauge",
  "type": "gauge-linear",
  "label": "CPU Usage",
  "width": "full",
  "settings": {
    "min": 0, "max": 100, "unit": "%",
    "showPercent": true,
    "zones": [
      { "from": 0,  "to": 70, "color": "#22c55e" },
      { "from": 70, "to": 90, "color": "#f59e0b" },
      { "from": 90, "to": 100, "color": "#ef4444" }
    ],
    "value": { "source": "$context", "path": "server.cpuPercent" }
  }
},
{
  "id": "memory-gauge",
  "type": "gauge-linear",
  "label": "Memory Usage",
  "width": "full",
  "settings": {
    "min": 0, "max": 32768, "unit": "MB",
    "zones": [
      { "from": 0,     "to": 24576, "color": "#22c55e" },
      { "from": 24576, "to": 32768, "color": "#ef4444" }
    ],
    "value": { "source": "$context", "path": "server.memoryMb" }
  }
},
{
  "id": "disk-gauge",
  "type": "gauge-linear",
  "label": "Disk Usage",
  "width": "full",
  "settings": {
    "min": 0, "max": 100, "unit": "%",
    "barColor": "#8b5cf6",
    "value": { "source": "$context", "path": "server.diskPercent" }
  }
}

Vertical Gauge

Set direction: "vertical" for a tall bar that fills from the bottom. Useful for tank or capacity displays:

{
  "id": "queue-depth",
  "type": "gauge-linear",
  "width": "quarter",
  "settings": {
    "direction": "vertical",
    "height": "200px",
    "min": 0,
    "max": 1000,
    "showValue": true,
    "zones": [
      { "from": 0,   "to": 700,  "color": "#22c55e" },
      { "from": 700, "to": 1000, "color": "#ef4444" }
    ],
    "value": { "source": "$context", "path": "queue.depth" }
  }
}

Radial vs Linear Gauge

Scenario	Radial Gauge	Linear Gauge
Single prominent KPI	Best — large, visual impact	Acceptable
Multiple KPIs in a list	Too large	Best — compact rows
Progress toward target	Possible	Best — feels like a progress bar
Score with zones (NPS, SLA)	Best — coloured arc	Good — coloured segments
Narrow column layout	Requires square space	Best — flexible width

← Radial Gauge Next: Binding Chart Data →