Overview

The CircularChart block renders arc-based visualizations inside a single component. Pick the variant that matches the data shape and communicative goal: a Gauge for a single scalar value against a range (fill level, completion percentage), a Radial Bar for multiple independent series on concentric rings (part-to-whole comparisons without summing to 100%), or a Speedometer for a real-time scalar value with color-coded threshold zones (CPU usage, server response time).

Tip: Both show a single value against a range. Use Gauge when the fill level itself communicates progress (e.g. 72% complete). Use Speedometer when threshold zones are the main story — the needle pointing into a red zone is the signal, not the numeric value.

Properties Reference

Gauge Variant

The gauge renders a partial arc filled from min to value. The center label shows the formatted value. This is the simplest variant — one number, one arc, one meaning.

Configuring a Gauge

1. Drop the block and set chartType: Drag CircularChart onto the canvas. In the Content inspector, set Chart Type = gauge.

2. Bind the value: Set Value to a binding expression — e.g. {{ ds_satisfaction.data.score }}. Set Min = 0 and Max = 10 to match a 0–10 satisfaction score.

3. Configure the label: Set Label Format to {{value}} / 10 to show the absolute value rather than a percentage. Enable Show Label = true.

4. Add thresholds (optional): Add threshold entries: { value: 4, color: "#EF4444" }, { value: 7, color: "#F59E0B" }, { value: 10, color: "#10B981" }. The arc turns green in the 7–10 zone, amber in 4–7, and red below 4.

Radial Bar Variant

The radial bar shows multiple independent series as concentric rings, each ring representing one metric's progress toward its own target. Unlike a pie chart, the rings do not sum to 100% — each is independently scaled 0–100.

Note: Each ring in a Radial Bar is independently full-circle at value = 100. If you want rings to show proportions of a total (which must sum to 100%), use a Pie or Donut chart instead.

Data Format for Radial Bar

Bind the data property to an array. Each element is one ring:

[ { "name": "Onboarding", "value": 88, "color": "#6366F1" }, { "name": "Feature Use", "value": 61, "color": "#0EA5E9" }, { "name": "Support Sat.", "value": 74, "color": "#10B981" } ]

The rings render outermost-first. Labels appear in a legend below the chart or inside each ring (controlled by Show Label).

Speedometer Variant

The speedometer is functionally similar to a gauge but optimized for real-time readings where threshold zones communicate operational status. It adds a needle, tick marks at threshold boundaries, and an optional zone legend.

Example: Server response time speedometer

Set Chart Type = speedometer, Min = 0, Max = 2000 (ms), Value bound to {{ api_health.avgResponseMs }}. Add thresholds: [{ value: 500, color: "#10B981" }, { value: 1200, color: "#F59E0B" }, { value: 2000, color: "#EF4444" }]. Set Label Format = "{{value}} ms". The needle swings into the red zone and the arc color shifts automatically when response times degrade.

Events & Exposed State

Common Patterns

Pattern: Employee satisfaction gauge on an HR dashboard

Use a Gauge with Min = 1, Max = 5, Value bound to the average satisfaction query result. Set Label Format = "{{value}}/5". Place it in a Stat Card's icon slot for a compact at-a-glance metric with a mini-arc indicator.

Pattern: Sales target progress radial

Use a Radial Bar to compare multiple sales reps' attainment simultaneously. Each ring's value is the rep's percentage of quota (0–100). Color-code by quartile. This avoids the stacked bar chart layout while preserving individual-vs-target context for each rep.

Related Pages