Flutter Chart with Graphic

A skill for helping users build data visualizations in Flutter using the 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

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:

Fixed value:
```
ColorEncode(value: Colors.blue)
```

Variable mapping:

ColorEncode(variable: 'type', values: Defaults.colors10)

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,
        ),
      ),
    ];
  },
)

Custom Encoder Functions

Every encode supports arbitrary logic via

encoder

dart

color: ColorEncode(encoder: (tuple) {
  final v = tuple['value'] as num;
  return v > 100 ? Colors.red : v > 50 ? Colors.orange : Colors.green;
}),

label: LabelEncode(encoder: (tuple) => Label(
  '${tuple['value']}%',
  LabelStyle(textStyle: TextStyle(
    fontSize: (tuple['value'] as num) > 50 ? 14 : 10,
    fontWeight: FontWeight.bold,
  )),
)),

Key Classes for Custom Development

Class	Purpose
`Attributes`	Encoded data element — contains `position` , `color` , `gradient` , `size` , `label` , `tag`
`CoordConv`	Converts normalized [0,1] positions to canvas pixels via `convert()` / `invert()`
`PaintStyle`	Full paint specification — fill, stroke, gradient, dash, elevation, shadow
`MarkElement`	Drawing primitives — the building blocks for custom rendering
`getPaintStyle()`	Utility to extract `PaintStyle` from `Attributes`

See
references/customization.md
for the comprehensive guide including coordinate handling, all drawing primitives, custom annotations, custom modifiers, and best practices.

Guides & Annotations

Axes: Use

Defaults.horizontalAxis

Defaults.verticalAxis

for quick setup, or customize with

AxisGuide

. See

references/guides.md

Tooltip:
```
TooltipGuide()
```
with optional custom renderer. See
```
references/guides.md
```
.
Crosshair:
```
CrosshairGuide()
```
. See
```
references/guides.md
```
.

Annotations:

LineAnnotation

RegionAnnotation

TagAnnotation

CustomAnnotation

. See

references/annotations.md

Styling

```
PaintStyle
```
— Fill/stroke colors, gradients, dash patterns, shadows
```
LabelStyle
```
— Text style, alignment, rotation, offset
```
Defaults
```
— Built-in color palettes (
```
colors10
```
,
```
colors20
```
), preset axes, default styles

See

references/styling.md

Event Streams

Charts expose

StreamController

parameters for external event coupling:

```
gestureStream
```
— Send/receive gesture events
```
resizeStream
```
— React to resize events
```
changeDataStream
```
— React to data change events
```
selectionStream
```
(on Mark) — Programmatically set selections

Dynamic Data

Simply update the

data

parameter via

setState()

dart

setState(() {
  data = newData;
});

The chart automatically re-renders with transition animations when

tag

is set.

Important Notes

The
```
Chart
```
widget is the only public widget — all configuration is via its constructor
```
color
```
and
```
gradient
```
on encodes are mutually exclusive

Pie charts require

Proportion

transform +

PolarCoord(transposed: true, dimCount: 1)

Use
```
tag
```
on marks for smooth transition animations between data states
```
Varset
```
```
/
```
(nest) operator is required for grouping (multi-series, stacked, dodged)
Function-typed properties are always treated as "unchanged" in equality comparisons

Reference Files

File	Content
`references/customization.md`	Custom chart development guide — shapes, tooltips, annotations, encoders, drawing primitives
`references/chart-widget.md`	Full Chart widget parameter reference
`references/marks.md`	All mark types and parameters
`references/encodes.md`	Aesthetic encoding reference
`references/shapes.md`	Shape types for each mark
`references/scales.md`	Scale types and configuration
`references/coordinates.md`	Coordinate system reference
`references/guides.md`	Axis, Tooltip, Crosshair reference
`references/annotations.md`	Annotation types reference
`references/selections.md`	Selection and interaction reference
`references/modifiers.md`	Geometry modifier reference
`references/transforms.md`	Data transform reference
`references/algebra.md`	Varset algebra reference
`references/animation.md`	Transition and entrance animation reference
`references/styling.md`	PaintStyle, LabelStyle, Defaults reference
`references/examples.md`	Complete chart examples

When answering user questions, read the source code for the most accurate and up-to-date API details. The library uses extensive code comments as documentation. Key source directories:

```
lib/src/chart/
```
— Chart widget
```
lib/src/mark/
```
— Mark types
```
lib/src/encode/
```
— Encode types
```
lib/src/shape/
```
— Shape implementations
```
lib/src/scale/
```
— Scale types
```
lib/src/coord/
```
— Coordinate systems
```
lib/src/guide/
```
— Axis, Tooltip, Crosshair, Annotations
```
lib/src/interaction/
```
— Selection, gestures
```
lib/src/variable/
```
— Variable and transforms
```
lib/src/algebra/
```
— Varset algebra
```
lib/src/common/
```
— Shared types (Label, PaintStyle, Defaults)

flutter-chart

NPX Install

Tags

SKILL.md Content

Flutter Chart with Graphic

When to Use

Why Custom Charts?

Quick Start

Installation

Import

Minimal Example

Core Concepts

The Chart Widget

Variables

Marks

Encodes (Aesthetic Mappings)

Position Algebra (Varset)

Coordinates

Interaction

Modifiers

Animation

Common Chart Recipes

Bar Chart

Horizontal Bar Chart

Grouped Bar Chart

Stacked Bar Chart

Line Chart

Smooth Line Chart

Area Chart

Pie Chart

Scatter Plot

Rose Chart

Custom Chart Development

Custom Shapes — The Core Extension Point

Custom Tooltip Renderer

Custom Encoder Functions

Key Classes for Custom Development

Guides & Annotations

Styling

Event Streams

Dynamic Data

Important Notes

Reference Files