Quick Start

Let’s create your first chart in 5 minutes. This guide uses React, but other frameworks are similar.

Step 1: Create a Basic Bar Chart

Let’s start with the simplest form of a bar chart.

import { Widget } from '@meursyphus/flitter-react';
import { BarChart } from '@meursyphus/headless-chart';

function MyFirstChart() {
  const chart = BarChart({
    data: {
      labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
      datasets: [{
        label: 'Monthly Sales',
        data: [120, 190, 300, 250, 420]
      }]
    }
  });

  return (
    <Widget 
      width="600px" 
      height="400px" 
      widget={chart} 
    />
  );
}

That’s it! The chart will render with default styling.

Step 2: Add Multiple Datasets

In real applications, you often need to compare multiple data sets. Let’s add more datasets.

const chart = BarChart({
  data: {
    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
    datasets: [
      {
        label: '2023',
        data: [120, 190, 300, 250, 420]
      },
      {
        label: '2024',
        data: [150, 230, 280, 320, 480]
      }
    ]
  }
});

Step 3: Your First Customization

Now let’s change the chart colors using the custom prop.

import { Container } from '@meursyphus/flitter';

const chart = BarChart({
  data: {
    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
    datasets: [{
      label: 'Monthly Sales',
      data: [120, 190, 300, 250, 420]
    }]
  },
  custom: {
    bar: ({ datasetIndex }) => {
      // Apply different colors for each dataset
      const colors = ['#3b82f6', '#ef4444', '#10b981'];
      
      return Container({
        width: Infinity,
        height: Infinity,
        color: colors[datasetIndex] || '#3b82f6'
      });
    }
  }
});

Step 4: Try Different Chart Types

Line Charts work in a similar way.

import { LineChart } from '@meursyphus/headless-chart';

const lineChart = LineChart({
  data: {
    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
    datasets: [{
      label: 'Visitors',
      data: [1200, 1900, 3000, 2500, 4200]
    }]
  }
});

Step 5: Add Interactive Features

Let’s add tooltips and hover effects.

import { GestureDetector, MouseRegion } from '@meursyphus/flitter';
import { useState } from 'react';

function InteractiveChart() {
  const [hoveredBar, setHoveredBar] = useState(null);
  
  const chart = BarChart({
    data: {
      labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
      datasets: [{
        label: 'Monthly Sales',
        data: [120, 190, 300, 250, 420]
      }]
    },
    custom: {
      bar: ({ label, value }) => {
        const isHovered = hoveredBar === label;
        
        return MouseRegion({
          onEnter: () => setHoveredBar(label),
          onExit: () => setHoveredBar(null),
          child: Container({
            width: Infinity,
            height: Infinity,
            color: isHovered ? '#2563eb' : '#3b82f6',
            // Scale effect on hover
            transform: isHovered ? 'scale(1.05)' : 'scale(1)',
            transition: 'all 0.2s ease'
          })
        });
      }
    }
  });

  return (
    <div>
      <Widget width="600px" height="400px" widget={chart} />
      {hoveredBar && (
        <p>Selected month: {hoveredBar}</p>
      )}
    </div>
  );
}

Real-World Example: Dashboard Chart

Here’s a more complete example that you can use in real projects.

import { 
  Container, 
  EdgeInsets, 
  BoxDecoration,
  BorderRadius,
  Text,
  TextStyle,
  Row,
  MainAxisAlignment
} from '@meursyphus/flitter';

function DashboardChart() {
  const chart = BarChart({
    data: {
      labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
      datasets: [
        {
          label: 'Completed',
          data: [12, 19, 15, 25, 22]
        },
        {
          label: 'In Progress',
          data: [5, 8, 7, 4, 6]
        }
      ]
    },
    custom: {
      // Custom layout
      layout: ({ plot, xAxis, yAxis, legends }) => {
        return Container({
          padding: EdgeInsets.all(20),
          decoration: new BoxDecoration({
            color: '#ffffff',
            borderRadius: BorderRadius.circular(12),
            boxShadow: [{
              color: 'rgba(0, 0, 0, 0.1)',
              blurRadius: 10,
              offset: { x: 0, y: 4 }
            }]
          }),
          child: Column({
            children: [
              // Title
              Text('Weekly Task Status', {
                style: new TextStyle({
                  fontSize: 18,
                  fontWeight: 'bold',
                  color: '#1f2937'
                })
              }),
              SizedBox({ height: 20 }),
              // Legend
              Row({
                mainAxisAlignment: MainAxisAlignment.center,
                children: legends
              }),
              SizedBox({ height: 20 }),
              // Chart
              plot
            ]
          })
        });
      },
      
      // Custom bar
      bar: ({ datasetIndex }) => {
        const colors = ['#3b82f6', '#fbbf24'];
        
        return Container({
          width: Infinity,
          height: Infinity,
          margin: EdgeInsets.symmetric({ horizontal: 4 }),
          decoration: new BoxDecoration({
            color: colors[datasetIndex],
            borderRadius: BorderRadius.only({
              topLeft: 4,
              topRight: 4
            })
          })
        });
      },
      
      // Custom grid
      gridXLine: () => Container({
        height: 1,
        color: '#f3f4f6'
      })
    }
  });

  return <Widget width="100%" height="400px" widget={chart} />;
}

Next Steps

Congratulations! 🎉 You’ve successfully created your first chart.

Now explore:

1. Core Concepts: Understanding the Flitter widget system
2. Chart Guide: Detailed guides for each chart type
3. Advanced Features: More complex customizations

Tips and Best Practices

1. Start Small

Begin with default charts and progressively add customizations.

2. Use TypeScript

TypeScript’s autocomplete makes development much easier.

3. Create Reusable Components

Extract frequently used custom components.

// Reusable custom bar
const BrandBar = ({ color = '#3b82f6' }) => {
  return Container({
    width: Infinity,
    height: Infinity,
    decoration: new BoxDecoration({
      color,
      borderRadius: BorderRadius.circular(4)
    })
  });
};

// Reuse across multiple charts
const chart1 = BarChart({
  custom: { bar: () => BrandBar({ color: '#3b82f6' }) }
});

const chart2 = BarChart({
  custom: { bar: () => BrandBar({ color: '#10b981' }) }
});