Theming

Overview

Cristalyse’s theming system provides complete control over chart appearance. Choose from built-in themes or create custom designs that match your brand perfectly.

Built-in Themes

Default Light Theme

Perfect for standard applications with clean, professional aesthetics:

CristalyseChart()
  .data(data)
  .mapping(x: 'month', y: 'revenue')
  .geomBar()
  .theme(ChartTheme.defaultTheme())
  .build()

Dark Theme

Optimized for dark mode interfaces and low-light environments:

CristalyseChart()
  .data(data)
  .mapping(x: 'category', y: 'value')
  .geomLine(strokeWidth: 3.0)
  .theme(ChartTheme.darkTheme())
  .build()

Solarized Light

Based on the popular Solarized color scheme, easy on the eyes:

CristalyseChart()
  .data(data)
  .mapping(x: 'time', y: 'metric', color: 'series')
  .geomPoint(size: 6.0)
  .theme(ChartTheme.solarizedLightTheme())
  .build()

Solarized Dark

Dark variant of Solarized for comfortable night viewing:

CristalyseChart()
  .data(data)
  .mapping(x: 'date', y: 'price')
  .geomArea(alpha: 0.4)
  .theme(ChartTheme.solarizedDarkTheme())
  .build()

Theme Properties

Colors
Dimensions
Typography

backgroundColor - Chart container background
plotBackgroundColor - Data plotting area background
primaryColor - Default geometry color
borderColor - Chart borders and outlines
gridColor - Grid line color
axisColor - Axis lines and labels
colorPalette - Array of colors for multi-series data

gridWidth - Thickness of grid lines
axisWidth - Thickness of axis lines
pointSizeDefault - Default point size
pointSizeMin - Minimum point size for scaling
pointSizeMax - Maximum point size for scaling
padding - Chart margins and spacing

axisTextStyle - Style for axis tick labels
axisLabelStyle - Style for axis titles

Creating Custom Themes

Corporate Branding

Create themes that match your brand colors:

final brandTheme = ChartTheme(
  backgroundColor: const Color(0xFFF8F9FA),
  plotBackgroundColor: Colors.white,
  primaryColor: const Color(0xFF007ACC), // Brand blue
  borderColor: const Color(0xFFE1E5E9),
  gridColor: const Color(0xFFF1F3F4),
  axisColor: const Color(0xFF5F6368),
  gridWidth: 0.5,
  axisWidth: 1.2,
  pointSizeDefault: 5.0,
  pointSizeMin: 3.0,
  pointSizeMax: 15.0,
  colorPalette: [
    const Color(0xFF007ACC), // Primary blue
    const Color(0xFFFF6B35), // Orange accent
    const Color(0xFF28A745), // Success green  
    const Color(0xFFDC3545), // Warning red
    const Color(0xFF6F42C1), // Purple
    const Color(0xFF20C997), // Teal
  ],
  padding: const EdgeInsets.fromLTRB(60, 20, 30, 50),
  axisTextStyle: const TextStyle(
    fontSize: 11,
    color: Color(0xFF5F6368),
    fontWeight: FontWeight.w500,
  ),
  axisLabelStyle: const TextStyle(
    fontSize: 13,
    color: Color(0xFF202124),
    fontWeight: FontWeight.w600,
  ),
);

CristalyseChart()
  .data(salesData)
  .mapping(x: 'quarter', y: 'revenue', color: 'region')
  .geomBar(style: BarStyle.grouped)
  .theme(brandTheme)
  .build()

High Contrast Accessibility

Optimize for users with visual impairments:

final accessibleTheme = ChartTheme(
  backgroundColor: Colors.white,
  plotBackgroundColor: Colors.white,
  primaryColor: Colors.black,
  borderColor: Colors.black,
  gridColor: const Color(0xFF666666),
  axisColor: Colors.black,
  gridWidth: 1.0,
  axisWidth: 2.0,
  pointSizeDefault: 8.0,
  pointSizeMin: 6.0,
  pointSizeMax: 20.0,
  colorPalette: [
    Colors.black,
    const Color(0xFF0066CC), // High contrast blue
    const Color(0xFFCC0000), // High contrast red
    const Color(0xFF009900), // High contrast green
    const Color(0xFFFF6600), // High contrast orange
  ],
  padding: const EdgeInsets.all(20),
  axisTextStyle: const TextStyle(
    fontSize: 14,
    color: Colors.black,
    fontWeight: FontWeight.bold,
  ),
);

Minimal Theme

Clean design for modern interfaces:

