Gauge Chart

Gauge charts display a single value within a defined range, similar to a speedometer. They are perfect for showing progress, KPIs, or any metric that falls within a known minimum and maximum.

Interface

GaugeChart Props

interface GaugeChartProps {
  // Required properties
  data: GaugeChartData;

  // Optional properties
  custom?: Partial<GaugeChartCustom>;
  title?: string;
}

Data Structure

type GaugeChartZone = {
  min: number;       // Zone start value
  max: number;       // Zone end value
  color: string;     // Zone color
};

type GaugeChartData = {
  value: number;         // Current value
  min?: number;          // Minimum scale value
  max?: number;          // Maximum scale value
  title?: string;        // Chart title
  zones?: GaugeChartZone[];  // Color zones
};

Basic Usage

import Widget from '@meursyphus/flitter-react';
import { GaugeChart } from '@meursyphus/headless-chart';

const data = {
  value: 72,
  min: 0,
  max: 100,
  title: 'Performance Score',
  zones: [
    { min: 0, max: 40, color: '#ef4444' },
    { min: 40, max: 70, color: '#f59e0b' },
    { min: 70, max: 100, color: '#10b981' }
  ]
};

function BasicGaugeChart() {
  return (
    <Widget
      width="400px"
      height="300px"
      widget={GaugeChart({ data })}
    />
  );
}

Chart Components

Gauge Chart consists of the following hierarchical structure:

GaugeChart
└── Layout (overall layout)
    ├── Title (chart title)
    ├── Gauge (gauge area)
    │   ├── Scale (arc scale with zones)
    │   └── Needle (indicator needle)
    └── ValueLabel (current value display)

Customizable Elements

You can customize the following components through the custom prop:

Real-World Usage Examples

1. Custom Value Label

const customGauge = GaugeChart({
  data,
  custom: {
    valueLabel: ({ value, min, max }) => {
      const percentage = ((value - min) / (max - min)) * 100;
      return Column({
        children: [
          Text(`${value}`, {
            style: new TextStyle({ fontSize: 32, fontWeight: 'bold', color: '#1f2937' })
          }),
          Text(`${percentage.toFixed(0)}%`, {
            style: new TextStyle({ fontSize: 16, color: '#6b7280' })
          })
        ]
      });
    }
  }
});

2. Custom Zones

const zoneGauge = GaugeChart({
  data: {
    value: 85,
    min: 0,
    max: 100,
    zones: [
      { min: 0, max: 25, color: '#ef4444' },
      { min: 25, max: 50, color: '#f97316' },
      { min: 50, max: 75, color: '#eab308' },
      { min: 75, max: 100, color: '#22c55e' }
    ]
  }
});

Next Steps

• For more examples, check out the demo page
• Use color zones to indicate different severity levels
• Customize the needle and value label for branded dashboards