gx_gauge

Customizable, animated and accessible gauges for Flutter: linear progress, stepper, scale and bar gauges, plus a radial gauge.

Formerly published as girix_code_gauge. Upgrading? See the migration guide.

Features

• Five gauges: GxLinearProgressGauge, GxLinearStepperGauge, GxLinearScaleGauge, GxLinearBarGauge and GxRadialGauge.
• Animated: pass a duration and curve, and value changes animate smoothly, like AnimatedContainer.
• Interactive: add onChanged to turn a gauge into a slider, or a radial gauge into a knob.
• Ranges, needles, markers and labels, including gradients and fully custom needle painting.
• Horizontal or vertical, and mirrored automatically in right-to-left locales.
• Theme-aware: colors you don't set come from your ColorScheme, so dark mode just works.
• Accessible: screen readers announce each gauge's label and value.
• No dependencies beyond Flutter.

Install

flutter pub add gx_gauge

import 'package:gx_gauge/gx_gauge.dart';

Requires Flutter 3.47 or later.

Quick start

Every gauge takes a GxGaugeValue(value:, min:, max:) (the range defaults to 0–100). Linear gauges fill the available width, and a radial gauge fills the shortest side unless you give it a diameter.

Linear progress

const GxLinearProgressGauge(
  value: GxGaugeValue(value: 68),
  needle: GxLinearNeedle(
    shape: GxNeedleShape.triangle,
    position: GxNeedlePosition.bottom,
    size: Size(14, 14),
  ),
)

Stepper

const GxLinearStepperGauge(
  currentStep: 2,
  steps: <GxStepperStep>[
    GxStepperStep(label: GxGaugeLabel(label: 'Ordered')),
    GxStepperStep(label: GxGaugeLabel(label: 'Packed')),
    GxStepperStep(label: GxGaugeLabel(label: 'Shipped')),
    GxStepperStep(label: GxGaugeLabel(label: 'Delivered')),
  ],
)

Scale

const GxLinearScaleGauge(
  value: GxGaugeValue(value: 72),
  interval: 20,
  minorTicksPerInterval: 3,
  needle: GxLinearNeedle(
    shape: GxNeedleShape.triangle,
    position: GxNeedlePosition.top,
    size: Size(14, 14),
  ),
  ranges: <GxLinearRange>[
    GxLinearRange(start: 0, end: 60, color: Colors.green),
    GxLinearRange(start: 60, end: 85, color: Colors.orange),
    GxLinearRange(start: 85, end: 100, color: Colors.red),
  ],
)

Bar

const GxLinearBarGauge(
  value: GxGaugeValue(value: 72),
  gapBetweenBars: 4,
  bars: <GxLinearBarPointer>[
    GxLinearBarPointer(start: 0, end: 50, color: Colors.green),
    GxLinearBarPointer(start: 50, end: 80, color: Colors.orange),
    GxLinearBarPointer(start: 80, end: 100, color: Colors.red),
  ],
  needle: GxLinearNeedle(
    shape: GxNeedleShape.triangle,
    position: GxNeedlePosition.top,
    size: Size(14, 14),
  ),
)

Radial

const GxRadialGauge(
  value: GxGaugeValue(value: 65),
  diameter: 220,
  startAngleInDegree: 135,
  sweepAngleInDegree: 270,
  interval: 20,
  showMajorTicks: true,
  showMinorTicks: true,
  minorTicksPerInterval: 3,
  showLabels: true,
  showNeedle: true,
  needle: GxRadialNeedle(),
)

Angles are in degrees, clockwise from 3 o'clock.

Recipes

Ranges with labels

const GxRadialGauge(
  value: GxGaugeValue(value: 45),
  diameter: 220,
  startAngleInDegree: 150,
  sweepAngleInDegree: 240,
  style: GxRadialGaugeStyle(thickness: 6),
  showNeedle: true,
  needle: GxRadialNeedle(thickness: 6),
  ranges: <GxRadialRange>[
    GxRadialRange(start: 0, end: 60, offset: -16, color: Colors.green,
        label: GxGaugeLabel(label: 'Eco')),
    GxRadialRange(start: 60, end: 100, offset: -16, color: Colors.red,
        label: GxGaugeLabel(label: 'Sport')),
  ],
)

Linear scales take GxLinearRanges the same way. Bars and ranges also accept a shaderCallback (for gradients) and a borderColor.

Animation

Every gauge animates value changes once you give it a duration. An update that arrives mid-animation continues smoothly from the value on screen.

GxRadialGauge(
  value: GxGaugeValue(value: speed, max: 240),
  duration: const Duration(milliseconds: 600),
  curve: Curves.easeOutCubic,
)

Interaction

Add onChanged to let users tap or drag a gauge to set its value. The radial gauge works like a knob. Interactive gauges can also be adjusted with screen readers.

GxRadialGauge(
  value: GxGaugeValue(value: _volume),
  semanticLabel: 'Volume',
  onChanged: (double v) => setState(() => _volume = v),
)

The progress, scale and bar gauges take onChanged too, and the stepper reports taps with onStepTapped.

Vertical gauges

const GxLinearProgressGauge(
  value: GxGaugeValue(value: 70),
  direction: Axis.vertical,
)

All four linear gauges accept direction: Axis.vertical, and run bottom to top.

Custom needles

Set the needle's shape to GxNeedleShape.custom and draw it yourself. The painter receives the needle, with its color already resolved.

void drawPin(Canvas canvas, Offset anchor, GxLinearNeedle needle) {
  final Paint paint = Paint()..color = needle.color!;
  canvas.drawCircle(anchor, needle.size.width / 2, paint);
}

const GxLinearScaleGauge(
  value: GxGaugeValue(value: 40),
  needle: GxLinearNeedle(shape: GxNeedleShape.custom, size: Size(12, 12)),
  needlePainter: drawPin,
)

Pass a top-level or static function so the gauge doesn't repaint every time its parent rebuilds.

Theming

Colors you leave unset come from the ambient Theme. For example, primary fills progress and arcs, outline colors ticks, and onSurface colors needles. To pin a color, set it on the style:

const GxLinearProgressGauge(
  value: GxGaugeValue(value: 40),
  style: GxLinearProgressStyle(
    color: Colors.deepPurple,
    backgroundColor: Colors.black12,
  ),
)

Accessibility

Each gauge announces its value to screen readers. Add a semanticLabel, e.g. 'Battery', and optionally a semanticValueFormatter, e.g. (v) => '${v.round()} percent'.

Migrating from girix_code_gauge

This package was previously published as girix_code_gauge. Every type now has the Gx prefix, and a few APIs have changed. doc/MIGRATION.md lists every change, with before-and-after code.

More

• API reference: every class and parameter, with defaults.
• Example app: lib/main.dart is a minimal demo, and lib/showcase/ covers every option.
• Changelog
• Contributing
• MIT License