zoned_line_chart 1.1.4

A highly customizable line chart widget for Flutter featuring colored zone backgrounds, automatic axis ticking, smooth Catmull-Rom curves, and interactive tap-to-inspect tooltips.

zoned_line_chart

A highly customizable line chart widget for Flutter featuring colored zone backgrounds, practitioner target lines, collapsible UI, data filtering, automatic axis ticking, smooth curves, and interactive tap-to-inspect tooltips.

Features

• Collapsible chart – A toggle button in the top-right corner to fold/unfold the chart with smooth animation.
• Data filtering – Built-in filter chips (5 / 10 / 20 / 50 / All) to quickly show the most recent N data points.
• Zone backgrounds – Define colored horizontal bands to indicate thresholds (e.g. normal, warning, danger). Areas beyond the defined zones are automatically filled with the nearest zone's color — no white gaps.
• Practitioner target lines – Dashed black horizontal lines with labels for clinical or reference targets.
• Two-line X-axis labels – Date on top (MM/dd), time below (HH:mm) for datetime axes.
• Smart label visibility – All labels shown for small datasets (≤7 points); 4 evenly-spaced labels for larger ones.
• Smooth line rendering – Catmull-Rom spline interpolation for natural-looking curves.
• Auto-ticking axes – Heckbert "nice numbers" algorithm generates clean Y-axis tick values automatically.
• Tap interaction – Tap any data point to display a tooltip with timestamp, value, and custom notes.
• Minimal dependencies – Built entirely with Flutter's CustomPainter; only intl (>=0.19.0 <1.0.0) is used for date formatting.

Installation

Add to your pubspec.yaml:

dependencies:
  zoned_line_chart: ^1.1.4

Then run:

flutter pub get

Quick Start

import 'package:zoned_line_chart/zoned_line_chart.dart';

CustomLineChart(
  data: [
    DataPoint(x: '2024-10-01T08:00:00Z', y: 36.5, metadata: {'note': 'Morning'}),
    DataPoint(x: '2024-10-01T12:00:00Z', y: 37.8, metadata: {'note': 'After lunch'}),
    DataPoint(x: '2024-10-01T18:00:00Z', y: 37.1),
  ],
  xAxisUnit: XAxisUnit.time,
  yAxisUnit: '°C',
  yAxisRange: (35, 43),
  zones: [
    ChartZone(name: 'Normal',    minY: 35.5, maxY: 37.5, color: Colors.green),
    ChartZone(name: 'Low Fever', minY: 37.5, maxY: 38.5, color: Colors.orange),
    ChartZone(name: 'High Fever', minY: 38.5, maxY: 43,  color: Colors.red),
  ],
  targetLines: [
    TargetLine(name: 'Target Low',  value: 36.0),
    TargetLine(name: 'Target High', value: 37.0),
  ],
  title: 'Temperature Monitoring',
  description: 'Tap a data point for details',
  collapsible: true,
  showFilter: true,
)

API Reference

CustomLineChart

Property	Type	Default	Description
data	List<DataPoint>	required	Data points to plot
xAxisUnit	XAxisUnit	.number	X-axis formatting mode
yAxisUnit	String	''	Unit string for Y-axis labels & tooltip
yAxisRange	(double, double)?	auto	Fixed Y range; auto-computed when null
zones	List<ChartZone>	[]	Colored horizontal background bands
targetLines	List<TargetLine>	[]	Dashed horizontal target/reference lines
title	String?	null	Card title above the chart
description	String?	null	Subtitle below the title
chartHeight	double	350	Height of the chart area
lineColor	Color	#1860A8	Color for the line and data dots
tooltipLabel	String?	null	Small label shown above the timestamp in tooltip
tooltipValueLabel	String	'Value'	Label next to the value dot in tooltip
collapsible	bool	true	Show a fold/unfold button in the top-right corner
initiallyExpanded	bool	true	Whether the chart starts expanded
showFilter	bool	true	Show the data-count filter chips
filterOptions	List<int?>	[5,10,20,50,null]	Available filter counts; null = "All"

DataPoint

Property	Type	Description
x	dynamic	X value – DateTime, String (ISO 8601), or num
y	double	Y value (numeric)
metadata	Map<String, dynamic>?	Optional metadata; 'note' key is shown in tooltip

ChartZone

Property	Type	Description
name	String	Zone name (shown in legend)
minY	double	Lower bound of the zone
maxY	double	Upper bound of the zone
color	Color	Zone background and legend color
label	String?	Optional short label

TargetLine

Property	Type	Description
name	String	Target name (shown on chart and in legend)
value	double	Y-axis value where the dashed line is drawn

XAxisUnit

Value	Axis Labels	Description
.time	MM/dd + HH:mm (two lines)	Date on top, time below
.date	MM/dd + HH:mm (two lines)	Date on top, time below
.number	raw value	Numeric display
.string	raw value	String display

Copy-paste Usage

If you prefer not to add a package dependency, copy these three files into your project:

lib/widgets/chart/
├── models.dart
├── chart_painter.dart
└── custom_line_chart.dart

Make sure intl is in your pubspec.yaml. The files use relative imports and work together in any directory.

License

MIT