flutter-chart

# Flutter Chart with Graphic A skill for helping users build data visualizations in Flutter using the [Graphic](https://pub.dev/packages/graphic) library — a Grammar of Graphics-based charting library. ## When to Use - User wants to create any type of chart in Flutter (bar, line, area, pie, scatter, heatmap, etc.) - User needs help configuring chart appearance, interactivity, or animations - User asks about Graphic library APIs or usage patterns - User wants to convert data into visual representations - **User wants to create custom, bespoke visualizations** — Graphic's customization system is its most powerful feature and a key strength of AI-assisted development ## Why Custom Charts? Standard chart types (bar, line, pie) only cover a fraction of data visualization needs. Graphic is built on Grammar of Graphics theory, which means **every visual layer is independently customizable**: - **Custom Shapes** — Render any geometry (triangles, lollipops, arrows, gauges, bullet charts, sparklines, etc.) - **Custom Tooltips** — Fully custom interactive overlays with any layout - **Custom Annotations** — Draw any graphics at data or absolute positions - **Custom Encoders** — Map data to visuals using arbitrary logic - **Custom Modifiers** — Define custom collision/arrangement behavior This makes AI-assisted development especially valuable: the AI can write custom shape renderers, coordinate math, and drawing code that would be tedious to implement manually. **Always consider customization when the user's requirements don't perfectly match a standard chart type.** See `references/customization.md` for the comprehensive customization guide. ## Quick Start ### Installation Add to `pubspec.yaml`: ```yaml dependencies: graphic: ^latest ``` Then run `flutter pub get`. ### Import ```dart import 'package:graphic/graphic.dart'; ``` ### Minimal Example ```dart Chart( data: [ {'category': 'A', 'value': 10}, {'category': 'B', 'value': 20}, {'category': 'C', 'value': 15}, ], variables: { 'category': Variable( accessor: (Map map) => map['category'] as String, ), 'value': Variable( accessor: (Map map) => map['value'] as num, ), }, marks: [IntervalMark()], axes: [Defaults.horizontalAxis, Defaults.verticalAxis], ) ``` ## Core Concepts Graphic follows the **Grammar of Graphics** theory. A chart is composed of independent, declarative layers: ``` data → Variable → Scale → Encode → Mark → Shape → Render ``` Everything is configured through the single `Chart<D>` widget constructor. There are no imperative APIs — all configuration is declarative. ### The Chart Widget `Chart<D>` is the only public widget. The type parameter `D` is the data item type. Key parameters: | Parameter | Type | Purpose | |-----------|------|---------| | `data` | `List<D>` | **Required.** Data to visualize | | `variables` | `Map<String, Variable<D, dynamic>>` | **Required.** How to extract values from data | | `marks` | `List<Mark>` | **Required.** Geometry types to render | | `coord` | `Coord?` | Coordinate system (default: `RectCoord`) | | `axes` | `List<AxisGuide>?` | Axis configuration | | `tooltip` | `TooltipGuide?` | Tooltip on interaction | | `crosshair` | `CrosshairGuide?` | Crosshair on interaction | | `annotations` | `List<Annotation>?` | Static annotations | | `selections` | `Map<String, Selection>?` | Named selection behaviors | | `transforms` | `List<VariableTransform>?` | Data transforms (filter, sort, proportion) | | `padding` | `EdgeInsets Function(Size)?` | Padding around the plot area | | `transition` | — | Set on each Mark, not on Chart | See `references/chart-widget.md` for full parameter details. ### Variables Variables define how raw data maps to abstract values: ```dart variables: { 'date': Variable( accessor: (MyData d) => d.date, scale: TimeScale(formatter: (t) => DateFormat.MMMd().format(t)), ), 'value': Variable( accessor: (MyData d) => d.value, scale: LinearScale(min: 0), ), } ``` Each variable can have a `Scale` that controls domain-to-range mapping. See `references/scales.md`. ### Marks Marks are the geometric elements that represent data: | Mark | Use Case | Default Shape | |------|----------|---------------| | `IntervalMark` | Bar charts, histograms, pie charts | `RectShape` | | `LineMark` | Line charts, sparklines | `BasicLineShape` | | `AreaMark` | Area charts, stream graphs | `BasicAreaShape` | | `PointMark` | Scatter plots, bubble charts | `CircleShape` | | `PolygonMark` | Heatmaps, treemaps | `HeatmapShape` | | `CustomMark` | Candlestick, custom shapes | Any `Shape` | See `references/marks.md` for parameters and `references/shapes.md` for shape options. ### Encodes (Aesthetic Mappings) Encodes map data values to visual properties. Every encode supports three modes: 1. **Fixed value**: `ColorEncode(value: Colors.blue)` 2. **Variable mapping**: `ColorEncode(variable: 'type', values: Defaults.colors10)` 3. **Custom function**: `ColorEncode(encoder: (tuple) => myColorLogic(tuple))` Available encodes: `ColorEncode`, `SizeEncode`, `ShapeEncode`, `LabelEncode`, `GradientEncode`, `ElevationEncode`. See `references/encodes.md` for details. ### Position Algebra (Varset) Position is specified using `Varset` algebra with three operators: | Operator | Name | Effect | |----------|------|--------| | `*` | Cross | Assigns variables to different dimensions (x, y) | | `+` | Blend | Combines variables on the same dimension | | `/` | Nest | Groups data by a variable | ```dart // x=date, y=value, grouped by type position: Varset('date') * Varset('value') / Varset('type') ``` See `references/algebra.md` for details. ### Coordinates - **`RectCoord`** — Cartesian coordinates (default). Supports `transposed`, `horizontalRange`, `verticalRange`. - **`PolarCoord`** — Polar/radial coordinates for pie charts, radar charts, rose charts. Supports `startAngle`, `endAngle`, `startRadius`, `endRadius`. See `references/coordinates.md` for details. ### Interaction Define named selections and use them in encode updaters: ```dart selections: { 'tap': PointSelection(dim: Dim.x), }, marks: [ IntervalMark( color: ColorEncode( value: Colors.blue, updaters: { 'tap': { true: (color) => color.withAlpha(255), // selected false: (color) => color.withAlpha(100), // not selected }, }, ), ), ], ``` See `references/selections.md` for selection types and gesture configuration. ### Modifiers Modifiers handle geometry collision/arrangement: - `StackModifier()` — Stack elements (stacked bar, stacked area) - `DodgeModifier()` — Place side by side (grouped bar) - `JitterModifier()` — Random scatter (strip plot) - `SymmetricModifier()` — Center symmetrically (stream graph) See `references/modifiers.md`. ### Animation ```dart IntervalMark( transition: Transition(duration: Duration(seconds: 1), curve: Curves.easeOut), entrance: {MarkEntrance.y}, // Animate from y=0 tag: (tuple) => tuple['id'].toString(), // Element matching for transitions ) ``` See `references/animation.md`. ## Common Chart Recipes ### Bar Chart ```dart marks: [IntervalMark()] coord: RectCoord() // default ``` ### Horizontal Bar Chart ```dart marks: [IntervalMark()] coord: RectCoord(transposed: true) ``` ### Grouped Bar Chart ```dart marks: [ IntervalMark( position: Varset('x') * Varset('y') / Varset('group'), color: ColorEncode(variable: 'group', values: Defaults.colors10), modifiers: [DodgeModifier()], ), ] ``` ### Stacked Bar Chart ```dart marks: [ IntervalMark( position: Varset('x') * Varset('y') / Varset('group'), color: ColorEncode(variable: 'group', values: Defaults.colors10), modifiers: [StackModifier()], ), ] ``` ### Line Chart ```dart marks: [LineMark()] ``` ### Smooth Line Chart ```dart marks: [ LineMark(shape: ShapeEncode(value: BasicLineShape(smooth: true))), ] ``` ### Area Chart ```dart marks: [AreaMark()] ``` ### Pie Chart ```dart transforms: [Proportion(variable: 'value', as: 'percent')], marks: [ IntervalMark( position: Varset('percent') / Varset('category'), color: ColorEncode(variable: 'category', values: Defaults.colors10), modifiers: [StackModifier()], ), ], coord: PolarCoord(transposed: true, dimCount: 1), ``` ### Scatter Plot ```dart marks: [ PointMark( size: SizeEncode(variable: 'magnitude', values: [2, 20]), color: ColorEncode(variable: 'type', values: Defaults.colors10), ), ] ``` ### Rose Chart ```dart marks: [IntervalMark(color: ColorEncode(variable: 'name', values: Defaults.colors10))], coord: PolarCoord(startRadius: 0.15), ``` See `references/examples.md` for more complete examples. ## Custom Chart Development Graphic's greatest strength is its **fully customizable rendering pipeline**. When standard chart types don't meet requirements, create custom visualizations by implementing your own shapes, tooltips, annotations, and encoders. ### Custom Shapes — The Core Extension Point Create entirely new chart geometries by extending a Shape base class and implementing `drawGroupPrimitives()`: ```dart class LollipopShape extends IntervalShape { LollipopShape({this.radius = 6}); final double radius; @override List<MarkElement> drawGroupPrimitives( List<Attributes> group, CoordConv coord, Offset origin, ) { final rst = <MarkElement>[]; for (var item in group) { if (item.position.any((p) => !p.dy.isFinite)) continue; final style = getPaintStyle(item, false, 0, null, null); final base = coord.convert(item.position[0]); final tip = coord.convert(item.position[1]); // Stem line rst.add(PolylineElement( points: [base, tip], style: PaintStyle(strokeColor: style.fillColor, strokeWidth: 2), tag: item.tag, )); // Circle head rst.add(CircleElement( center: tip, radius: radius, style: style, tag: item.tag, )); } return rst; } @override bool equalTo(Object other) => other is LollipopShape && radius == other.radius; } ``` **Available base classes**: `IntervalShape`, `LineShape`, `AreaShape`, `PointShape`, `PolygonShape` **Available drawing primitives**: `RectElement`, `CircleElement`, `PolygonElement`, `PolylineElement`, `ArcElement`, `SectorElement`, `SplineElement`, `PathElement`, `LabelElement`, `GroupElement` ### Custom Tooltip Renderer ```dart tooltip: TooltipGuide( renderer: (Size size, Offset anchor, Map<int, Tuple> selected) { final t = selected.values.first; return [ RectElement( rect: Rect.fromCenter(center: anchor, width: 100, height: 36), borderRadius: BorderRadius.circular(6), style: PaintStyle(fillColor: Colors.black87, elevation: 4), ), LabelElement( text: '${t['name']}: ${t['value']}', anchor: anchor, style: LabelStyle( textStyle: TextStyle(color: Colors.white, fontSize: 12), align: Alignment.center, ), ),