https://github.com/rudi-q/cristalyse
High-performance data visualization library for Flutter with native rendering and cross-platform support
https://github.com/rudi-q/cristalyse
bar-chart business-intelligence charts dart dashboard data-visualization dual-axis flutter ggplot2 grammar-of-graphics heatmap interactive-charts line-chart native-rendering pie-chart plotting scatter-plot stacked-bars
Last synced: 4 months ago
JSON representation
High-performance data visualization library for Flutter with native rendering and cross-platform support
- Host: GitHub
- URL: https://github.com/rudi-q/cristalyse
- Owner: rudi-q
- License: mit
- Created: 2025-06-08T09:12:11.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-02-16T14:04:42.000Z (4 months ago)
- Last Synced: 2026-02-16T21:44:34.913Z (4 months ago)
- Topics: bar-chart, business-intelligence, charts, dart, dashboard, data-visualization, dual-axis, flutter, ggplot2, grammar-of-graphics, heatmap, interactive-charts, line-chart, native-rendering, pie-chart, plotting, scatter-plot, stacked-bars
- Language: Dart
- Homepage: https://docs.cristalyse.com
- Size: 21.1 MB
- Stars: 63
- Watchers: 1
- Forks: 6
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
**The grammar of graphics visualization library that Flutter developers have been waiting for.**
[](https://flutter.dev/)
[](https://dart.dev/)
[](https://pub.dev/packages/cristalyse)
[](https://pub.dev/packages/cristalyse/score)
[](https://pub.dev/packages/cristalyse/score)
[](https://pub.dev/packages/cristalyse/score)
[](https://opensource.org/licenses/MIT)
[](https://flutter.dev/)
[-145261?logo=webassembly&logoColor=white)](https://flutter.dev/)
[](https://flutter.dev/)
[](https://flutter.dev/)
[](https://flutter.dev/)
[](https://flutter.dev/)
[](https://flutter.dev/)
[](https://docs.cristalyse.com/cristalyse-mcp-server#claude-code-cli)
[](https://docs.cristalyse.com/cristalyse-mcp-server#ai-code-editor-cursor%2C-windsurf%2C-warp)
[](https://docs.cristalyse.com/cristalyse-mcp-server#ai-code-editor-cursor%2C-windsurf%2C-warp)
[](https://docs.cristalyse.com/cristalyse-mcp-server#ai-code-editor-cursor%2C-windsurf%2C-warp)
> Finally, create beautiful data visualizations in Flutter without fighting against chart widgets or settling for web-based solutions.
---
Visit our complete documentation for step-by-step guides, interactive examples,
and everything you need to master data visualization in Flutter.
Comprehensive guides, examples, and API reference
---
## 🤖 AI-Powered Development
**Cristalyse Docs now has MCP server** which you can connect to your AI coding assistant (Cursor, Windsurf, Warp, Claude) for instant access to documentation while you code.
---
## ✨ Why Cristalyse?
**Stop wrestling with limited chart libraries.** Cristalyse brings the power of grammar of graphics (think ggplot2) to Flutter with buttery-smooth 60fps animations and true cross-platform deployment.
- 🎨 **Grammar of Graphics API** - Familiar syntax if you've used ggplot2 or plotly
- 🚀 **Native 60fps Animations** - Leverages Flutter's rendering engine, not DOM manipulation
- 📱 **True Cross-Platform** - One codebase → Mobile, Web, Desktop, all looking identical
- ⚡ **GPU-Accelerated Performance** - Handle large datasets without breaking a sweat
- 🎯 **Flutter-First Design** - Seamlessly integrates with your existing Flutter apps
- 📊 **Dual Y-Axis Support** - Professional business dashboards with independent left/right scales
- 📈 **Advanced Bar Charts** - Grouped, stacked, and horizontal variations with smooth animations
- 🫧 **Bubble Charts** - Multi-dimensional data visualization with size, color, and position encoding
- 👆 **Interactive Charts** - Engage users with tooltips, hover effects, and click events.
### See What You Can Build
Interactive scatter plots with smooth animations and multi-dimensional data mapping
Progressive line drawing with customizable themes and multi-series support
## 🎯 Perfect For
- **Flutter developers** building data-driven apps who need more than basic chart widgets
- **Data scientists** who want to deploy interactive visualizations to mobile without learning Swift/Kotlin
- **Enterprise teams** building dashboards that need consistent UX across all platforms
- **Business analysts** creating professional reports with dual Y-axis charts and advanced visualizations
- **Product managers** tracking performance metrics across multiple dimensions with bubble charts
Build stunning, interactive charts with the power of grammar of graphics
## 🚀 Quick Start
### Installation
```bash
flutter pub add cristalyse
```
That's it! No complex setup, no additional configuration.
### Your First Chart (30 seconds)
```dart
import 'package:cristalyse/cristalyse.dart';
import 'package:flutter/material.dart';
class MyChart extends StatelessWidget {
@override
Widget build(BuildContext context) {
final data = [
{'x': 1, 'y': 2, 'category': 'A'},
{'x': 2, 'y': 3, 'category': 'B'},
{'x': 3, 'y': 1, 'category': 'A'},
{'x': 4, 'y': 4, 'category': 'C'},
];
return CristalyseChart()
.data(data)
.mapping(x: 'x', y: 'y', color: 'category')
.geomPoint(
size: 8.0, // Made points a bit larger to see border clearly
alpha: 0.8,
shape: PointShape.triangle, // Example: use triangles
borderWidth: 1.5, // Example: add a border to points
)
.scaleXContinuous()
.scaleYContinuous()
.theme(ChartTheme.defaultTheme())
.build();
}
}
```
**Result:** A beautiful, animated scatter plot that works identically on iOS, Android, Web, and Desktop.
Your first chart - clean, responsive, and cross-platform
## 💡 Interactive Charts
### Enhanced Panning Behavior
**Real-time data streaming and interactive exploration** with advanced pan controls and coordinate transformation.
```dart
// Basic panning with range callbacks
CristalyseChart()
.data(timeSeriesData)
.mapping(x: 'timestamp', y: 'value')
.geomLine()
.interaction(
pan: PanConfig(
enabled: true,
onPanUpdate: (info) {
// Handle real-time updates based on visible X range
print('Visible X range: ${info.visibleMinX} - ${info.visibleMaxX}');
// Load more data when approaching boundaries
if (info.visibleMaxX! > maxDataTimestamp - bufferTime) {
loadMoreRecentData();
}
},
throttle: Duration(milliseconds: 100), // Prevent overwhelming callbacks
),
)
.build();
// Advanced panning with state management
class PanningChartState extends State {
DateTime? visibleStart;
DateTime? visibleEnd;
@override
Widget build(BuildContext context) {
return Column([
// Range display header
Container(
padding: EdgeInsets.all(8),
child: Text(
visibleStart != null
? 'Range: ${DateFormat('MMM d').format(visibleStart!)} - ${DateFormat('MMM d').format(visibleEnd!)}'
: 'Loading...',
),
),
// Interactive chart
Expanded(
child: CristalyseChart()
.data(chartData)
.mapping(x: 'date', y: 'revenue')
.geomLine()
.onPan((info) {
setState(() {
visibleStart = DateTime.fromMillisecondsSinceEpoch(
(info.visibleMinX! * 1000).round()
);
visibleEnd = DateTime.fromMillisecondsSinceEpoch(
(info.visibleMaxX! * 1000).round()
);
});
// Fetch data for new range
fetchDataForDateRange(visibleStart!, visibleEnd!);
})
.build(),
),
]);
}
}
```
**Panning Features:**
- ✅ **Coordinate Transformation** - Screen pixels to data values automatically
- ✅ **Throttled Callbacks** - Configurable update frequency for performance
- ✅ **Range State Persistence** - Maintains pan position across interactions
- ✅ **Real-time Data Loading** - Perfect for streaming and large datasets
- ✅ **Multi-axis Support** - Independent X and Y panning controls
- ✅ **Touch & Mouse Compatible** - Works on all platforms
Bring your data to life with a fully interactive layer. Add rich tooltips, hover effects, and click/tap events to give users a more engaging experience.
```dart
// Add tooltips and click handlers
CristalyseChart()
.data(salesData)
.mapping(x: 'week', y: 'revenue', color: 'rep')
.geomPoint(size: 8.0)
.interaction(
tooltip: TooltipConfig(
builder: (point) {
// Build a custom widget for the tooltip
final category = point.getDisplayValue('rep');
final value = point.getDisplayValue('revenue');
return Container(
padding: const EdgeInsets.all(8),
decoration: BoxDecoration(
color: Colors.black.withOpacity(0.8),
borderRadius: BorderRadius.circular(4),
),
child: Text(
'$category: \$$value k',
style: const TextStyle(color: Colors.white, fontSize: 12),
),
);
},
),
click: ClickConfig(
onTap: (point) {
// Handle tap event, e.g., show a dialog
print('Tapped on: ${point.data}');
},
),
)
.build();
```
## 🎬 See It In Action
### Animated Scatter Plot
```dart
CristalyseChart()
.data(salesData)
.mapping(x: 'date', y: 'revenue', color: 'region', size: 'deals')
.geomPoint(alpha: 0.7)
.animate(duration: Duration(milliseconds: 800), curve: Curves.elasticOut)
.theme(ChartTheme.defaultTheme())
.build()
```
### Multi-Series Line Chart
```dart
CristalyseChart()
.data(timeSeriesData)
.mapping(x: 'month', y: 'users', color: 'platform')
.geomLine(strokeWidth: 3.0)
.geomPoint(size: 4.0)
.animate(duration: Duration(milliseconds: 1200))
.theme(ChartTheme.darkTheme())
.build()
```
### Combined Visualizations
```dart
CristalyseChart()
.data(analyticsData)
.mapping(x: 'week', y: 'engagement')
.geomLine(strokeWidth: 2.0, alpha: 0.8) // Trend line
.geomPoint(size: 5.0, alpha: 0.9) // Data points
.animate(duration: Duration(milliseconds: 1000), curve: Curves.easeInOutCubic)
.build()
```
## 📊 Advanced Bar Charts
Vertical and horizontal bar charts with staggered animations
### Stacked Bar Charts
```dart
// Perfect for budget breakdowns and composition analysis
CristalyseChart()
.data(revenueData)
.mapping(x: 'quarter', y: 'revenue', color: 'category')
.geomBar(
style: BarStyle.stacked, // Stack segments on top of each other
width: 0.8,
alpha: 0.9,
)
.scaleXOrdinal()
.scaleYContinuous(min: 0)
.theme(ChartTheme.defaultTheme())
.animate(duration: Duration(milliseconds: 1400))
.build()
```
Stacked bars with segment-by-segment progressive animation
### Grouped Bar Charts
```dart
// Compare multiple series side-by-side
CristalyseChart()
.data(productData)
.mapping(x: 'quarter', y: 'revenue', color: 'product')
.geomBar(
style: BarStyle.grouped, // Place bars side-by-side
width: 0.8,
alpha: 0.9,
)
.scaleXOrdinal()
.scaleYContinuous(min: 0)
.theme(ChartTheme.defaultTheme())
.build()
```
Grouped bar charts for comparing multiple series side-by-side
### Horizontal Bar Charts & Coordinate Flipping
**Transform any vertical chart into horizontal** with coordinate system flipping.
```dart
// Horizontal bars - perfect for long category names and rankings
final departmentData = [
{'department': 'Engineering', 'headcount': 45},
{'department': 'Product Management', 'headcount': 25},
{'department': 'Sales & Marketing', 'headcount': 35},
{'department': 'Customer Success', 'headcount': 20},
{'department': 'Human Resources', 'headcount': 15},
];
CristalyseChart()
.data(departmentData)
.mapping(x: 'department', y: 'headcount')
.geomBar(
borderRadius: BorderRadius.circular(4), // Rounded corners
borderWidth: 1.0, // Add borders
alpha: 0.8,
)
.coordFlip() // ✨ Flip to horizontal
.scaleXOrdinal()
.scaleYContinuous(min: 0)
.theme(ChartTheme.defaultTheme())
.build()
// Horizontal grouped bars for comparison
CristalyseChart()
.data(quarterlyData)
.mapping(x: 'quarter', y: 'revenue', color: 'region')
.geomBar(style: BarStyle.grouped)
.coordFlip() // Makes grouped bars horizontal
.legend(position: LegendPosition.bottomRight)
.build()
// Horizontal stacked bars for composition
CristalyseChart()
.data(budgetData)
.mapping(x: 'category', y: 'amount', color: 'subcategory')
.geomBar(style: BarStyle.stacked)
.coordFlip() // Horizontal stacked bars
.scaleYContinuous(
labels: NumberFormat.simpleCurrency().format,
)
.build()
// Horizontal scatter plot - useful for rank vs performance
CristalyseChart()
.data(performanceData)
.mapping(x: 'employee_name', y: 'performance_score', size: 'years_experience')
.geomPoint()
.coordFlip() // Names on Y-axis, scores on X-axis
.build()
```
**Coordinate Flipping Features:**
- ✅ **Universal Transformation** - Works with all chart types (bars, points, lines)
- ✅ **Automatic Axis Swapping** - X becomes Y, Y becomes X seamlessly
- ✅ **Label Readability** - Perfect for long category names
- ✅ **Ranking Visualizations** - Natural top-to-bottom ranking display
- ✅ **Legend Compatibility** - Legends work perfectly with flipped coordinates
- ✅ **Animation Support** - Smooth animations work in both orientations
## 🏷️ Legends
**Automatic legend generation** from your color mappings with flexible positioning and styling.
```dart
// Automatic legend from color mapping
CristalyseChart()
.data(salesData)
.mapping(x: 'month', y: 'revenue', color: 'product') // Color mapping required
.geomBar()
.legend() // ✨ Auto-generates legend from 'product' categories
.build();
// Positioned legend with custom styling
CristalyseChart()
.data(revenueData)
.mapping(x: 'quarter', y: 'amount', color: 'category')
.geomBar(style: BarStyle.stacked)
.legend(
position: LegendPosition.right,
orientation: LegendOrientation.vertical,
backgroundColor: Colors.white.withOpacity(0.9),
textStyle: TextStyle(fontSize: 12, fontWeight: FontWeight.w500),
padding: EdgeInsets.all(12),
)
.build();
// Top horizontal legend for grouped bars
CristalyseChart()
.data(productData)
.mapping(x: 'quarter', y: 'revenue', color: 'product')
.geomBar(style: BarStyle.grouped)
.legend(
position: LegendPosition.topRight,
orientation: LegendOrientation.horizontal,
spacing: 16.0,
itemSpacing: 8.0,
)
.build();
```
**Legend Features:**
- ✅ **Auto-Generation** - Automatically creates legends from color mappings
- ✅ **Flexible Positioning** - Top, bottom, left, right, and corner positions
- ✅ **Custom Styling** - Background, text style, padding, and spacing control
- ✅ **Smart Layouts** - Automatic horizontal/vertical orientation based on position
- ✅ **Multi-Chart Support** - Works with all chart types that use color mapping
- ✅ **Responsive Design** - Adapts to container constraints
### Legend Positions
```dart
// Available positions
LegendPosition.top
LegendPosition.bottom
LegendPosition.left
LegendPosition.right
LegendPosition.topLeft
LegendPosition.topRight
LegendPosition.bottomLeft
LegendPosition.bottomRight
```
## 🥧 Pie Charts and Donut Charts
**Perfect for part-to-whole relationships** - visualize market share, revenue distribution, user demographics, and any categorical data where proportions matter.
### Basic Pie Chart
```dart
// Revenue Distribution by Platform
CristalyseChart()
.data([
{'category': 'Mobile', 'revenue': 45.2},
{'category': 'Desktop', 'revenue': 32.8},
{'category': 'Tablet', 'revenue': 22.0},
])
.mappingPie(value: 'revenue', category: 'category')
.geomPie(
outerRadius: 120.0,
strokeWidth: 2.0,
strokeColor: Colors.white,
showLabels: true,
showPercentages: true,
)
.theme(ChartTheme.defaultTheme())
.animate(
duration: Duration(milliseconds: 1200),
curve: Curves.elasticOut,
)
.build()
```
### Donut Charts
```dart
// User Analytics with Donut Visualization
CristalyseChart()
.data(userPlatformData)
.mappingPie(value: 'users', category: 'platform')
.geomPie(
innerRadius: 60.0, // Creates donut hole
outerRadius: 120.0,
strokeWidth: 3.0,
strokeColor: Colors.white,
showLabels: true,
showPercentages: false, // Show actual values
)
.theme(ChartTheme.darkTheme())
.animate(
duration: Duration(milliseconds: 1500),
curve: Curves.easeOutBack,
)
.build()
```
### Advanced Pie Charts with Custom Styling
```dart
// Market Share Analysis with Exploded Slices
CristalyseChart()
.data(marketShareData)
.mappingPie(value: 'market_share', category: 'product')
.geomPie(
outerRadius: 150.0,
strokeWidth: 2.0,
strokeColor: Colors.white,
showLabels: true,
showPercentages: true,
explodeSlices: true, // Explode slices for emphasis
explodeDistance: 15.0,
labelRadius: 180.0, // Position labels further out
labelStyle: TextStyle(
fontSize: 12,
fontWeight: FontWeight.bold,
color: Colors.black87,
),
)
.theme(ChartTheme.solarizedLightTheme())
.build()
}
```
## 🔥 Heat Map Charts
**Perfect for 2D data visualization** - visualize correlations, performance matrices, time-based patterns, and any data with two categorical dimensions and a continuous value.
### Business Performance Heat Map
```dart
// Sales Performance by Region and Month
CristalyseChart()
.data([
{'month': 'Jan', 'region': 'North', 'sales': 85},
{'month': 'Jan', 'region': 'South', 'sales': 62},
{'month': 'Feb', 'region': 'North', 'sales': 93},
{'month': 'Feb', 'region': 'South', 'sales': 78},
// ... more data
])
.mappingHeatMap(x: 'month', y: 'region', value: 'sales')
.geomHeatMap(
cellSpacing: 2.0,
cellBorderRadius: BorderRadius.circular(4),
colorGradient: [Colors.red, Colors.yellow, Colors.green],
interpolateColors: true,
showValues: true,
valueFormatter: (value) => '${value.toInt()}%',
)
.theme(ChartTheme.defaultTheme())
.animate(duration: Duration(milliseconds: 1500))
.build()
```
### System Monitoring Heat Map
```dart
// Server Response Times by Hour and Service
CristalyseChart()
.data(metricsData)
.mappingHeatMap(x: 'hour', y: 'service', value: 'response_time')
.geomHeatMap(
minValue: 0,
maxValue: 100,
nullValueColor: Colors.grey.shade200,
cellAspectRatio: 1.0,
showValues: true,
valueTextStyle: TextStyle(
fontSize: 10,
fontWeight: FontWeight.bold,
),
)
.theme(ChartTheme.darkTheme())
.build()
```
### Correlation Matrix
```dart
// Feature Correlation Analysis
CristalyseChart()
.data(correlationData)
.mappingHeatMap(x: 'variable1', y: 'variable2', value: 'correlation')
.geomHeatMap(
minValue: -1.0,
maxValue: 1.0,
colorGradient: [
Colors.blue.shade800, // Strong negative correlation
Colors.white, // No correlation
Colors.red.shade800, // Strong positive correlation
],
interpolateColors: true,
cellSpacing: 1.0,
showValues: true,
valueFormatter: (value) => value.toStringAsFixed(2),
)
.build()
```
## 🎯 Dual Y-Axis Charts
**Perfect for business dashboards** - correlate volume metrics with efficiency metrics on independent scales.
```dart
// Revenue vs Conversion Rate - The Classic Business Dashboard
CristalyseChart()
.data(businessData)
.mapping(x: 'month', y: 'revenue') // Primary Y-axis (left)
.mappingY2('conversion_rate') // Secondary Y-axis (right)
.geomBar(
yAxis: YAxis.primary, // Revenue bars use left axis
alpha: 0.7,
)
.geomLine(
yAxis: YAxis.secondary, // Conversion line uses right axis
strokeWidth: 3.0,
color: Colors.orange,
)
.geomPoint(
yAxis: YAxis.secondary, // Points on conversion line
size: 8.0,
color: Colors.orange,
)
.scaleXOrdinal()
.scaleYContinuous(min: 0) // Left axis: Revenue ($k)
.scaleY2Continuous(min: 0, max: 100) // Right axis: Percentage (%)
.theme(ChartTheme.defaultTheme())
.build()
```
Dual axis charts for correlating two different metrics on independent scales
### More Dual Y-Axis Examples
```dart
// Sales Volume vs Customer Satisfaction
CristalyseChart()
.data(salesData)
.mapping(x: 'week', y: 'sales_volume')
.mappingY2('satisfaction_score')
.geomBar(yAxis: YAxis.primary) // Volume bars
.geomLine(yAxis: YAxis.secondary) // Satisfaction trend
.scaleY2Continuous(min: 1, max: 5) // Rating scale
.build();
// Website Traffic vs Bounce Rate
CristalyseChart()
.data(analyticsData)
.mapping(x: 'date', y: 'page_views')
.mappingY2('bounce_rate')
.geomArea(yAxis: YAxis.primary, alpha: 0.3) // Traffic area
.geomLine(yAxis: YAxis.secondary, strokeWidth: 2.0) // Bounce rate line
.scaleY2Continuous(min: 0, max: 100) // Percentage scale
.build();
```
## 🫧 Bubble Charts
**Perfect for market analysis and multi-dimensional data** - visualize three variables simultaneously with position and size encoding.
```dart
// Market Performance Analysis
CristalyseChart()
.data([
{'company': 'TechCorp', 'revenue': 250, 'customers': 180, 'marketShare': 28},
{'company': 'StartupX', 'revenue': 85, 'customers': 120, 'marketShare': 12},
{'company': 'MidSize', 'revenue': 150, 'customers': 160, 'marketShare': 18},
])
.mapping(
x: 'revenue', // Revenue on X-axis
y: 'customers', // Customer count on Y-axis
size: 'marketShare', // Market share determines bubble size
color: 'category' // Color by company category
)
.geomBubble(
minSize: 8.0, // Minimum bubble radius
maxSize: 25.0, // Maximum bubble radius
alpha: 0.7, // Semi-transparent bubbles
borderWidth: 2.0, // Border for definition
showLabels: true, // Show value labels
labelFormatter: (value) => '${value}%', // Custom label format
)
.scaleXContinuous()
.scaleYContinuous()
.theme(ChartTheme.defaultTheme())
.animate(duration: Duration(milliseconds: 1200))
.build()
```
Perfect for analyzing relationships between three continuous variables
### Bubble Chart Features
- ✅ **Size Encoding** - Third dimension mapped to bubble radius
- ✅ **Color Grouping** - Categorical data with distinct colors
- ✅ **Custom Labels** - Show formatted values on bubbles
- ✅ **Interactive Tooltips** - Rich hover information
- ✅ **Dual Y-Axis Support** - Use with secondary scales
- ✅ **Animation Support** - Smooth entrance effects
## 🔥 Current Features
### ✅ Chart Types
- **Scatter plots** with size and color mapping
- **Line charts** with multi-series support and progressive drawing
- **Area charts** with smooth fills and multi-series transparency
- **Bar charts** (vertical, horizontal, grouped, stacked) with smooth animations
- **Pie charts and donut charts** with exploded slices and smart label positioning
- **Heat map charts** with customizable color gradients and 2D data visualization
- **Bubble charts** with 3D data visualization and size encoding
- **Dual Y-axis charts** for professional business dashboards
- **Combined visualizations** (bars + lines, points + lines, etc.)
### ✅ Advanced Features
- **Grammar of Graphics API** - Familiar ggplot2-style syntax
- **Smooth 60fps animations** with customizable timing and curves
- **Dual Y-axis support** with independent scales and data routing
- **Multiple built-in themes** (Light, Dark, Solarized Light/Dark)
- **Custom color palettes** for brand-specific category mapping
- **Automatic legend generation** with flexible positioning and styling
- **Advanced label formatting** with NumberFormat integration
- **Interactive panning** with real-time data streaming support
- **Responsive scaling** for all screen sizes
- **High-DPI support** for crisp visuals
### ✅ Data Handling
- **Flexible data formats** - List>
- **Mixed data types** - Automatic type detection and conversion
- **Missing value handling** - Graceful degradation for null/invalid data
- **Large dataset support** - Optimized for 1000+ data points
- **Real-time updates** - Smooth transitions when data changes
- **Multi-dimensional mapping** - X, Y, size, color encoding simultaneously
## 📸 Chart Export
**Export your charts as professional-quality SVG vector graphics** for reports, presentations, and documentation.
```dart
// Simple SVG export
final result = await chart.exportAsSvg(
width: 1200,
height: 800,
filename: 'sales_report',
);
print('Chart saved to: ${result.filePath}');
// Advanced configuration
final config = ExportConfig(
width: 1920,
height: 1080,
format: ExportFormat.svg,
filename: 'high_res_dashboard',
);
final result = await chart.export(config);
```
**SVG Export Features:**
- ✅ **Scalable Vector Graphics** - Infinite zoom without quality loss
- ✅ **Professional Quality** - Perfect for presentations and reports
- ✅ **Small File Sizes** - Efficient for web and print
- ✅ **Design Software Compatible** - Editable in Figma, Adobe Illustrator, etc.
- ✅ **Cross-Platform Reliable** - Works consistently on all platforms
- ✅ **Automatic File Management** - Saves to Documents directory with timestamp
## 🎯 Real-World Examples
### Sales Dashboard
```dart
Widget buildRevenueTrend() {
return CristalyseChart()
.data(monthlyRevenue)
.mapping(x: 'month', y: 'revenue', color: 'product_line')
.geomLine(strokeWidth: 3.0)
.geomPoint(size: 5.0)
.scaleXContinuous()
.scaleYContinuous(min: 0)
.theme(ChartTheme.solarizedDarkTheme()) // Use Solarized Dark theme
.animate(duration: Duration(milliseconds: 1500))
.build();
}
```
### User Analytics
```dart
Widget buildEngagementScatter() {
return CristalyseChart()
.data(userMetrics)
.mapping(x: 'session_length', y: 'pages_viewed',
color: 'user_type', size: 'revenue')
.geomPoint(alpha: 0.6)
.scaleXContinuous()
.scaleYContinuous()
.theme(isDarkMode ? ChartTheme.darkTheme() : ChartTheme.defaultTheme())
.animate(duration: Duration(milliseconds: 800), curve: Curves.elasticOut)
.build();
}
```
### Market Share Analysis
```dart
Widget buildMarketSharePie() {
return CristalyseChart()
.data(marketData)
.mappingPie(value: 'market_share', category: 'product')
.geomPie(
outerRadius: 140.0,
strokeWidth: 3.0,
strokeColor: Colors.white,
showLabels: true,
showPercentages: true,
explodeSlices: true, // Emphasize key segments
explodeDistance: 12.0,
labelStyle: TextStyle(
fontSize: 11,
fontWeight: FontWeight.w600,
),
)
.theme(ChartTheme.defaultTheme())
.animate(duration: Duration(milliseconds: 1200), curve: Curves.elasticOut)
.build();
}
```
### Business Intelligence Dashboard
```dart
// Revenue bars + profit margin line on dual Y-axis
CristalyseChart()
.data(kpiData)
.mapping(x: 'quarter', y: 'revenue')
.mappingY2('profit_margin')
.geomBar(yAxis: YAxis.primary, style: BarStyle.stacked)
.geomLine(yAxis: YAxis.secondary, color: Colors.green)
.scaleYContinuous(labels: NumberFormat.simpleCurrency().format)
.scaleY2Continuous(labels: (v) => '${v.toStringAsFixed(1)}%')
.legend()
.build();
```
### Advanced Multi-Geometry Dashboard
```dart
// Combined area + line + bubbles with dual Y-axis
CristalyseChart()
.data(performanceData)
.mapping(x: 'month', y: 'revenue', size: 'team_size', color: 'department')
.mappingY2('efficiency')
.geomArea(yAxis: YAxis.primary, alpha: 0.2)
.geomLine(yAxis: YAxis.primary, strokeWidth: 3.0)
.geomBubble(yAxis: YAxis.primary, minSize: 5.0, maxSize: 15.0)
.geomLine(yAxis: YAxis.secondary, color: Colors.orange)
.scaleYContinuous(labels: NumberFormat.compact().format)
.scaleY2Continuous(labels: (v) => '${v.round()}%')
.legend()
.interaction(pan: PanConfig(enabled: true))
.build();
```
## 💡 Why Not Just Use...?
| Alternative | Why Cristalyse is Better |
|-------------|---------------------------|
| **fl_chart** | Grammar of graphics API vs basic chart widgets. Dual Y-axis support vs single axis limitation. |
| **charts_flutter** | Active development vs deprecated. Stacked bars and advanced features vs basic charts. |
| **Web charts (plotly.js)** | Native performance vs DOM rendering. True mobile deployment vs responsive web. |
| **Platform-specific charts** | Write once vs write 3x for iOS/Android/Web. Consistent UX vs platform differences. |
| **Business tools (Tableau)** | Embedded in your app vs separate tools. Full customization vs template limitations. |
## 🛠 Advanced Configuration
### Animation Control
```dart
chart.animate(
duration: Duration(milliseconds: 1200),
curve: Curves.elasticOut, // Try different curves!
)
```
### Custom Themes
**Complete visual control** with built-in themes and full customization options.
```dart
// Built-in themes
CristalyseChart()
.data(data)
.mapping(x: 'month', y: 'revenue')
.geomLine()
.theme(ChartTheme.darkTheme()) // or .defaultTheme(), .solarizedLightTheme()
.build();
// Custom branded theme
final brandedTheme = ChartTheme(
primaryColor: const Color(0xFF007BFF), // Brand primary
colorPalette: [Colors.blue, Colors.green, Colors.red],
axisTextStyle: const TextStyle(fontSize: 12, fontWeight: FontWeight.w500),
);
CristalyseChart()
.theme(brandedTheme)
.build();
```
**Theme Features:**
- ✅ **Built-in Themes** - Light, dark, and Solarized variants ready to use
- ✅ **Brand Customization** - Match your organization's visual identity
- ✅ **Responsive Design** - Adapt themes based on screen size
- ✅ **Color Palettes** - Comprehensive color schemes for multi-series charts
- ✅ **Typography Control** - Custom fonts, sizes, and weights
- ✅ **Layout Options** - Padding, spacing, and dimension control
### Custom Color Palettes
**Brand-specific colors for categories** with semantic meaning and consistent visual identity.
```dart
// Platform-specific colors
final platformColors = {
'iOS': const Color(0xFF007AFF),
'Android': const Color(0xFF3DDC84),
'Web': const Color(0xFFFF6B35),
};
CristalyseChart()
.data(appAnalyticsData)
.mapping(x: 'month', y: 'users', color: 'platform')
.geomLine()
.customPalette(categoryColors: platformColors)
.build();
```
**Custom Palette Features:**
- ✅ **Brand Consistency** - Use your organization's exact brand colors
- ✅ **Semantic Colors** - Map status, priority, or meaning to colors
- ✅ **Category Override** - Specific colors for individual categories
- ✅ **Fallback Support** - Unmapped categories use theme colors
- ✅ **Legend Integration** - Custom colors appear in auto-generated legends
### Advanced Label Formatting
**Professional number formatting** with NumberFormat integration and custom callbacks.
```dart
import 'package:intl/intl.dart';
// Currency formatting
.scaleYContinuous(labels: NumberFormat.simpleCurrency().format) // $1,234.56
// Compact notation
.scaleYContinuous(labels: NumberFormat.compact().format) // 1.2M, 5.6K
// Custom formatting
.scaleYContinuous(labels: (value) => '${value.toStringAsFixed(1)}°C') // 23.5°C
```
**Label Formatting Features:**
- ✅ **NumberFormat Integration** - Built-in currency, percentage, and compact formatting
- ✅ **Custom Callbacks** - Full control over label appearance and logic
- ✅ **Locale Support** - Automatic localization based on device settings
- ✅ **Multi-Chart Support** - Works with all chart types (axes, pie slices, bubbles)
- ✅ **Performance Optimized** - Efficient formatting without UI blocking
- ✅ **Unit Flexibility** - Easy addition of units, symbols, and custom text
### Advanced Data Mapping
```dart
// Map any data structure
chart
.data(complexData)
.mapping(
x: 'timestamp', // Time series
y: 'metric_value', // Numeric values
color: 'category', // Color grouping
size: 'importance' // Size encoding
)
.mappingY2('efficiency') // Secondary Y-axis for dual charts
```
### Stacked Bar Configuration
```dart
chart
.data(budgetData)
.mapping(x: 'department', y: 'amount', color: 'category')
.geomBar(
style: BarStyle.stacked, // Stack segments
width: 0.8, // Bar width
borderRadius: BorderRadius.circular(4), // Rounded corners
alpha: 0.9, // Transparency
)
.scaleXOrdinal()
.scaleYContinuous(min: 0)
```
## 📱 Platform Support
- ✅ **iOS 12+**
- ✅ **Android API 21+**
- ✅ **Web (Chrome 80+, Firefox, Safari)**
- ✅ **Windows 10+**
- ✅ **macOS 10.14+**
- ✅ **Linux (Ubuntu 18.04+)**
## 🧪 Development Status
**Current Version: 1.17.4** - Production ready with fixed tooltips for interactive legends, bar chart positive/negative value styling, integer-only ticks, pinch/scroll wheel/button-based zoom, tick configuration, optional Y-axis titles in legends, boundary clamping, programmatic pan controller, interactive floating legends, and intelligent axis bounds
We're shipping progressively! Each release adds new visualization types while maintaining backward compatibility.
- ✅ **v0.1.0** - Scatter plots and basic theming
- ✅ **v0.2.0** - Line charts and animations
- ✅ **v0.3.0** - Bar charts (including horizontal) and areas
- ✅ **v0.4.0** - Enhanced theming with custom colors and text styles, stacked bars
- ✅ **v0.5.0** - **Dual Y-axis support** and advanced bar chart variations
- ✅ **v0.6.0** - Interactive tooltips
- ✅ **v0.7.0** - Interactive panning
- ✅ **v0.8.0** - **Area chart support** with animations and multi-series capabilities
- ✅ **v0.9.0** - **Enhanced dual Y-axis SVG export** with comprehensive scale support
- ✅ **v1.0.0** - **Pie charts and donut charts** with exploded slices and smart label positioning
- ✅ **v1.1.0** - **Advanced label formatting system** with NumberFormat integration (by [@davidlrichmond](https://github.com/davidlrichmond))
- ✅ **v1.2.0** - **Heat map charts** with 2D data visualization and customizable color gradients
- ✅ **v1.3.0** - **Bubble charts** with 3D data visualization and professional size encoding
- ✅ **v1.4.0** - **Custom color palettes** for brand-specific category mapping
- ✅ **v1.5.0** - **Automatic legend generation** with flexible positioning and styling
- ✅ **v1.6.0** - **Experimental gradient color support** for customPalette with Linear, Radial, and Sweep gradients
- ✅ **v1.7.0** - **Progress bar charts** with horizontal, vertical, circular, stacked, grouped, gauge, and concentric styles + comprehensive documentation improvements
- ✅ **v1.8.0** - **Intelligent axis bounds & labeling** with Wilkinson Extended algorithm (by [@davidlrichmond](https://github.com/davidlrichmond)) - professional round-number ticks, geometry-aware defaults, comprehensive testing
- ✅ **v1.9.0** - **Interactive & floating legends** with click-to-toggle visibility, custom positioning with offsets, color consistency preservation, and overflow rendering support
- ✅ **v1.10.0** - **Axis titles & bubble size guide** with optional titles for all axes, visual bubble size legends, smart spacing calculations, and bubble legend validation fixes (by [@davidlrichmond](https://github.com/davidlrichmond))
- ✅ **v1.11.0** - **Programmatic pan controller** for external chart panning control via PanController with panTo() and panReset() methods (by [@jbbjarnason](https://github.com/jbbjarnason))
- ✅ **v1.12.0** - **Boundary clamping for pan operations** with optional boundaryClampingX and boundaryClampingY to prevent infinite panning beyond data boundaries (by [@jbbjarnason](https://github.com/jbbjarnason))
- ✅ **v1.13.0** - **Optional Y-axis titles in legends** for improved multi-axis chart readability (by [@jbbjarnason](https://github.com/jbbjarnason))
- ✅ **v1.14.0** - **Tick configuration for scales** with explicit tick positions and simple linear spacing options (by [@jbbjarnason](https://github.com/jbbjarnason))
- ✅ **v1.15.0** - **Zoom & pan interactions** with pinch gestures, scroll wheel support, and floating zoom buttons for multi-touch and desktop platforms
- ✅ **v1.16.0** - **Integer-only ticks** for continuous scales, ensuring clean integer values for count data
- ✅ **v1.17.0** - **Bar chart positive/negative value styling** with smart rounded corners (`roundOutwardEdges`) and conditional colors (`positiveColor`/`negativeColor`) for financial charts and variance analysis
## Support This Project
**Love Cristalyse?** Your support helps me dedicate more time to building the Flutter charting library you deserve!
### Why Sponsor?
- **Faster Development** - More features, bug fixes, and improvements
- **Better Documentation** - Comprehensive guides and examples
- **Priority Support** - Get your issues and feature requests prioritized
- **New Chart Types** - Help fund development of advanced visualizations
- **Platform Support** - Ensure continued cross-platform compatibility
### What Your Support Enables
**Active Development** - Cristalyse is passion project that requires significant time investment
**Advanced Features** - Complex chart types like treemaps, sankey diagrams, and statistical overlays
**Bug Fixes & Performance** - Rapid responses to issues and continuous optimization
**Documentation & Examples** - Real-world examples and comprehensive tutorials
**Community Building** - Discord server, workshops, and educational content
Every contribution, no matter the size, makes a real difference!
---
## 🤝 Contributing
We'd love your help! Check out our [contributing guide](CONTRIBUTING.md) and:
- 🐛 Report bugs
- 💡 Suggest features
- 📝 Improve documentation
- 🔧 Submit pull requests
## 📄 License
MIT License - build whatever you want, commercially or otherwise.
## 🔗 Links
- 📦 [pub.dev package](https://pub.dev/packages/cristalyse)
- 📖 [Full documentation](https://github.com/rudi-q/cristalyse#readme)
- 🐛 [Issue tracker](https://github.com/rudi-q/cristalyse/issues)
- 💬 [Discussions](https://github.com/rudi-q/cristalyse/discussions)
---
**Ready to create stunning visualizations?** `flutter pub add cristalyse` and start building! 🚀
*Cristalyse: Finally, the grammar of graphics library Flutter developers deserve.*