Skip to main content

GaugeChart

GaugeChart

Display single value metrics with progress indicator

Tags: chart metric kpi progress score

View Demo

The GaugeChart displays a single value within a range, similar to a speedometer or dial. It's perfect for KPIs, performance scores, completion percentages, or any metric where you want to show progress toward a goal or threshold.

Reporting props marked Svelte only (valueFormat, showDataTable, exportable, reference lines, data zoom and so on) are available in @classic-homes/charts-svelte; React support is pending.

Import​

<script>
  import { GaugeChart } from '@classic-homes/charts-svelte';
</script>
// React
import { GaugeChart } from '@classic-homes/charts-react';

Basic Usage​

<script>
  import { GaugeChart } from '@classic-homes/charts-svelte';
</script>

<GaugeChart title="Performance Score" value={72} min={0} max={100} showProgress height={400} />

Props​

Chart-Specific Props​

Prop Type Default Description
value number required Current value to display; a value that is not a finite number shows the empty state
min number 0 Minimum value of the gauge
max number 100 Maximum value of the gauge
splitNumber number 10 Number of tick divisions
showProgress boolean false Show colored progress arc
formatValue (value: number) => string - Custom value formatter (takes precedence over valueFormat)
onClick (params: DataPointEventParams) => void - Callback when the gauge is clicked

Inherited Base Props​

Prop Type Default Description
title string required Chart title for accessibility
height number | string 400 Chart height
theme 'light' | 'dark' | 'auto' 'auto' Theme preference
animation boolean true Enable/disable animations
tooltipFormatter string | ((items: TooltipFormatterParams[]) => string) - Custom tooltip template or HTML function
tooltipValueFormatter (value: number) => string - Format values in the default tooltip
option EChartsOption - Raw ECharts option deep-merged over the generated one
description string - Optional description for screen readers
minHeight number - Minimum height in pixels; also bounds an 'auto' height
maxHeight number - Maximum height in pixels; also bounds an 'auto' height
loading boolean false Show loading skeleton; over existing data a loading overlay is shown instead (Svelte)
error string | null - Error message to display
onRetry () => void - Show a Retry button on the error state, calling this (Svelte only)
emptyMessage string - Message shown when data is empty
valueFormat ValueFormatPreset | Intl.NumberFormatOptions | ((value: number) => string) - How values are written in value axes, tooltips, labels and the data table: 'number', 'integer', 'compact', 'currency', 'currencyCents', 'percent', 'percentValue', 'days', Intl options or a function (Svelte only)
locale string 'en-US' Locale for valueFormat (Svelte only)
onReady (chart: EChartsType) => void - Called with the ECharts instance when it is created (Svelte only)
events Record<string, (params) => void> - Raw ECharts event handlers keyed by event name, e.g. datazoom (Svelte only)
showDataTable boolean | 'sr-only' 'sr-only' Render the data as a table: 'sr-only' for screen readers, true adds a visible "Show data" toggle, false for none (Svelte only)
exportable boolean | ChartExportConfig false Show PNG and CSV download buttons; or { image, csv, filename } (Svelte only)
patterns boolean false Fill series with decal patterns as well as colour, for colour-blind readers (Svelte only)
class string - Custom CSS class
showLegend boolean - Show chart legend
showTooltip boolean true Show tooltip on hover
showGrid boolean - Show grid lines (where applicable)

Examples​

Performance Score​

<GaugeChart title="Performance Score" value={85} min={0} max={100} showProgress />

With Custom Formatter​

<GaugeChart title="Completion Rate" value={72} formatValue={(v) => `${v}%`} showProgress />

Temperature Gauge​

<GaugeChart
  title="CPU Temperature"
  value={65}
  min={0}
  max={100}
  formatValue={(v) => `${v}°C`}
  showProgress
/>

Revenue KPI​

<GaugeChart
  title="Monthly Target"
  value={85000}
  min={0}
  max={100000}
  formatValue={(v) => `$${(v / 1000).toFixed(0)}K`}
  showProgress
/>

Value Format and Missing Values (Svelte only)​

<GaugeChart
  title="On-time Closings"
  value={0.87}
  min={0}
  max={1}
  valueFormat="percent"
  showProgress
/>

<!-- null or NaN shows the empty state instead of a needle at 0 -->
<GaugeChart title="On-time Closings" value={null} emptyMessage="No closings yet" />

Accessibility​

  • Title provides clear context
  • Value is announced to screen readers
  • Progress indicator provides visual feedback
  • Respects reduced motion preferences
On this page