React Bubble Chart

A powerful, customizable bubble chart component for React applications with TypeScript support. Perfect for visualizing three-dimensional data relationships with interactive features, smooth animations, and extensive customization options.

Installation

npm install @aniruddha1806/bubble-chart

Features

• 🫧 Interactive bubble charts with three-dimensional data visualization
• 🎭 Smooth entrance animations with scroll-triggered effects
• 🖱️ Hover tooltips and click handlers
• 📊 Customizable axes with configurable ticks and labels
• 🎨 Extensive styling options (colors, sizing, formatting)
• 📱 Responsive SVG-based rendering
• 📏 Flexible bubble sizing (relative or absolute)
• 🔄 Real-time data updates with smooth transitions
• 📝 TypeScript support with full type definitions
• ♿ Accessibility-friendly structure
• 🪶 Zero dependencies for chart rendering

Quick Start

Basic Bubble Chart

import { BubbleChart } from '@aniruddha1806/bubble-chart';

function App() {
  const data = [
    { x: 10, y: 20, size: 15, label: 'Product A', color: '#3b82f6' },
    { x: 25, y: 35, size: 25, label: 'Product B', color: '#10b981' },
    { x: 40, y: 15, size: 20, label: 'Product C', color: '#f59e0b' },
    { x: 30, y: 45, size: 30, label: 'Product D', color: '#ef4444' },
    { x: 50, y: 30, size: 18, label: 'Product E', color: '#8b5cf6' }
  ];

  return (
    <BubbleChart
      data={data}
      width="100%"
      height={400}
      xAxisLabel="Revenue (millions)"
      yAxisLabel="Growth Rate (%)"
      showTooltip={true}
      animated={true}
    />
  );
}

Advanced Configuration

import { BubbleChart } from '@aniruddha1806/bubble-chart';

function AdvancedExample() {
  const data = [
    // ... your data
  ];

  return (
    <BubbleChart
      data={data}
      width={800}
      height={500}
      xAxisLabel="Market Share (%)"
      yAxisLabel="Customer Satisfaction"
      minRadius={8}
      maxRadius={60}
      xAxisTicks={8}
      yAxisTicks={6}
      bubbleSizeMultiplier={1.2}
      animated={true}
      animationDuration={1000}
      formatValue={(value) => `$${value}M`}
      onBubbleClick={(bubble) => console.log('Clicked:', bubble)}
    />
  );
}

Props

Core Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | data | BubbleDataPoint[] | required | Array of bubble data points | | width | number \| string | "100%" | Chart width | | height | number \| string | 400 | Chart height |

Styling Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | colors | string[] | default palette | Color palette for bubbles | | backgroundColor | string | "transparent" | Chart background color | | className | string | "" | CSS class for container | | bubbleClassName | string | "" | CSS class for bubbles | | tooltipClassName | string | "" | CSS class for tooltips |

Axis Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | xAxisLabel | string | "X-Axis" | X-axis label text | | yAxisLabel | string | "Y-Axis" | Y-axis label text | | xAxisTicks | number | 5 | Number of X-axis tick marks | | yAxisTicks | number | 5 | Number of Y-axis tick marks |

Bubble Sizing Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | minRadius | number | 10 | Minimum bubble radius | | maxRadius | number | 50 | Maximum bubble radius | | bubbleSizeMultiplier | number | 1 | Size scaling multiplier | | absoluteBubbleSize | boolean | false | Use absolute sizing instead of relative |

Formatting Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | formatValue | (value: number) => string | toString | General value formatter | | formatXAxisValue | (value: number) => string | formatValue | X-axis value formatter | | formatYAxisValue | (value: number) => string | formatValue | Y-axis value formatter |

Interaction Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | showTooltip | boolean | true | Show hover tooltips | | onBubbleClick | (dataPoint: BubbleDataPoint) => void | undefined | Bubble click handler | | tooltipContent | (bubble: BubbleDataPoint) => React.ReactNode | undefined | Custom tooltip content |

Animation Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | animated | boolean | true | Enable entrance animations | | animationDuration | number | 800 | Animation duration (ms) |

Data Types

type BubbleDataPoint = {
  x: number;
  y: number;
  size: number;
  label?: string;
  color?: string;
  [key: string]: any; // Additional custom properties
};

Examples

Sales Performance Dashboard

Visualize sales data with revenue, growth, and market size:

import { BubbleChart } from '@aniruddha1806/bubble-chart';

