mix_chart 0.0.1
mix_chart: ^0.0.1 copied to clipboard
Type-safe Flutter chart widgets styled with Mix.
mix_chart #
Mix-styled Flutter line/area, grouped/stacked/floating bar, and pie/donut charts.
Mix owns data models, stable IDs, interactions, semantics and generated stylers;
fl_chart is a private renderer, with no raw configuration escape hatch.
See the decision log.
Quick start #
import 'package:flutter/material.dart';
import 'package:mix/mix.dart';
import 'package:mix_chart/mix_chart.dart';
LineChart(
semanticsLabel: 'Weekly revenue',
series: [
LineSeries(
id: 'revenue',
label: 'Revenue',
points: [
ChartPoint(id: 'mon', x: 0, y: 18),
ChartPoint(id: 'tue', x: 1, y: 31),
ChartPoint(id: 'wed', x: 2, y: 27),
],
style: .stroke(
.color(const Color(0xFF6366F1)).width(3),
).marker(.show(true).radius(4)),
),
],
xAxis: ChartAxis.numeric(
interval: 1,
labelFormatter: (value) => ['Mon', 'Tue', 'Wed'][value.round()],
),
yAxis: ChartAxis.numeric(
min: 0,
labelFormatter: (value) => '\$${value.toInt()}k',
),
style: .axis(
.label(
.fontSize(11).color(const Color(0xFF64748B)),
),
).grid(
.showVertical(false).stroke(
.color(const Color(0xFFE2E8F0)).width(1),
),
).series(
.curve(LineCurve.curved).belowArea(
.show(true).color(const Color(0x226366F1)),
),
).frame(.showBorder(false).clip(true)),
onPointTap: (hit) => selectPoint(hit.selectionKey),
);
Point IDs are unique within a series, while bar and segment IDs are unique within their parents. Selection therefore uses hierarchical keys:
LinePointKey? selectedPoint;
BarSelectionKey? selectedBarItem;
LineChart(
series: series,
selectedPoints: {?selectedPoint},
onPointTap: (hit) => selectedPoint = hit.selectionKey,
);
BarChart(
groups: groups,
selectedItems: {?selectedBarItem},
onBarTap: (hit) => selectedBarItem = hit.selectionKey,
);
Use BarSelectionKey.bar(...) or BarSelectionKey.segment(...) when
constructing selection state without an interaction hit.
Styling and behavior #
Presentation precedence is package defaults → chart common style → per-series, bar, segment or slice style → selection presentation. Use consumer-owned tokens and variants when needed; the package does not require a token registry.
- Floating bars set
fromYandtoY; stacked bars useBarSegment. - A donut is a pie with positive
centerRadius; nullable line-pointycreates a gap. - Empty charts and all-zero pies render safely.
- Horizontal bar scaling requires
spaceEvenly,spaceAround, orspaceBetween. selectedSliceRadiusOffsetadds to the resolved per-slice radius. Unset keeps the 8 logical-pixel default; zero disables expansion.- Unset slice radius is 80 logical pixels, reduced when the pie or donut and the selected-slice expansion would not fit its box.
- Axis label builders, badges and tooltips accept Flutter widgets. Hits carry public IDs, values, local position and pointer events, not backend indices.
Axes and values #
Without axis configuration:
- Ticks fall on a round step (1, 2 or 5 times a power of ten) sized to the plot, and never on fractions when every value on the axis is a whole number.
- A value-axis bound left to the data is rounded out to that step, so the first and last ticks are round numbers too. A line chart's x bounds are not rounded.
- A bound, explicit or derived, is labelled only when it falls on a tick. Pass
minIncluded: trueormaxIncluded: trueto label an off-tick bound;falsenever labels it. - Grid lines follow the axis step unless the grid style sets an interval.
- An unstyled value axis widens its label space to fit its ticks on one line. Crowded bar category labels are thinned to every n-th label.
Explicit min, max and interval always win; a bound left open rounds out
to an explicit interval. Tooltips, bar labels and the semantics summary
write values without a trailing .0; pass valueFormatter for currency or
units. Line and bar charts fall back to the y-axis labelFormatter when it
returns non-blank text.
The line hover indicator draws the series marker in its selected state over a guide line. The guide uses the grid stroke when one is styled, and otherwise a 1px slate line a shade darker than the default grid.
Animation ownership #
Choose one owner: Mix .animate(...) for presentation changes, or
ChartDataTransition for numeric data updates with a stable styler. Leave the
other transition disabled. Data interpolation requires unchanged ID order and
drawable topology; insertion, deletion, reordering or value↔gap changes snap.
MediaQuery.disableAnimations forces immediate output.
Accessibility and limits #
Each chart exposes one root semantics node. Provide semanticsLabel; otherwise
an ordered summary is built from labels and formatters. semanticsValue
overrides the value, and excludeFromSemantics supports decorative charts.
Per-mark spatial semantics and keyboard navigation are not implemented because
the renderer does not expose stable mark geometry.
Scatter, radar, candlestick, heatmap, gauge, treemap, annotations, error bars,
3D and arbitrary mark painters are outside the current model. Put gradient
surrounds on an outer Mix Box.
Integration and releases #
The gallery and playground contain bar, pie, token, interaction, label and tooltip examples. JSON consumers opt into mix_chart_protocol; rendering apps do not need it.
Publishing uses mix_chart-v<version> tags and requires maintainer action.
Confirm pub.dev publisher ownership before relying on OIDC. The
Protocol publishing guide explains
shared OIDC prerequisites; its package name and tag prefix are Protocol-specific.
BSD 3-Clause. See LICENSE.
Pie labels with default placement use the full label and value when they fit,
then the value alone, and finally no in-slice text for very narrow slices.
Tooltips and semantics retain the full information. Explicit labelPosition
keeps caller-controlled placement. Text is measured at the current text scale.
