chartificial #

Cartesian charts for Flutter, built on the framework's two-dimensional viewport. Designed for the charts that are awkward everywhere else: time series that scroll, history that loads as you reach it, and axis labels that are real widgets.

Why chartificial #

• Lazy paged loading. Give it a ChartLoader and history is fetched before the user scrolls to the edge, with a configurable prefetch margin. Loading never blocks scrolling: the user can keep going into regions whose data hasn't arrived yet, and pages land behind them without moving the pixels already on screen.
• Axis labels are widgets. AxisLabelConfig.builder returns whatever you like — an icon, a chip, a two-line date. The viewport recycles them instead of rebuilding, so scrolling costs nothing extra.
• A fixed spine, pluggable policies. The frame sequence is closed; every decision inside it is an interface you can implement. Series, decorations, range policies, tick strategies, scales and pointer snapping are all open seams — the built-in bar series is itself just a client of the public ChartSeries.
• No dependencies. flutter and nothing else. Android, iOS, web, macOS, Windows and Linux.

Gallery #

Scrolling time axis — newest point pinned right, scroll into the past	Value-space color bands — stroke colored by value, not by position
Line styles — curves, dashes, area fill, gradient stroke, end badge	Floating bars — min–max pills over a background track
Stacked + grouped bars — cumulative segments, clustered per slot	Mixed series — bars and a line sharing a scrolling axis
Custom decorations — replace the grid, ring the viewport edge crossings	Custom series — a lollipop series defined outside the package

Install #

$ flutter pub add chartificial

import 'package:chartificial/chartificial.dart';

Quick start #

Everything but the axes and series has a working default, and it is all const-constructible:

SizedBox(
  height: 240,
  child: Chartificial(
    xAxis: const NumericAxis(),
    yAxis: const NumericAxis(),
    series: const [
      LineSeries(
        id: 'demo',
        data: [
          ChartPoint(0, 1),
          ChartPoint(1, 3),
          ChartPoint(2, 2),
          ChartPoint(3, 5),
        ],
      ),
    ],
  ),
)

Like every viewport, the chart cannot size itself to its content — give it bounded constraints in both directions (SizedBox, Expanded, AspectRatio).

Scrolling time series #

The case the package is built for. AxisAnchor.end starts at the newest point and scrolls left into history; AxisResolution.interval fixes how many pixels an hour occupies, which is what makes the axis scrollable at all; and ChartLoader fetches older pages before the user reaches them.

final controller = ChartificialController(
  followLatest: true, // stay pinned to "now" until the user scrolls away
  loader: ChartLoader(
    onLoadOlder: (request) async {
      final page = await api.fetchBefore(request.edgeDateTime);
      controller.prependPoints('aqi', page.points);
      return page.hasMore; // returning false latches exhaustion
    },
  ),
);

Chartificial(
  controller: controller,
  xAxis: DateTimeAxis(
    anchor: AxisAnchor.end,
    resolution: AxisResolution.interval(const Duration(hours: 1), 24),
    ticks: AxisTicks.timeInterval(const Duration(hours: 6)),
    labels: AxisLabelConfig(
      builder: (context, tick) => Text('${tick.dateTime.hour}:00'),
    ),
  ),
  yAxis: const NumericAxis(range: AxisRange.fixed(0, 300)),
  series: const [
    LineSeries(
      id: 'aqi',
      colorScale: ChartColorScale.bands([
        ColorBand(0, 50, Color(0xFF4CAF50)),
        ColorBand(50, 100, Color(0xFFFFC107)),
        ColorBand(100, 300, Color(0xFFF44336)),
      ]),
    ),
  ],
  trackball: TrackballBehavior(
    builder: (context, details) => MyTooltip(details),
  ),
)

Loading never gates scrolling. While controller.canLoadMore(direction) is true the scroll boundary stays ahead of the finger, so the user can fling straight past the loaded edge: the not-yet-loaded region renders as an empty plot with a live axis, and pages fill it in without shifting what is on screen. ChartLoadRequest.suggestedSpanX covers the whole scrolled-ahead gap, so a source that honors the hint fills it in one page. Only exhaustion (returning false) bounds the scroll — the chart then eases back to the oldest loaded point, and isAtLatest/scrollToLatest always mean the newest datum, never a loading boundary.

ChartColorScale stops are defined in value space, so a band boundary sits exactly at 50 however the axis is transformed — including a log axis.

Extension points #

The spine being closed is the point: paint order, label recycling, scroll anchoring and load triggering are invariants you compose within.

Every open seam takes a single context object (ChartPaintContext, AxisRangeContext, TickResolveContext), so new capabilities arrive as new context fields rather than as signature breaks.

Example app #

example/ has twelve runnable demos:

$ cd example && flutter run

Requirements #

Flutter >=3.44.0 / Dart ^3.12.0, for the TwoDimensionalViewport APIs the chart is built on.

Contributing #

Issues and pull requests are welcome — see CONTRIBUTING.md.

License #

MIT — see LICENSE.