Kubit React Charts

Table of Contents

For Library Users

• Features
• Installation
• Quick Start
• Available Components
• API Reference

For Contributors & Developers

• Development Setup
• Project Architecture
• Development Scripts
• Contributing Guidelines
• License

For Library Users

💡 Cross-platform: Kubit Charts is also available for Android and iOS platforms, enabling consistent chart experiences across all your applications.

Features

Composable: Modular architecture where each chart is composed of specialized elements
Performant: Optimized SVG rendering with React 18
Accessible: WCAG compliant with keyboard navigation support
Customizable: Flexible styling and granular configurations
Responsive: Adaptable to different screen sizes
TypeScript: Fully typed for better developer experience
SSR Ready: Complete Server-Side Rendering support for Next.js, Remix, Gatsby, and more
Error Handling: Advanced centralized error management system with detailed debugging
Production Safe: Built-in logging system that's automatically optimized for production builds
Tested: Complete coverage with Vitest and Testing Library

Installation

Yarn (Recommended)

yarn add @kubit-ui-web/react-charts

NPM

npm install @kubit-ui-web/react-charts

Peer Dependencies

This library requires React as a peer dependency:

npm install react react-dom
# or
yarn add react react-dom

Compatible versions:

• React: ^18.3.1
• React DOM: ^18.3.1

Tree-Shaking Support

The library supports granular imports for optimal bundle size:

// Import specific charts only
import { BarChart } from '@kubit-ui-web/react-charts/charts/barChart';
import { LineChart } from '@kubit-ui-web/react-charts/charts/lineChart';
// Import specific components only
import { Node } from '@kubit-ui-web/react-charts/components/node';
import { Path } from '@kubit-ui-web/react-charts/components/path';
// Import specific utilities only
import { logger } from '@kubit-ui-web/react-charts/utils/logger';
import { isBrowser } from '@kubit-ui-web/react-charts/utils/ssr';

Quick Start

Importing Components

// Import complete charts
import { BarChart, LineChart, PieChart } from '@kubit-ui-web/react-charts';
// Import specific components
import { Node, Path, Plot } from '@kubit-ui-web/react-charts/components';
// Import types
import type { BarOrientation, ChartData } from '@kubit-ui-web/react-charts/types';
// Import utilities
import { configureLogger, logger } from '@kubit-ui-web/react-charts/utils';
import { createSVGElement, isBrowser, safeWindow } from '@kubit-ui-web/react-charts/utils';

LineChart Example

import { LineChart } from '@kubit-ui-web/react-charts';
import React from 'react';

const data = [
  { year: '2020', sales: 100, profit: 20 },
  { year: '2021', sales: 150, profit: 35 },
  { year: '2022', sales: 180, profit: 45 },
  { year: '2023', sales: 200, profit: 60 },
];

function MyLineChart() {
  return (
    <LineChart data={data} xKey="year" width="100%" height="400px">
      <LineChart.Path dataKey="sales" stroke="#0078D4" strokeWidth={2} />
      <LineChart.Path dataKey="profit" stroke="#FF6B35" strokeWidth={2} />
      <LineChart.XAxis position="BOTTOM" showTickLines />
      <LineChart.YAxis position="LEFT" valueFormatter={val => `$${val}k`} />
    </LineChart>
  );
}

BarChart Example

import { BarChart, BarOrientation } from '@kubit-ui-web/react-charts';
import React from 'react';

const data = [
  { category: 'A', value: 30 },
  { category: 'B', value: 45 },
  { category: 'C', value: 25 },
  { category: 'D', value: 60 },
];

function MyBarChart() {
  return (
    <BarChart
      data={data}
      pKey="category"
      orientation={BarOrientation.VERTICAL}
      gapBetweenBars={5}
      width="100%"
      height="400px"
    >
      <BarChart.Path
        dataKey="value"
        dataIdx={0}
        barConfig={{
          barWidth: 40,
          singleConfig: [{ color: '#0078D4', coverage: 100 }],
        }}
      />
      <BarChart.XAxis position="BOTTOM" />
      <BarChart.YAxis position="LEFT" />
    </BarChart>
  );
}

Error Handling Example

import { LineChart } from '@kubit-ui-web/react-charts';
import type { ChartErrorCollection } from '@kubit-ui-web/react-charts/types';
import React from 'react';

function ChartWithErrorHandling() {
  const handleErrors = (errors: ChartErrorCollection) => {
    // Centralized error handling
    console.warn('Chart errors:', errors);
    // Display user-friendly messages or retry logic
  };

  return (
    <LineChart data={data} xKey="year" onErrors={handleErrors} width="100%" height="400px">
      <LineChart.Path dataKey="sales" stroke="#0078D4" />
      <LineChart.XAxis position="BOTTOM" />
      <LineChart.YAxis position="LEFT" />
    </LineChart>
  );
}

SSR (Server-Side Rendering) Support

import { LineChart, isBrowser, safeWindow } from '@kubit-ui-web/react-charts';
import React from 'react';

