Metrics & Gauges

Six islands for at-a-glance state: a headline KPI, a multi-stat scorecard, three gauges, and a status grid of service/check tiles. Each previewed below is a real OpenIslands renderer: the same code a live dashboard runs, not a screenshot. For the full registry, see Islands.

metric.kpi

A single headline number off the last row, with an optional delta versus the previous row and a sparkline drawn over the time axis it finds. Reach for it when one number (net worth, MRR, today's steps) deserves the top of a page.

{
  "type": "metric.kpi",
  "title": "Monthly revenue",
  "dataset": "revenue",
  "value": "revenue_eur",
  "compareTo": "prev",
  "format": "eur"
}

• value: the field holding the headline number (required).
• compareTo: "prev" draws a delta against the previous row; a field name compares to that column instead; "none" (the default) shows no delta.
• target: a field holding a target to measure the value against.
• format: any value format; unit appends a free-form suffix.
• color: a 6-digit hex (e.g. "#22C55E") for the sparkline, overriding the palette.

metric.scorecard

A compact scorecard of several KPIs read off the last row, each with an optional delta versus the previous row. Reach for it when a handful of related numbers (MRR, active users, churn, NPS) belong together in one tidy tile instead of separate KPI cards.

{
  "type": "metric.scorecard",
  "title": "This month",
  "dataset": "saas_metrics",
  "stats": [
    { "value": "mrr_eur", "label": "MRR", "format": "eur", "compareTo": "prev" },
    { "value": "active_users", "label": "Active users", "format": "int", "compareTo": "prev" },
    { "value": "churn", "label": "Churn", "format": "pct" },
    { "value": "nps", "label": "NPS", "format": "int" }
  ]
}

• stats: the list of numbers to show (at least one), each reading its value off the last row.
• stats[].label defaults to the field name; a value format (format) or free-form unit styles the value; compareTo: "prev" adds a delta badge versus the previous row.
• columns: a fixed grid column count (1-6); omitted, the grid is responsive.

gauge.rings

Up to four concentric progress rings read off the last row: the dashboard view when several goals or budgets share one tile. Each ring fills toward its max (a column or a fixed number); the center shows the outermost ring's percentage.

{
  "type": "gauge.rings",
  "title": "Today's targets",
  "dataset": "daily_targets",
  "rings": [
    { "value": "calories", "max": "calorie_goal", "label": "Calories" },
    { "value": "protein_g", "max": "protein_goal", "label": "Protein" },
    { "value": "water_ml", "max": "water_goal", "label": "Water" }
  ]
}

• rings: one to four rings, outermost first (required). Each is { value, max, label?, color?, direction? }.
• max: a column name or a fixed number; the goal the ring fills toward.
• direction: atLeast (default, fills toward a goal) or atMost (a budget: crossing the limit turns the ring danger-red).
• color: a CSS color per ring; defaults to a built-in palette.

gauge.goal

One ring per goal, each comparing the last row's value to a goal or a target band. Reach for it when a number has a defined good range: within the band reads success-green, under it amber, over it danger-red. The three rings below hit all three tones at once — heart rate over its band, sleep clear of its floor, activity short of it.

{
  "type": "gauge.goal",
  "title": "Today vs goals",
  "dataset": "vitals",
  "size": "small",
  "goals": [
    { "value": "rhr", "goal": { "min": 50, "max": 60 }, "label": "Resting HR", "unit": "bpm", "format": "int" },
    { "value": "sleep_h", "goal": { "min": 7 }, "label": "Sleep", "unit": "h", "format": "int" },
    { "value": "active_min", "goal": { "min": 30 }, "label": "Active", "unit": "min", "format": "int" }
  ]
}

• goals: one to six goals, each its own ring side by side in a row that wraps (required). Each is { value, goal, label?, unit?, format? }, read off the last row.
• goal: at least one of min / max, each a column or a number; supplying both makes a target band, the value reads green inside it, amber below, red above.
• value: the field holding the ring's current number; format is any value format, unit/label annotate the ring.
• size: the footprint shared by every ring — small, medium (the default), or large. small packs several rings across a row and swaps each badge for a compact status dot; large emphasizes one or two.

gauge.meter

One or more horizontal usage bars read off the last row: the quota- or capacity-style view. Each meter shows value / max and fills proportionally in its own color.

{
  "type": "gauge.meter",
  "title": "Plan usage",
  "dataset": "plan_usage",
  "meters": [
    { "value": "storage_gb", "max": "storage_cap", "label": "Storage (GB)" },
    { "value": "seats_used", "max": "seat_cap", "label": "Seats" },
    { "value": "api_calls", "max": "api_cap", "label": "API calls" }
  ]
}

• meters: one or more bars, top to bottom (required). Each is { value, max, label?, color? }.
• max: a column name or a fixed number; the capacity the bar fills against.
• color: a CSS color per meter; defaults to a built-in palette.

status.grid

A responsive grid of state tiles, one per row: the ops & status-page view for service or check health. Each tile labels an entity, badges its state, and can show a metric underneath; the badge tone comes from the state value.

{
  "type": "status.grid",
  "title": "Service status",
  "dataset": "services",
  "label": "service",
  "state": "status",
  "value": "p95_ms",
  "format": "int",
  "tones": { "maintenance": "warning" }
}

• label: the field naming each entity — a service, check, or host (required).
• state: the field holding each entity's status value, shown as the tile's badge (required).
• value: an optional metric shown under the label; format is any value format.
• tones: a state → tone map (success / warning / danger / neutral) to override the tone of specific state values. Unmapped values fall back to a keyword convention: up / ok / healthy / online → success, warn / degraded / pending → warning, down / error / critical / fail → danger, anything else → neutral.