cristalyse 1.2.2

cristalyse: ^1.2.2 copied to clipboard

[Cristalyse]

The grammar of graphics visualization library that Flutter developers have been waiting for.

Finally, create beautiful data visualizations in Flutter without fighting against chart widgets or settling for web-based solutions.

✨ 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
• 👆 Interactive Charts - Engage users with tooltips, hover effects, and click events.

See What You Can Build #

[Animated Scatter Plot]
Interactive scatter plots with smooth animations and multi-dimensional data mapping

[Progressive Line Chart]
Progressive line drawing with customizable themes and multi-series support

🚀 Quick Start #

Installation #

flutter pub add cristalyse

That's it! No complex setup, no additional configuration.

Your First Chart (30 seconds) #

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.

[Simple Scatter Plot]
Your first chart - clean, responsive, and cross-platform

💡 Interactive Charts #

New: Enhanced Panning Behavior #

Add real-time panning capabilities to your charts with seamless range updates and smooth interaction.

CristalyseChart()
  .data(myData)
  .mapping(x: 'x', y: 'y')
  .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}');
      },
    ),
  )
  .build();

Features:

• Maintains pan state across interactions
• Synchronizes displayed range between header and chart axis
• Enhanced UI for range display card

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.

// 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 #

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 #

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 #

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 #

Stacked Bar Charts #

// 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 Bar Chart]
Stacked bars with segment-by-segment progressive animation

Grouped Bar Charts #

// 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 Chart]
Grouped bar charts for comparing multiple series side-by-side

Horizontal Bar Charts #

// Great for ranking and long category names
CristalyseChart()
  .data(departmentData)
  .mapping(x: 'department', y: 'headcount')
  .geomBar(
    borderRadius: BorderRadius.circular(4), // Rounded corners
    borderWidth: 1.0,                       // Add borders
  )
  .coordFlip()                              // Flip to horizontal
  .scaleXOrdinal()
  .scaleYContinuous(min: 0)
  .theme(ChartTheme.defaultTheme())
  .build()

🥧 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 #

// 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 #

// 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 #

// 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 #

// 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 #

// 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 #

// 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.

// 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 Chart]
Dual axis charts for correlating two different metrics on independent scales

More Dual Y-Axis Examples #

// 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();

🔥 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
• 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
• Coordinate flipping for horizontal charts
• Multiple themes (Light, Dark, Solarized Light/Dark)
• Custom color palettes and styling options
• Responsive scaling for all screen sizes
• High-DPI support for crisp visuals

✅ Data Handling #

• Flexible data formats - List<Map<String, dynamic>>
• 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

📸 Chart Export #

Export your charts as professional-quality SVG vector graphics for reports, presentations, and documentation.

// 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

🚧 Coming Soon (Next Releases) #

• Statistical overlays (regression lines, confidence intervals)
• Interactive zoom capabilities with scale persistence
• Faceting for small multiples and grid layouts
• Enhanced SVG export with full chart rendering

🎯 Real-World Examples #

Sales Dashboard #

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 #

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 #

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 #

Widget buildKPIDashboard() {
  return CristalyseChart()
      .data(kpiData)
      .mapping(x: 'quarter', y: 'revenue')
      .mappingY2('profit_margin')             // Dual Y-axis for percentage
      .geomBar(
        yAxis: YAxis.primary,
        style: BarStyle.stacked,              // Stack revenue components
        color: 'revenue_source',
      )
      .geomLine(
        yAxis: YAxis.secondary,               // Profit margin trend
        strokeWidth: 4.0,
        color: Colors.green,
      )
      .scaleXOrdinal()
      .scaleYContinuous(min: 0)               // Revenue scale
      .scaleY2Continuous(min: 0, max: 50)     // Percentage scale
      .theme(ChartTheme.defaultTheme())
      .build();
}

💡 Why Not Just Use...? #

🛠 Advanced Configuration #

Custom Themes #

final customTheme = ChartTheme(
  backgroundColor: Colors.grey[50]!,
  primaryColor: Colors.deepPurple,
  colorPalette: [Colors.blue, Colors.red, Colors.green],
  gridColor: Colors.grey[300]!,
  axisTextStyle: TextStyle(fontSize: 14, color: Colors.black87),
  padding: EdgeInsets.all(40),
);

chart.theme(customTheme)

Animation Control #

chart.animate(
  duration: Duration(milliseconds: 1200),
  curve: Curves.elasticOut,  // Try different curves!
)

Advanced Data Mapping #

// 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 #

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.2.2 - Production ready with heat map charts, enhanced dual Y-axis SVG export and comprehensive interactive capabilities

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
• ✅ v1.2.0 - Heat map charts with 2D data visualization and customizable color gradients

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 and:

• 🐛 Report bugs
• 💡 Suggest features
• 📝 Improve documentation
• 🔧 Submit pull requests

📄 License #

MIT License - build whatever you want, commercially or otherwise.

🔗 Links #

• 📦 pub.flutter-io.cn package
• 📖 Full documentation
• 🐛 Issue tracker
• 💬 Discussions

Ready to create stunning visualizations? flutter pub add cristalyse and start building! 🚀

Cristalyse: Finally, the grammar of graphics library Flutter developers deserve.