function SSRCompatibleChart() {
  // Safe browser API access
  const windowWidth = isBrowser() ? safeWindow()?.innerWidth || 800 : 800;

  return (
    <LineChart data={data} xKey="year" width={windowWidth} height="400px">
      <LineChart.Path dataKey="sales" stroke="#0078D4" />
    </LineChart>
  );
}

Logger Configuration

import { configureLogger, logger } from '@kubit-ui-web/react-charts';

// Configure logger for development
configureLogger({
  enabled: true,
  minLevel: 'debug',
  prefix: '[MyApp Charts]',
});

// Use logger in your components
function MyComponent() {
  logger.info('Chart rendering started');
  // Chart implementation
}

Available Components

Main Charts

| Component | Description | Use Cases | | --------------- | ----------------------------- | ----------------------------------- | | LineChart | Multi-series line chart | Time trends, metric comparisons | | BarChart | Horizontal/vertical bar chart | Category comparisons, discrete data | | PieChart | Circular chart with segments | Part-to-whole relationships |

Base Components

| Component | Description | | --------------- | ----------------------------- | | Plot | Base SVG container for charts | | Path | Customizable SVG path element | | Node | Interactive points in charts | | Line | Lines and connectors | | Bar | Rectangular bars | | ChartText | Formatted text for labels |

Available Hooks

| Hook | Description | | -------------- | ---------------------------------------- | | useFocus | Focus state management for accessibility | | useHover | Hover detection with callbacks |

Utility Functions

| Utility | Description | | ---------------------------- | -------------------------------------------------- | | logger | Production-safe logging with configurable levels | | configureLogger | Logger configuration for development/debugging | | isBrowser | Environment detection for browser vs SSR | | isServer | Check if running in server-side environment | | safeWindow | Safe access to window object in SSR environments | | safeDocument | Safe access to document object in SSR environments | | createSVGElement | SSR-compatible SVG element creation | | createErrorAccumulator | Advanced error management for chart components |

API Reference

For detailed API documentation, component props, and advanced examples, please refer to our individual component READMEs:

• BarChart Documentation
• LineChart Documentation
• PieChart Documentation

For Contributors & Developers

Development Setup

Environment Requirements

• Node.js >= 16
• Yarn (recommended) or npm
• Git

Getting Started

1. Clone the repository

   git clone https://github.com/kubit-ui/kubit-react-charts
   cd web-ui-charts/app

2. Install dependencies

   yarn install

3. Start development server

   yarn start

This will launch Storybook at http://localhost:6006 where you can interact with all components.

Project Architecture

src/
├── charts/           # High-level chart components
│   ├── barChart/     # BarChart and subcomponents
│   ├── lineChart/    # LineChart and subcomponents
│   └── pieChart/     # PieChart and subcomponents
├── components/       # Reusable SVG base components
│   ├── plot/         # Main SVG container
│   ├── path/         # Path elements
│   ├── node/         # Interactive points
│   ├── line/         # Lines and connectors
│   └── ...
├── hooks/            # Custom hooks
├── types/            # TypeScript definitions
├── utils/            # Shared utility functions
└── storybook/        # Storybook configuration and constants

Composition Pattern

Each chart follows a consistent compositional pattern:

const LineChart = Object.assign(LineChartStructure, {
  Path: LineChartPath,
  XAxis: LineChartXAxis,
  YAxis: LineChartYAxis,
  Separator: LineChartSeparator,
});

This pattern enables:

• Flexibility: Use only the components you need
• Reusability: Shared components between different charts
• Extensibility: Easy addition of new subcomponents

Development Scripts

Main Commands

# Start Storybook in development mode
yarn start

# Build library for production
yarn dist

# Run tests with coverage
yarn test

# Lint code with ESLint
yarn eslint

# Format code
yarn format

# Build Storybook for production
yarn build

# Changeset commands (for maintainers)
yarn changeset              # Create a changeset manually
yarn changeset:version      # Version packages
yarn changeset:publish      # Publish to NPM
yarn changeset:status       # Check changeset status

# Run accessibility tests
yarn storybook:axe

Build Commands

# Complete build (ESM + CJS)
yarn dist

# Build in watch mode
yarn dist:watch

# CommonJS only
yarn dist:cjs

# ES Modules only
yarn dist:esm

Testing Commands

# Unit tests with UI
yarn vitest-report

# Storybook tests
yarn test-storybook

# ESLint only
yarn eslint --fix

Contributing

Code Standards

• TypeScript: Fully typed code
• ESLint: Strict configuration with Kubit rules
• Prettier: Automatic code formatting
• Testing: Minimum 80% coverage

Contribution Workflow

See our CONTRIBUTING for coding conventions, commit message guidelines, and pull request processes.

Component Development Guidelines

Please refer to our development instructions for detailed guidelines on:

• Component structure and patterns
• Naming conventions
• TypeScript usage
• Error handling
• CSS and styling
• Accessibility requirements

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.