mailinapp
Documentation menu

Gauge block

A single metric plotted against good/warning/serious threshold bands you define — a needle-style dial, not a row-based chart. It exists for the "is this number okay right now" read: uptime, error rate, NPS, latency, anything with a health-status framing rather than a trend or a comparison.

How it works

The image draws a semicircular arc split into three colored bands (good, warning, serious) by two threshold breakpoints, with a needle pointing at the authored value. Unlike every sibling chart in this family, a gauge has no row-list at all — its entire "data" is five scalar numbers (a value, a min/max scale, and the two threshold breakpoints), which puts it closer in shape to the KPI scorecard's single authored value than to any category/series/point table.

That's also why gauge is the one chart block in this whole family with no data table underneath it. A data table exists to carry numbers the image locks away in pixels — but a gauge's value and status are never locked away in the first place. They render as real HTML text directly beside the image: a bold value line (formatted as a plain number, currency, or percent) followed by a colored status word ("Good," "Warning," or "Serious"), plus a small muted line repeating the value, status, and scale range beneath the image itself. That text is unconditional — it renders whether or not the image loads, the same non-negotiable accessibility contract every other chart in the family fulfills with a <table>.

Threshold bands are always the reserved status palette (green/amber/red) — never a field you can override, the same "red always means bad" trust rule the waterfall block's increase/decrease colors follow. goodMax and warningMax split the min–max scale into three ascending bands in that order (good, then warning, then anything past warningMax is serious) — the classic "speedometer" read where low is safe and high is risk, like CPU load or error rate. A metric where high is actually good (like an NPS or uptime score) just authors its thresholds the other way round — goodMax set near max — rather than needing a separate "direction" flag.

Configurable fields:

  • Label — optional heading text above the value.
  • Value — the metric itself, as text (so it can carry a merge tag).
  • Format — Number, Currency, or Percent, controlling how the value renders as text.
  • Scale minimum / Scale maximum — the min/max bounds of the dial.
  • Good zone up to — the goodMax breakpoint.
  • Warning zone up to (above is Serious) — the warningMax breakpoint; anything past it renders as the serious band.
  • Background color, padding, border and border radius on the card.
  • Value color/size and label color/size — text styling for the big value line and the heading label.

If the value is blank or doesn't resolve to a number (an unresolved merge tag, for instance), the block renders its label and card chrome with a plain "Add a numeric value to render this gauge" notice instead of the arc. An authored range where min >= max, or thresholds out of order, is clamped automatically rather than producing a broken dial mid-edit.

Examples

An SLA or uptime snapshot — "99.94% uptime this month," good up to 99.9%, warning up to 99.5%, anything below that serious — dropped into a status-page digest gives subscribers an at-a-glance health read without a dashboard link. A support team can chart average response time against target SLAs (good under 2 hours, warning under 6, serious past that). A customer-facing NPS or satisfaction score report can use a gauge as the headline visual in a quarterly relationship email, thresholds authored so a high score reads as good rather than risky.

What the static fallback looks like

<div style="margin:12px 0;background-color:#ffffff;padding:16px">
  <p style="margin:0 0 4px;font-weight:600;font-size:13px;color:#6b7280">Uptime this month</p>
  <p style="margin:0 0 6px;font-weight:700;font-size:32px;color:#111827">
    99.94%  <span style="font-size:14px;font-weight:600;color:#16a34a">Good</span>
  </p>
  <img src="https://mailinapp.com/api/analytics/chart?d=eyJ0eXBlIjoi...&s=3f9a2b1c..." width="320" height="200"
       alt="Gauge: 99.94 of 0–100 (Good)" />
  <p style="margin:4px 0 0;font-size:11px;color:#9ca3af">Uptime this month — 99.94% (Good) — scale 0–100</p>
</div>

The bold value line and the muted summary line beneath the image are both real HTML text — the value and status are never dependent on the arc image rendering, which is why gauge is the one block in the family without a data table.

Related