handwritten-graph

Handwritten Graph Library (TypeScript)

A modern TypeScript library for creating hand-drawn style charts inspired by comics and sketches. Built with D3.js and designed with type safety and excellent developer experience in mind.

Documentation

Example

Here’s some example of a graph generated with this library:

Bar charts

Pie charts

Donut charts

Complete API Documentation

📚 Live Demo | 📖 Quick Start

Features

• 🎨 Hand-drawn/sketched visual style - Authentic comic-book aesthetic
• 📊 Multiple chart types - Line graphs, bar charts, and pie charts
• 🔧 TypeScript support - Full type definitions and IntelliSense
• 🎯 Multi-series support - Handle complex datasets with ease
• 🎭 Interactive tooltips - Hover effects with detailed information
• 🎪 Directional scribble fills - Artistic fill patterns for charts
• 🎨 Oil paint textures - Rich watercolor-like effects
• ⚙️ Highly configurable - Extensive customization options
• 🧩 Modern architecture - Clean OOP design with proper separation of concerns

Installation

npm install handwritten-graph

Or via CDN:

<script src="https://unpkg.com/handwritten-graph@latest/dist/handwritten-graph.js"></script>

Quick Start

TypeScript/ES6 Modules

import { LineChart, BarChart, PieChart } from 'handwritten-graph';

// Sample data that can be reused across chart types
const chartData = {
  labels: ["Q1", "Q2", "Q3", "Q4"],
  datasets: [
    {
      label: "Revenue",
      data: [65, 59, 80, 81],
      lineColor: "rgb(75, 192, 192)", // For LineChart
      barColor: "#36A2EB" // For BarChart
    }
  ]
};

// Line Chart with Area Fill
const lineChart = new LineChart("#line-chart-container", chartData, {
  showArea: true,
  useScribbleFill: true
});

// Bar Chart (Vertical)
const barChart = new BarChart("#bar-chart-container", chartData, {
  orientation: 'vertical',
  showValues: true
});

// Horizontal Bar Chart
const horizontalBarChart = new BarChart("#horizontal-bar-container", chartData, {
  orientation: 'horizontal'
});

// Pie Chart
const pieData = [
  { label: "Marketing", value: 30, color: "#FF6384" },
  { label: "Development", value: 45, color: "#36A2EB" },
  { label: "Research", value: 15, color: "#FFCE56" },
  { label: "Administration", value: 10, color: "#4BC0C0" }
];

const pieChart = new PieChart("#pie-chart-container", pieData, {
  useScribbleFill: true,
  fillStyle: 'directional'
});

Legacy/JavaScript (Factory Functions)

// Using factory functions for backward compatibility
const lineCleanup = HandwrittenGraph.createGraph("#graph-container", chartData);
const barCleanup = HandwrittenGraph.createBarChart("#bar-container", chartData);
const pieCleanup = HandwrittenGraph.createPieChart("#pie-container", pieData);

// Clean up when done
lineCleanup();
barCleanup();
pieCleanup();

API Reference

Chart Classes

// Line Chart
new LineChart(selector: string, data: LineChartData, config?: Partial)

// Bar Chart  
new BarChart(selector: string, data: BarChartData, config?: Partial)

// Pie Chart
new PieChart(selector: string, data: PieChartData, config?: Partial)

Key Configuration Options

interface BaseChartConfig {
  width?: number;
  height?: number;
  handDrawnEffect?: boolean;
  useScribbleFill?: boolean; // Enable artistic fill patterns
  fillStyle?: 'directional' | 'oilpaint'; // Fill pattern style
}

// LineChart specific
interface LineChartConfig extends BaseChartConfig {
  showArea?: boolean; // Enable area fill under lines
  pointRadius?: number;
  lineColor?: string;
}

// BarChart specific  
interface BarChartConfig extends BaseChartConfig {
  orientation?: 'vertical' | 'horizontal'; // Chart orientation
  showValues?: boolean; // Show value labels on bars
  barSpacing?: number;
  groupSpacing?: number;
}

// PieChart specific
interface PieChartConfig extends BaseChartConfig {
  innerRadius?: number; // For donut charts
  legendBorder?: boolean;
}

Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• Modern mobile browsers

Development

# Install dependencies
npm install

# Development build with watch
npm run dev

# Production build
npm run build

# Testing
npm run test

Architecture

The library follows modern TypeScript patterns:

• Object-Oriented Design: Charts are classes with proper encapsulation
• Type Safety: Full TypeScript definitions with strict typing
• Composition: Modular utilities and components
• Inheritance: Base chart class with shared functionality
• Factory Pattern: Backward-compatible factory functions
• Strategy Pattern: Pluggable fill styles and effects

License

MIT License - see LICENSE file for details.

Changelog

v1.0.6

• ENHANCED: Blob shapes improved to have better borders, and soft boundaries
• ENHANCED: Improve pastel/pencil color conversion for hand-drawn aesthetics
• OPTIMIZED: Improve rendering performance with reduced filter complexity
• OPTIMIZED: Pattern caching system reduce memory footprint
• FIXED: Improved scribble lines to cover fill areas properly

v1.0.5

• NEW: BarChart support with vertical and horizontal orientations
• NEW: Area fill support for LineCharts with showArea option
• NEW: Multi-series support for BarCharts
• NEW: Value labels on bar charts with showValues option
• ENHANCED: Improved scribble fill patterns for all chart types
• ENHANCED: Better responsive design and styling
• ENHANCED: Seamless pie chart borders matching slice colors

v1.0.4

• Update test suite
• Add test coverage
• Type check scripts
• Type definition publish support

v1.0.3

• Comprehensive test suite
• Test Setup with D3 mocks
• Example html to preview built lib

v1.0.2

• Text elements with proper SVG property handling
• Axes and grid styling
• Line chart elements
• Pie chart elements
• Legend and Tooltip styling
• Hand-drawn effects
• Responsive design
• Print styles

v1.0.1

• Enhanced type definitions
• Improved performance
• Better error handling

v1.0.0

• Complete TypeScript rewrite from handwritten-graph
• Modern class-based architecture