ExChartz

High-performance, customizable chart components for React Native and Expo built with Skia and Reanimated.

Features

• 🚀 High Performance: Built with react-native-skia for high performance
• 📊 Multiple Chart Types: Area, Line, Bar, Pie, Radar charts
• 🎨 Fully Customizable: Colors, animations, styling, and layout options
• 📱 Cross Platform: Works on iOS, Android, and Expo
• 🔄 Smooth Animations: Powered by react-native-reanimated
• 📐 Flexible Scaling: Support for linear, log, band, and time scales
• 🎯 TypeScript: Full TypeScript support with comprehensive type definitions
• 🔧 Composable: Mix and match chart components within CartesianChart

Installation

npm install exchartz

Peer Dependencies

ExChartz requires the following peer dependencies:

npm install react-native-skia react-native-reanimated d3

For Expo projects:

expo install react-native-skia react-native-reanimated
npm install d3

Note: Make sure to follow the setup instructions for react-native-skia and react-native-reanimated in your project.

Basic Usage

CartesianChart (Container)

The CartesianChart component provides the coordinate system and axes for other chart components.

import React from "react";
import { CartesianChart, LineChart } from "exchartz";

const data = [
  { x: 0, y: 10 },
  { x: 1, y: 20 },
  { x: 2, y: 15 },
  { x: 3, y: 25 },
  { x: 4, y: 18 },
];

export default function BasicChart() {
  return (
    <CartesianChart
      width={300}
      height={200}
      padding={{ left: 40, right: 20, top: 20, bottom: 40 }}
      xAxis={{ showAxis: true, showGrid: true }}
      yAxis={{ showAxis: true, showGrid: true }}
    >
      <LineChart data={data} lineColor="#3b82f6" strokeWidth={2} />
    </CartesianChart>
  );
}

LineChart

import React from "react";
import { CartesianChart, LineChart } from "exchartz";
import * as d3 from "d3";

const data = [
  { x: 0, y: 10 },
  { x: 1, y: 20 },
  { x: 2, y: 15 },
  { x: 3, y: 25 },
  { x: 4, y: 18 },
];

export default function LineChartExample() {
  return (
    <CartesianChart width={300} height={200}>
      <LineChart
        data={data}
        lineColor="#ef4444"
        strokeWidth={3}
        curve={d3.curveCatmullRom}
        animated={true}
        animationDuration={1000}
      />
    </CartesianChart>
  );
}

AreaChart

import React from "react";
import { CartesianChart, AreaChart } from "exchartz";

const data = [
  { x: 0, y: 10 },
  { x: 1, y: 20 },
  { x: 2, y: 15 },
  { x: 3, y: 25 },
  { x: 4, y: 18 },
];

export default function AreaChartExample() {
  return (
    <CartesianChart width={300} height={200}>
      <AreaChart
        data={data}
        areaColor="#10b981"
        opacity={0.7}
        animated={true}
        animationDuration={1200}
      />
    </CartesianChart>
  );
}

BarChart

import React from "react";
import { CartesianChart, BarChart } from "exchartz";

const data = [
  { x: "Jan", y: 10 },
  { x: "Feb", y: 20 },
  { x: "Mar", y: 15 },
  { x: "Apr", y: 25 },
  { x: "May", y: 18 },
];

export default function BarChartExample() {
  return (
    <CartesianChart width={300} height={200} xAxis={{ scaleType: "band" }}>
      <BarChart
        data={data}
        barColor={["#3b82f6", "#ef4444", "#10b981", "#f59e0b", "#8b5cf6"]}
        animated={true}
        animationDuration={800}
      />
    </CartesianChart>
  );
}

API Documentation

CartesianChart Props

| Prop | Type | Default | Description | | ----------------- | ------------ | ------------ | ------------------------------------------------ | | width | number | Required | Chart width in pixels | | height | number | Required | Chart height in pixels | | padding | object | {} | Chart padding { left?, right?, top?, bottom? } | | xAxis | AxisConfig | {} | X-axis configuration | | yAxis | AxisConfig | {} | Y-axis configuration | | backgroundColor | string | undefined | Chart background color | | children | ReactNode | Required | Chart components to render |

