Gauge

Use a gauge to communicate one value against an automatically derived or authored range.

Every preview on this page is generated from the YAML shown below it using a fixed documentation dataset.

Omit both minimum and maximum to derive a readable domain from the current single metric value. Set both to author a stable domain; an out-of-range value is shown as a diagnostic rather than clipped. Optional target and thresholds are anchored to an authored domain, while showPointer and progressWidth can be used with either mode.

Customer review health

Use a naturally bounded score with an explicit target, so the position and distance from goal are immediately interpretable.

Key fields

visuals:
  - id: review_gauge
    title: Average customer review
    type: gauge
    presentation:
      type: polar
      minimum: 0
      maximum: 5
      target: 4.5
    query:
      type: aggregate
      dimensions: []
      metrics:
      - review_score

Large-volume domain

Large count domains remain supported when the operating range and target are genuinely meaningful, though a KPI or progress mode is often easier to scan.

Key fields

visuals:
  - id: total_orders_gauge
    title: Total orders gauge
    type: gauge
    presentation:
      type: polar
      minimum: 0
      maximum: 120000
      target: 100000
    query:
      type: aggregate
      dimensions: []
      metrics:
      - order_count

Threshold bands

Add ordered thresholds to give score ranges semantic tones; progressWidth controls the arc weight.

Key fields

visuals:
  - id: review_gauge_thresholds
    title: Review gauge with thresholds
    type: gauge
    presentation:
      type: polar
      minimum: 0
      maximum: 5
      target: 4.5
      progressWidth: 16
      thresholds:
      - value: 3
        tone: danger
      - value: 4
        tone: warning
      - value: 5
        tone: success
    query:
      type: aggregate
      dimensions: []
      metrics:
      - review_score

API reference

Kind: chart. Renderer: echarts. Supported result shapes: scalar.

Field	Type	Default	Allowed values	Description
`query.metrics`	`metric mapping`	—	—	Selects governed semantic metrics consumed by the visual shape.
`presentation.maximum`	`number`	`renderer default`	—	Sets the upper bound of a polar scale.
`presentation.minimum`	`number`	`renderer default`	—	Sets the lower bound of a polar scale.
`presentation.progressWidth`	`number`	`renderer default`	`positive number`	Sets the gauge progress arc width.
`presentation.target`	`number`	`none`	—	Marks an explicit target on a polar scale.
`presentation.thresholds`	`threshold list`	`none`	`ordered numeric thresholds`	Classifies gauge values into ordered ranges with semantic tones.

Accessibility. Use a descriptive title and unit, and do not rely on color alone to distinguish series or values.