final minimalTheme = ChartTheme(
  backgroundColor: Colors.transparent,
  plotBackgroundColor: Colors.transparent,
  primaryColor: const Color(0xFF2196F3),
  borderColor: Colors.transparent,
  gridColor: const Color(0x1A000000),
  axisColor: const Color(0xFF757575),
  gridWidth: 0.5,
  axisWidth: 0.8,
  pointSizeDefault: 4.0,
  pointSizeMin: 2.0,
  pointSizeMax: 10.0,
  colorPalette: [
    const Color(0xFF2196F3),
    const Color(0xFFFF5722),
    const Color(0xFF4CAF50),
    const Color(0xFFFFC107),
    const Color(0xFF9C27B0),
  ],
  padding: const EdgeInsets.fromLTRB(40, 10, 10, 30),
  axisTextStyle: const TextStyle(
    fontSize: 10,
    color: Color(0xFF757575),
  ),
);

Theme Modifications

Using copyWith()

Modify existing themes while preserving most properties:

// Customize default theme colors
final customTheme = ChartTheme.defaultTheme().copyWith(
  primaryColor: Colors.deepPurple,
  colorPalette: [
    Colors.deepPurple,
    Colors.amber,
    Colors.teal,
    Colors.pink,
  ],
);

// Adjust dark theme spacing
final spaciousTheme = ChartTheme.darkTheme().copyWith(
  padding: const EdgeInsets.all(40),
  pointSizeDefault: 8.0,
);

// Update typography
final boldTheme = ChartTheme.solarizedLightTheme().copyWith(
  axisTextStyle: const TextStyle(
    fontSize: 12,
    fontWeight: FontWeight.bold,
    color: Color(0xFF586e75),
  ),
);

Dynamic Theme Selection

Switch themes based on app state:

class ThemeAwareChart extends StatelessWidget {
  final bool isDarkMode;
  final List<Map<String, dynamic>> data;

  const ThemeAwareChart({
    required this.isDarkMode,
    required this.data,
    super.key,
  });

  @override
  Widget build(BuildContext context) {
    final theme = isDarkMode 
        ? ChartTheme.darkTheme()
        : ChartTheme.defaultTheme();
    
    return CristalyseChart()
      .data(data)
      .mapping(x: 'x', y: 'y')
      .geomLine()
      .theme(theme)
      .animate(duration: const Duration(milliseconds: 300))
      .build();
  }
}

Custom Category Colors

Using customPalette()

Assign specific colors to chart categories instead of relying on theme defaults. Perfect for brand consistency and semantic coloring:

// Financial portfolio by asset class
final assetColors = {
  'Stocks': const Color(0xFF2563EB),       // Blue - growth
  'Bonds': const Color(0xFF059669),        // Green - stability  
  'Real Estate': const Color(0xFFDC2626),  // Red - tangible
  'Commodities': const Color(0xFFF59E0B),  // Yellow - resources
  'Cash': const Color(0xFF6B7280),         // Gray - liquid
};

CristalyseChart()
  .data(portfolioData)
  .mapping(x: 'year', y: 'allocation', color: 'asset_class')
  .geomArea(strokeWidth: 1.0, alpha: 0.7)
  .theme(ChartTheme.defaultTheme())
  .customPalette(categoryColors: assetColors)
  .build();

Semantic Color Mapping

Use meaningful colors for status, performance, or categorical data:

// Customer satisfaction survey results
final satisfactionColors = {
  'Very Satisfied': const Color(0xFF10B981),    // Bright green
  'Satisfied': const Color(0xFF84CC16),         // Lime green
  'Neutral': const Color(0xFFFBBF24),           // Amber
  'Dissatisfied': const Color(0xFFF97316),      // Orange
  'Very Dissatisfied': const Color(0xFFEF4444), // Red
};

CristalyseChart()
  .data(surveyResults)
  .mapping(x: 'month', y: 'responses', color: 'satisfaction')
  .geomBar(style: BarStyle.stacked)
  .customPalette(categoryColors: satisfactionColors)
  .build();

Department Analytics

Consistent colors across organizational charts:

// Regional sales performance by continent
final regionColors = {
  'North America': const Color(0xFF3B82F6),  // Blue - established market
  'Europe': const Color(0xFF10B981),         // Green - growth market
  'Asia Pacific': const Color(0xFFF59E0B),   // Yellow - emerging opportunity
  'Latin America': const Color(0xFFEF4444),  // Red - developing market
  'Middle East': const Color(0xFF8B5CF6),    // Purple - strategic market
  'Africa': const Color(0xFF06B6D4),         // Cyan - future potential
};

CristalyseChart()
  .data(globalSalesData)
  .mapping(x: 'quarter', y: 'revenue', color: 'region')
  .geomLine(strokeWidth: 3.0)
  .geomPoint(size: 5.0)
  .customPalette(categoryColors: regionColors)
  .build();

Smart Fallback Behavior

Categories not specified in your custom palette automatically use theme defaults:

// Only specify colors for key categories
final partialColors = {
  'Primary': Colors.blue,
  'Secondary': Colors.orange,
  // 'Other' categories will use theme.colorPalette colors
};

CristalyseChart()
  .data(mixedData)
  .mapping(x: 'date', y: 'value', color: 'category')
  .geomArea()
  .customPalette(categoryColors: partialColors)
  .build();