AxisConfig Interface

| Property | Type | Default | Description | | ------------ | --------------------------------------- | --------------- | ------------------ | | domain | [number, number] \| string[] | Auto-calculated | Axis domain range | | scaleType | 'linear' \| 'log' \| 'band' \| 'time' | 'linear' | Scale type | | showAxis | boolean | true | Show axis line | | showGrid | boolean | false | Show grid lines | | showTicks | boolean | true | Show tick marks | | showLabels | boolean | true | Show axis labels | | axisColor | string | '#000' | Axis line color | | gridColor | string | '#e5e5e5' | Grid line color | | labelColor | string | '#000' | Label text color | | tickLength | number | 5 | Tick mark length | | tickCount | number | 5 | Number of ticks | | tickValues | number[] \| string[] | Auto-calculated | Custom tick values | | label | string | undefined | Axis label |

LineChart Props

| Prop | Type | Default | Description | | ------------------- | ------------------ | ---------------- | ------------------------ | | data | ChartDataPoint[] | Required | Chart data points | | lineColor | string | '#000' | Line color | | strokeWidth | number | 2 | Line stroke width | | curve | d3.CurveFactory | d3.curveLinear | D3 curve function | | animated | boolean | false | Enable animations | | animationDuration | number | 1000 | Animation duration in ms | | animationDelay | number | 0 | Animation delay in ms |

AreaChart Props

| Prop | Type | Default | Description | | ------------------- | ------------------ | ---------------- | ------------------------ | | data | ChartDataPoint[] | Required | Chart data points | | areaColor | string | '#000' | Area fill color | | curve | d3.CurveFactory | d3.curveLinear | D3 curve function | | opacity | number | 1 | Area opacity | | animated | boolean | false | Enable animations | | animationDuration | number | 1000 | Animation duration in ms | | animationDelay | number | 0 | Animation delay in ms |

BarChart Props

| Prop | Type | Default | Description | | ------------------- | ------------------ | --------------- | -------------------------- | | data | ChartDataPoint[] | Required | Chart data points | | barColor | string[] | ['#000'] | Bar colors array | | barWidth | number | Auto-calculated | Bar width | | spacing | number | 0.1 | Spacing between bars | | animated | boolean | false | Enable animations | | animationDuration | number | 1000 | Animation duration in ms | | animationDelay | number | 0 | Animation delay in ms | | horizontal | boolean | false | Horizontal bar orientation | | labelPadding | number | 5 | Label padding | | font | SkFont | undefined | Font for labels |

ChartDataPoint Interface

interface ChartDataPoint {
  x: number | string;
  y: number;
}

Advanced Usage

Multiple Chart Types

import React from "react";
import { CartesianChart, LineChart, AreaChart } from "exchartz";

const lineData = [
  { x: 0, y: 10 },
  { x: 1, y: 20 },
  { x: 2, y: 15 },
  { x: 3, y: 25 },
];

const areaData = [
  { x: 0, y: 5 },
  { x: 1, y: 8 },
  { x: 2, y: 12 },
  { x: 3, y: 10 },
];

export default function CombinedChart() {
  return (
    <CartesianChart
      width={400}
      height={250}
      padding={{ left: 50, right: 30, top: 30, bottom: 50 }}
      xAxis={{
        showAxis: true,
        showGrid: true,
        label: "Time (hours)",
      }}
      yAxis={{
        showAxis: true,
        showGrid: true,
        label: "Value",
      }}
    >
      <AreaChart
        data={areaData}
        areaColor="#3b82f6"
        opacity={0.3}
        animated={true}
      />
      <LineChart
        data={lineData}
        lineColor="#ef4444"
        strokeWidth={3}
        animated={true}
        animationDelay={500}
      />
    </CartesianChart>
  );
}

Custom Animations

import React from "react";
import { CartesianChart, BarChart } from "exchartz";
import * as d3 from "d3";

const data = [
  { x: "Q1", y: 100 },
  { x: "Q2", y: 150 },
  { x: "Q3", y: 120 },
  { x: "Q4", y: 180 },
];