function SalesPerformance() {
  const salesData = [
    {
      x: 45, // Revenue (millions)
      y: 12, // Growth rate (%)
      size: 25, // Market size
      label: 'North America',
      color: '#3b82f6',
      region: 'NA',
      customers: 1250
    },
    {
      x: 32,
      y: 18,
      size: 20,
      label: 'Europe',
      color: '#10b981',
      region: 'EU',
      customers: 980
    },
    {
      x: 28,
      y: 25,
      size: 30,
      label: 'Asia Pacific',
      color: '#f59e0b',
      region: 'APAC',
      customers: 1580
    },
    {
      x: 15,
      y: 35,
      size: 15,
      label: 'Latin America',
      color: '#ef4444',
      region: 'LATAM',
      customers: 650
    },
    {
      x: 8,
      y: 42,
      size: 12,
      label: 'Middle East',
      color: '#8b5cf6',
      region: 'ME',
      customers: 420
    }
  ];

  const handleBubbleClick = (bubble) => {
    alert(`Region: ${bubble.label}\\nRevenue: $${bubble.x}M\\nGrowth: ${bubble.y}%\\nCustomers: ${bubble.customers}`);
  };

  const customTooltip = (bubble) => (
    <div>
      <div style={{ fontWeight: 'bold', marginBottom: '4px' }}>{bubble.label}</div>
      <div>Revenue: $${bubble.x}M</div>
      <div>Growth: \${bubble.y}%</div>
      <div>Market Size: \${bubble.size}</div>
      <div>Customers: \${bubble.customers?.toLocaleString()}</div>
    </div>
  );

  return (
    <div style={{ padding: '20px' }}>
      <h2>Regional Sales Performance</h2>
      <p>Revenue vs Growth Rate (Bubble size = Market opportunity)</p>
      
      <BubbleChart
        data={salesData}
        width="100%"
        height={500}
        xAxisLabel="Revenue ($ millions)"
        yAxisLabel="Growth Rate (%)"
        minRadius={15}
        maxRadius={45}
        xAxisTicks={6}
        yAxisTicks={8}
        animated={true}
        animationDuration={1200}
        onBubbleClick={handleBubbleClick}
        tooltipContent={customTooltip}
        formatXAxisValue={(value) => `$${value}M`}
        formatYAxisValue={(value) => `${value}%`}
      />
      
      <div style={{ 
        marginTop: '20px',
        display: 'grid',
        gridTemplateColumns: 'repeat(auto-fit, minmax(200px, 1fr))',
        gap: '16px'
      }}>
        {salesData.map((region, index) => (
          <div
            key={index}
            style={{
              padding: '16px',
              backgroundColor: 'white',
              border: '1px solid #e2e8f0',
              borderRadius: '8px',
              textAlign: 'center'
            }}
          >
            <div style={{ 
              width: '20px', 
              height: '20px', 
              backgroundColor: region.color,
              borderRadius: '50%',
              margin: '0 auto 8px'
            }}></div>
            <h4 style={{ margin: '0 0 4px 0' }}>{region.label}</h4>
            <p style={{ margin: 0, fontSize: '14px', color: '#666' }}>
              $${region.x}M revenue
            </p>
          </div>
        ))}
      </div>
    </div>
  );
}

TypeScript Usage

The component provides full TypeScript support:

import { BubbleChart, BubbleDataPoint, BubbleChartProps } from '@aniruddha1806/bubble-chart';
import { useState, useCallback } from 'react';

interface AnalyticsData extends BubbleDataPoint {
  category: string;
  revenue: number;
  customers: number;
}

interface ChartConfig {
  title: string;
  xLabel: string;
  yLabel: string;
  colors: string[];
}

const AnalyticsDashboard: React.FC = () => {
  const [analyticsData, setAnalyticsData] = useState<AnalyticsData[]>([
    {
      x: 45,
      y: 12,
      size: 25,
      label: 'Product A',
      color: '#3b82f6',
      category: 'Electronics',
      revenue: 2500000,
      customers: 1250
    },
    {
      x: 32,
      y: 18,
      size: 20,
      label: 'Product B',
      color: '#10b981',
      category: 'Software',
      revenue: 1800000,
      customers: 980
    }
  ]);

  const handleBubbleClick = useCallback((dataPoint: BubbleDataPoint): void => {
    const analyticsPoint = dataPoint as AnalyticsData;
    console.log('Analytics data:', analyticsPoint);
    // Handle click logic
  }, []);

  const formatCurrency = useCallback((value: number): string => {
    return new Intl.NumberFormat('en-US', {
      style: 'currency',
      currency: 'USD',
      minimumFractionDigits: 0,
      maximumFractionDigits: 0
    }).format(value);
  }, []);

  const customTooltip = useCallback((bubble: BubbleDataPoint): React.ReactNode => {
    const data = bubble as AnalyticsData;
    return (
      <div>
        <div style={{ fontWeight: 'bold', marginBottom: '4px' }}>{data.label}</div>
        <div>Category: {data.category}</div>
        <div>Revenue: {formatCurrency(data.revenue)}</div>
        <div>Customers: {data.customers.toLocaleString()}</div>
        <div>Market Share: \${data.x}%</div>
        <div>Growth: \${data.y}%</div>
      </div>
    );
  }, [formatCurrency]);

  const chartConfig: ChartConfig = {
    title: 'Product Performance Analysis',
    xLabel: 'Market Share (%)',
    yLabel: 'Growth Rate (%)',
    colors: ['#3b82f6', '#10b981', '#f59e0b', '#ef4444', '#8b5cf6']
  };

  const bubbleChartProps: BubbleChartProps = {
    data: analyticsData,
    width: '100%',
    height: 500,
    colors: chartConfig.colors,
    xAxisLabel: chartConfig.xLabel,
    yAxisLabel: chartConfig.yLabel,
    minRadius: 15,
    maxRadius: 45,
    animated: true,
    animationDuration: 1000,
    onBubbleClick: handleBubbleClick,
    tooltipContent: customTooltip,
    formatXAxisValue: (value) => `\${value}%`,
    formatYAxisValue: (value) => `\${value}%`
  };

  return (
    <div>
      <h2>{chartConfig.title}</h2>
      <BubbleChart {...bubbleChartProps} />
      
      <div>
        <h3>Summary Statistics:</h3>
        <p>Total Products: {analyticsData.length}</p>
        <p>Total Revenue: {formatCurrency(analyticsData.reduce((sum, item) => sum + item.revenue, 0))}</p>
        <p>Total Customers: {analyticsData.reduce((sum, item) => sum + item.customers, 0).toLocaleString()}</p>
      </div>
    </div>
  );
};