Gauge

Use a gauge to communicate one value against a known range or threshold scale.

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

Basic

Use the single_value shape with one measure and an explicit meaningful range.

Key fields

visuals:
  total_orders_gauge:
    title: Total orders gauge
    type: gauge
    presentation:
      minimum: 0
      maximum: 120000
      target: 100000
    query:
      measures:
        order_count: null

Bounded score

Use a bounded measure such as review score so the gauge position has an immediately understood minimum and maximum.

Key fields

visuals:
  review_gauge:
    title: Average review gauge
    type: gauge
    presentation:
      minimum: 0
      maximum: 5
      target: 4.5
    query:
      measures:
        review_score: null

Threshold bands

Declare min and max, then add ordered thresholds to give score ranges semantic tones; progress_width controls the arc weight.

Key fields

visuals:
  review_gauge_thresholds:
    title: Review gauge with thresholds
    type: gauge
    presentation:
      minimum: 0
      maximum: 5
      target: 4.5
      progress_width: 16
      thresholds:
        - value: 3
          tone: danger
        - value: 4
          tone: warning
        - value: 5
          tone: success
    query:
      measures:
        review_score: null

API reference

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

Field	Type	Default	Allowed values	Description
`query.measures`	`measure mapping`	—	—	Selects the governed semantic measures consumed by the visual shape.
`presentation.maximum`	`number`	`required for gauges`	—	Sets the explicit upper bound of a gauge scale.
`presentation.minimum`	`number`	`required for gauges`	—	Sets the explicit lower bound of a gauge scale.
`presentation.progress_width`	`number`	`12`	`positive number`	Sets the width of the gauge progress arc.
`presentation.target`	`number`	`none`	—	Adds a labeled gauge target that must fall within the configured domain.
`presentation.thresholds`	`threshold list`	`none`	—	Maps gauge thresholds to scale positions and colors.

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