export default function AnimatedBarChart() {
  return (
    <CartesianChart
      width={350}
      height={300}
      padding={{ left: 60, right: 30, top: 30, bottom: 60 }}
      xAxis={{
        scaleType: "band",
        showAxis: true,
        showLabels: true,
      }}
      yAxis={{
        showAxis: true,
        showGrid: true,
        tickCount: 6,
      }}
      backgroundColor="#f8fafc"
    >
      <BarChart
        data={data}
        barColor={["#3b82f6", "#10b981", "#f59e0b", "#ef4444"]}
        animated={true}
        animationDuration={1500}
        animationDelay={200}
      />
    </CartesianChart>
  );
}

Time Series Chart

import React from "react";
import { CartesianChart, LineChart } from "exchartz";
import * as d3 from "d3";

const timeData = [
  { x: new Date("2024-01-01").getTime(), y: 100 },
  { x: new Date("2024-02-01").getTime(), y: 120 },
  { x: new Date("2024-03-01").getTime(), y: 90 },
  { x: new Date("2024-04-01").getTime(), y: 150 },
];

export default function TimeSeriesChart() {
  return (
    <CartesianChart
      width={400}
      height={250}
      xAxis={{
        scaleType: "time",
        showGrid: true,
        tickCount: 4,
      }}
      yAxis={{
        showGrid: true,
      }}
    >
      <LineChart
        data={timeData}
        lineColor="#8b5cf6"
        strokeWidth={2}
        curve={d3.curveCatmullRom}
        animated={true}
      />
    </CartesianChart>
  );
}

Performance Considerations

Best Practices

1. Data Optimization: Keep data arrays reasonably sized (< 1000 points for smooth performance)
2. Animation Usage: Use animations sparingly on lower-end devices
3. Memoization: Wrap chart components in React.memo() when data doesn't change frequently
4. Reanimated Worklets: Chart animations run on the UI thread for optimal performance
5. List Size Changes: Varying the data size while animating can cause unexpected results

Memory Management

import React, { useMemo } from "react";
import { CartesianChart, LineChart } from "exchartz";

export default function OptimizedChart({ rawData }) {
  // Memoize processed data to avoid recalculations
  const chartData = useMemo(
    () =>
      rawData.map((item, index) => ({
        x: index,
        y: item.value,
      })),
    [rawData]
  );

  return (
    <CartesianChart width={300} height={200}>
      <LineChart data={chartData} />
    </CartesianChart>
  );
}

Performance Tips

• Use animated={false} for static charts
• Limit the number of data points for real-time charts
• Consider data sampling for large datasets
• Use React.memo() to prevent unnecessary re-renders
• Avoid frequent prop changes that trigger re-animations

Troubleshooting

Common Issues

Charts not rendering

• Ensure react-native-skia is properly installed and linked
• Check that chart dimensions (width, height) are provided
• Verify data format matches ChartDataPoint interface

Animations not working

• Confirm react-native-reanimated is installed and configured
• Check that animated={true} is set on chart components
• Ensure your React Native version supports Reanimated 3.x

TypeScript errors

• Install @types/d3 for D3 type definitions: npm install -D @types/d3
• Ensure your TypeScript version is 4.5 or higher

Performance issues

• Reduce data point count for smoother animations
• Disable animations on lower-end devices
• Use React.memo() to optimize re-renders

Platform-Specific Notes

iOS

• Ensure iOS deployment target is 11.0 or higher
• Add Skia framework to your iOS project if using bare React Native

Android

• Minimum SDK version should be 21 or higher
• Enable Hermes for better performance

Expo

• Use Expo SDK 49+ for best compatibility
• Ensure development build includes native dependencies

Contributing

We welcome contributions! Please follow these guidelines:

1. Fork the repository and create a feature branch
2. Write tests for new functionality
3. Follow TypeScript best practices and maintain type safety
4. Update documentation for any API changes
5. Test on both platforms (iOS and Android)

Development Setup

git clone https://github.com/mzkux/exchartz.git
cd exchartz
npm install
npm run build
npm test

Submitting Changes

1. Create a pull request with a clear description
2. Include examples of new features
3. Ensure all tests pass
4. Update README.md if needed

License

MIT License - see LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Built using React Native Skia and Reanimated