Important: The customPalette() method requires a color mapping in your .mapping() call. Categories not specified in categoryColors will automatically use colors from your theme’s colorPalette.

Advanced Theming Patterns

Conditional Color Palettes

Adapt colors based on data characteristics:

ChartTheme adaptiveTheme(List<Map<String, dynamic>> data) {
  final categories = data.map((d) => d['category']).toSet().length;
  
  // Use different palettes based on data complexity
  final palette = categories <= 3
      ? [Colors.blue, Colors.orange, Colors.green]
      : [
          Colors.blue[400]!, Colors.blue[600]!, Colors.blue[800]!,
          Colors.orange[400]!, Colors.orange[600]!, Colors.orange[800]!,
          Colors.green[400]!, Colors.green[600]!, Colors.green[800]!,
        ];
        
  return ChartTheme.defaultTheme().copyWith(
    colorPalette: palette,
  );
}

Responsive Theme Sizing

Adjust theme properties based on screen size:

ChartTheme responsiveTheme(BuildContext context) {
  final screenWidth = MediaQuery.of(context).size.width;
  final isSmallScreen = screenWidth < 600;
  
  return ChartTheme.defaultTheme().copyWith(
    padding: EdgeInsets.all(isSmallScreen ? 16 : 32),
    axisTextStyle: TextStyle(
      fontSize: isSmallScreen ? 10 : 12,
      color: Colors.black87,
    ),
    pointSizeDefault: isSmallScreen ? 3.0 : 5.0,
    gridWidth: isSmallScreen ? 0.3 : 0.5,
  );
}

Best Practices

Color Accessibility

Ensure sufficient contrast ratios (4.5:1 minimum)
Test with colorblind-friendly palettes
Provide alternative visual cues beyond color
Consider WCAG 2.1 guidelines for data visualization

Consistency

Use the same theme across related charts
Maintain consistent color meanings (red = danger, green = success)
Keep typography hierarchy consistent
Align with your app’s overall design system

Performance

Reuse theme objects rather than creating new ones
Cache theme calculations for dynamic themes
Use copyWith() for minor modifications
Consider theme switching animation performance

Customization

Start with built-in themes as foundation
Test themes with various data types and sizes
Consider responsive design for different screen sizes
Document custom theme usage for team members

Custom Category Colors

Use customPalette() for brand-specific or semantic colors
Maintain consistent color meanings across charts
Leverage fallback behavior for unmapped categories
Combine with themes for complete visual control
Test color accessibility and contrast ratios

Theme Gallery

Corporate Blue

Professional theme with brand-focused blue palette and clean typography

High Contrast

WCAG-compliant theme optimized for visual accessibility

Minimal Dark

Clean dark theme perfect for modern dashboards

Scientific

High-precision theme designed for scientific data visualization

Next Steps

Interactions

Add hover effects and user interactions to themed charts

Animations

Animate theme transitions and chart rendering

Export

Export themed charts with consistent styling

Custom Themes

Advanced techniques for creating complex theme systems

Get Started

Chart Types

Features

Advanced

Overview

Built-in Themes

Default Light Theme

Dark Theme

Solarized Light

Solarized Dark

Theme Properties

Creating Custom Themes

Corporate Branding

High Contrast Accessibility

Minimal Theme

Theme Modifications

Using copyWith()

Dynamic Theme Selection

Custom Category Colors

Using customPalette()

Semantic Color Mapping

Department Analytics

Smart Fallback Behavior

Advanced Theming Patterns

Conditional Color Palettes

Responsive Theme Sizing

Best Practices

Theme Gallery

Corporate Blue

High Contrast

Minimal Dark

Scientific

Next Steps

Interactions

Animations

Export

Custom Themes

​Overview

​Built-in Themes

​Default Light Theme

​Dark Theme

​Solarized Light

​Solarized Dark

​Theme Properties

​Creating Custom Themes

​Corporate Branding

​High Contrast Accessibility

​Minimal Theme

​Theme Modifications

​Using copyWith()

​Dynamic Theme Selection

​Custom Category Colors

​Using customPalette()

​Semantic Color Mapping

​Department Analytics

​Smart Fallback Behavior

​Advanced Theming Patterns

​Conditional Color Palettes

​Responsive Theme Sizing

​Best Practices

​Theme Gallery

Corporate Blue

High Contrast

Minimal Dark

Scientific

​Next Steps

Interactions

Animations

Export

Custom Themes

Overview

Built-in Themes

Default Light Theme

Dark Theme

Solarized Light

Solarized Dark

Theme Properties

Creating Custom Themes

Corporate Branding

High Contrast Accessibility

Minimal Theme

Theme Modifications

Using copyWith()

Dynamic Theme Selection

Custom Category Colors

Using customPalette()

Semantic Color Mapping

Department Analytics

Smart Fallback Behavior

Advanced Theming Patterns

Conditional Color Palettes

Responsive Theme Sizing

Best Practices

Theme Gallery

Next Steps