Chart.js Administrator & Developer Guide

Chart.js v4.5.1 is a canvas-based charting library for the browser and Node.js. This guide covers everything an administrator, integrator, or contributing developer needs to understand the internals, configure builds, deploy at scale, and troubleshoot production issues. See the User Guide for usage examples.

1. Architecture Overview

1.1 Design Philosophy

Chart.js is a modular, plugin-driven rendering engine that draws charts onto HTML5 <canvas> elements. The architecture follows a registry pattern where controllers, elements, scales, and plugins are registered at runtime. This enables tree-shaking for ESM consumers while providing a batteries-included UMD bundle for CDN usage.

1.2 Core Subsystems

The engine is organized into seven subsystems, each with a well-defined responsibility:

1.3 Component Flow

User Config
    │
    ▼
Config Resolver ──► Scope Chain (dataset → type overrides → defaults)
    │
    ▼
Registry ──► Resolves controllers, scales, elements, plugins by ID
    │
    ▼
Chart Controller
    ├── Layout Engine (positions boxes: title, legend, scales, chart area)
    ├── Dataset Controllers (bar, line, pie, etc.)
    │       └── Elements (Arc, Bar, Line, Point)
    ├── Scales (category, linear, log, time, radial)
    ├── Plugins (lifecycle hooks: beforeInit → ... → destroy)
    └── Animator (singleton RAF loop)
            └── Animation instances (from → to interpolation)

1.4 Class Hierarchy

1.5 Runtime Dependency

Chart.js has exactly one runtime dependency:

All other devDependencies (Rollup, Karma, Jasmine, SWC, etc.) are build-time only.

Important

Chart.js has zero CLI commands, zero REST API endpoints, zero server-side actions, and zero filters. It is a pure client-side library. Do not look for backend configuration sections -- they do not exist.

2. System Requirements

2.1 Build Environment

2.2 Browser Support

Chart.js targets ES2018 (per .eslintrc.yml) and transpiles to ES2022 via SWC in the build step. Runtime requirements:

2.3 Node.js / SSR Requirements

For server-side rendering, Chart.js needs a canvas implementation (e.g., canvas or @napi-rs/canvas) that provides a 2D context. The BasicPlatform is auto-selected when OffscreenCanvas is available or the context is not a browser DOM element. The BasicPlatform disables animations automatically.

2.4 pnpm Workspace

The repository uses a pnpm workspace defined in pnpm-workspace.yaml:

packages:
  - docs
  - test/integration/*

This means pnpm install at root handles all sub-packages, including the VuePress documentation site and integration test projects.

3. Configuration Reference

3.1 Config Resolution Chain

The config resolver (src/core/core.config.js) implements a scope-chain lookup. When Chart.js resolves an option value, it traverses scopes in this order:

1. Dataset-level options (highest priority)
2. Chart type overrides (Chart.overrides[type])
3. Global defaults (Chart.defaults)
4. Descriptors (internal metadata)

Key resolver methods:

Note

The config resolver uses aggressive caching for scope keys and resolvers. If you modify Chart.defaults after chart creation, call chart.update() to force re-resolution. Mutations to nested default objects are picked up automatically through the proxy mechanism, but adding entirely new scope branches requires a full update cycle.

3.2 Scale Auto-Detection

The config system auto-detects axis type from the scale ID or its position property:

• ID starting with x or position top/bottom maps to the x-axis
• ID starting with y or position left/right maps to the y-axis
• ID r maps to the radial axis

Scale defaults are then merged per chart type, so a bar chart's x-axis gets CategoryScale defaults while a scatter chart's x-axis gets LinearScale defaults.

3.3 Animation Configuration

Available easing functions (31 total in helpers.easing.js): linear, easeInQuad, easeOutQuad, easeInOutQuad, easeInCubic, easeOutCubic, easeInOutCubic, easeInQuart, easeOutQuart, easeInOutQuart, easeInQuint, easeOutQuint, easeInOutQuint, easeInSine, easeOutSine, easeInOutSine, easeInExpo, easeOutExpo, easeInOutExpo, easeInCirc, easeOutCirc, easeInOutCirc, easeInElastic, easeOutElastic, easeInOutElastic, easeInBack, easeOutBack, easeInOutBack, easeInBounce, easeOutBounce, easeInOutBounce.

3.4 Colors Plugin Palette

The built-in ColorsPlugin (src/plugins/plugin.colors.ts) assigns default colors when the user has not specified any:

Background colors are the same with 0.5 opacity. For Doughnut and PolarArea charts, colors rotate per data point (slice). For all other chart types, colors apply per dataset. The plugin skips assignment if the user has already defined backgroundColor or borderColor, unless forceOverride: true is set.

3.5 Decimation Plugin Configuration

Warning

The decimation plugin only works with line charts using a linear or time x-axis and parsing: false. If any of these conditions are not met, decimation silently does nothing. The plugin replaces dataset.data via a getter/setter, so the original data array is preserved internally.

3.6 Interaction Modes

3.7 Plugin Lifecycle Hooks

Plugins receive these hooks in order during the chart lifecycle:

install → start → beforeInit → afterInit →
  [per update cycle:]
    beforeUpdate → beforeElementsUpdate → beforeDatasetsUpdate →
      beforeDatasetUpdate → afterDatasetUpdate (per dataset) →
    afterDatasetsUpdate → afterUpdate →
    beforeLayout → afterLayout →
    beforeRender →
      beforeDraw →
        beforeDatasetsDraw →
          beforeDatasetDraw → afterDatasetDraw (per dataset) →
        afterDatasetsDraw →
      afterDraw →
    afterRender →
  [per event:]
    beforeEvent → afterEvent →
  resize →
  stop → uninstall → destroy

3.8 Fill Modes (Filler Plugin)

The filler plugin (src/plugins/plugin.filler/, 8 files, ~20K chars) supports these fill targets:

4. Deployment & Scaling

4.1 Build System

Chart.js uses Rollup with SWC transpilation. The build produces four output variants from rollup.config.js:

Build plugins in use:

4.2 Package Exports

The package.json exports map provides three entry points:

{
  "chart.js": {
    "import": "dist/chart.js",
    "require": "dist/chart.cjs"
  },
  "chart.js/auto": "auto-registers all built-in components",
  "chart.js/helpers": "dist/helpers.js / dist/helpers.cjs"
}

• chart.js -- Tree-shakeable ESM/CJS entry. Consumers must manually Chart.register(...) the components they need.
• chart.js/auto -- Auto-registers all controllers, elements, scales, and plugins. Convenient but prevents tree-shaking.
• chart.js/helpers -- Utility functions for plugin/extension authors.

Type definitions ship as dist/types.d.ts. The sideEffects field marks auto and UMD builds as having side effects (they auto-register components on import).

4.3 Reproducible Builds

The Rollup config reads the SOURCE_DATE_EPOCH environment variable for reproducible builds. Set this to a Unix timestamp to ensure deterministic output:

SOURCE_DATE_EPOCH=$(date +%s) pnpm build

4.4 CDN Deployment

The UMD bundle is designed for CDN delivery:

<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/chart.js@4.5.1/dist/chart.umd.min.js"></script>

<!-- unpkg -->
<script src="https://unpkg.com/chart.js@4.5.1/dist/chart.umd.min.js"></script>

The UMD entry (src/index.umd.ts) auto-registers all built-in components, so no additional setup is needed for <script> tag usage.

Tip

For production deployments, always pin a specific version (e.g., chart.js@4.5.1) rather than using @latest. Chart.js major and minor versions can change default behavior, scale types, or plugin APIs.

4.5 npm Scripts Reference

4.6 Tree-Shaking Guide

To minimize bundle size in modern bundlers (webpack, Rollup, Vite, esbuild):

1. Import from chart.js (not chart.js/auto)
2. Register only the components you use:

import {
  Chart,
  LineController,
  LineElement,
  PointElement,
  LinearScale,
  CategoryScale,
  Tooltip,
  Legend
} from 'chart.js';

Chart.register(
  LineController,
  LineElement,
  PointElement,
  LinearScale,
  CategoryScale,
  Tooltip,
  Legend
);

3. The sideEffects field in package.json correctly marks chart.js/auto and UMD builds, so bundlers will not tree-shake those entry points.

5. Operations

5.1 Chart Instance Management

The Chart class maintains a singleton instances map keyed by a numeric chart ID:

Chart.instances  // Map of all active chart instances
Chart.getChart(canvasOrId)  // Retrieve chart bound to a canvas element or ID string

Caution

Chart.js prevents reuse of a canvas that already has a chart bound to it. You must call chart.destroy() before creating a new chart on the same canvas. Failure to do so throws an error and leaves the canvas in an inconsistent state. This is the single most common issue in SPA frameworks (React, Vue, Angular) where components remount.

5.2 Memory Management

Each Chart instance holds references to:

• The canvas element and its 2D rendering context
• All dataset data arrays
• Parsed data caches
• Animation state
• Event listener proxies on the DOM

Cleanup checklist:

1. Call chart.destroy() -- this removes event listeners, clears animations, and deletes the instance from Chart.instances
2. In SPA frameworks, destroy in the unmount/cleanup lifecycle hook
3. The decimation plugin replaces dataset.data with getter/setter proxies; destroy() cleans these up

5.3 Resize Behavior

The DomPlatform uses ResizeObserver to detect container size changes and MutationObserver for canvas attach/detach events. It also listens for devicePixelRatio changes (e.g., dragging a window between monitors with different DPIs).

The internal _doResize method is debounced using the resizeDelay option. Set this to a non-zero value (e.g., 100) if resize events cause excessive redraws.

5.4 Testing Infrastructure

Browser tests: Karma + Jasmine (karma.conf.cjs)

• Fixture-based visual regression tests in test/fixtures/
• Coverage via Istanbul when running test-ci-karma

Integration tests (in test/integration/):

5.5 Linting & Code Quality

ESLint (.eslintrc.yml):

• Extends the chartjs shared config
• Enforces ES2018 language restrictions
• TypeScript support for .ts files
• Cache enabled for incremental linting

Code Climate (.codeclimate.yml):

• Duplication detection enabled
• FIXME/TODO comment detection
• Argument count threshold: 5
• Method complexity threshold: 7

6. Performance

6.1 Rendering Pipeline

Each chart.update() call triggers this pipeline:

1. Config resolution -- resolves all scriptable options against context
2. Layout -- positions boxes (title, legend, scales) using the box layout engine
3. Scale update -- tick generation, auto-skip, label sizing
4. Dataset update -- maps data to pixel positions, applies stacking
5. Animation -- creates/updates Animation instances for changed properties
6. Render -- draws to canvas via the Animator singleton's RAF loop

6.2 Data Decimation

For large datasets (thousands of points), the decimation plugin is critical:

Min-Max algorithm (default):

• Preserves local minima and maxima
• Fast O(n) single pass
• Good for data where peaks matter

LTTB algorithm (Largest Triangle Three Buckets):

• Better visual fidelity for general datasets
• O(n) complexity
• Configured via samples option

Tip

Enable decimation for any line chart with more than a few hundred data points. Set parsing: false and use a linear or time x-axis. The threshold defaults to 4 * chartWidth pixels, meaning decimation only activates when data points significantly outnumber pixels.

6.3 Animation Performance

The Animator is a singleton that runs a single requestAnimationFrame loop for all active chart instances. Optimizations:

• Animations that have completed are automatically cleaned up
• The loop stops entirely when no animations are active
• transitions.resize.animation.duration = 0 ensures resize is instant
• Set animation: false globally to disable all animations (recommended for dashboards with frequent updates)

// Disable animations for real-time dashboards
new Chart(ctx, {
  options: {
    animation: false,
    transitions: {
      active: { animation: { duration: 0 } }
    }
  }
});

6.4 Tick Auto-Skip

The auto-skip system (src/core/core.scale.autoskip.js) prevents label overlap on axes by calculating maximum fitting labels based on:

• Label rotation angle
• Available pixel space
• Font size and padding

This runs on every scale update. For extremely dense tick sets, auto-skip can become a bottleneck; consider setting explicit ticks.maxTicksLimit to cap computation.

6.5 Performance Checklist

7. Security

7.1 Threat Model

Chart.js is a client-side rendering library. The primary security concerns are:

1. Cross-Site Scripting (XSS) via data injection -- Chart.js renders to <canvas>, which does not interpret HTML or execute scripts. Canvas drawing operations are inherently safe against XSS.
2. Prototype pollution -- The config resolution chain uses deep merging. Chart.js's helpers.core.js implements isObject() checks but consumers must sanitize untrusted config input.
3. Denial of Service -- Extremely large datasets or deeply nested configs can cause browser tab crashes. Apply data limits at the application layer.

Warning

While canvas rendering is XSS-safe, the tooltip plugin can render custom HTML via the external callback. If you use external tooltips that inject user-supplied data into the DOM, you must sanitize that data. The default tooltip uses canvas rendering and is safe.

7.2 Supply Chain

Chart.js has exactly one runtime dependency (@kurkle/color). The attack surface is minimal. The build toolchain (Rollup, SWC, Karma, etc.) runs at development time only and is not shipped to consumers.

7.3 Content Security Policy

For CSP-compliant environments:

• Chart.js does not use eval() or new Function()
• No inline styles are injected into the DOM
• Canvas operations do not require unsafe-inline or unsafe-eval
• Required CSP directives: none beyond the defaults

7.4 Data Validation

Chart.js does not validate incoming data types at the boundary. It expects numeric values where numbers are needed and trusts the caller. For applications accepting user-supplied chart data, validate at the application layer before passing to Chart.js.

8. Developer Internals

8.1 Chart Class Deep Dive

The Chart class (src/core/core.controller.js, ~1500 lines) is the central orchestrator.

Constructor accepts:

• An HTMLCanvasElement
• A string ID (looks up canvas by DOM ID)
• A CanvasRenderingContext2D
• A jQuery-like wrapper (extracts first element)

Static members:

Instance methods:

8.2 Registry Internals

The Registry class holds four TypedRegistry instances:

Registry
├── controllers  (TypedRegistry<DatasetController>)
├── elements     (TypedRegistry<Element>)
├── scales       (TypedRegistry<Scale>)
└── plugins      (TypedRegistry<Plugin>)

Each TypedRegistry enforces that registered components have a string id property. Registration fails with the error "class does not have id: " if this is missing.

Lookup methods: getController(id), getElement(id), getScale(id), getPlugin(id).

The add(...) and remove(...) methods accept varargs of individual components or arrays, enabling batch registration:

Chart.register(BarController, BarElement, CategoryScale, LinearScale);
Chart.register([Tooltip, Legend, Title]);

8.3 Controllers (8 Chart Types)

All controllers extend DatasetController (src/core/core.datasetController.js), which provides the base update/draw/hit-test cycle.

8.4 Scale System

Hierarchy:

Scale (core.scale.js)
├── CategoryScale (scale.category.js)
├── LinearScale (scale.linear.js)
│   └── extends LinearScaleBase (scale.linearbase.js)
├── LogarithmicScale (scale.logarithmic.js)
│   └── extends LinearScaleBase
├── RadialLinearScale (scale.radialLinear.js) — radar/polar with point labels
├── TimeScale (scale.time.js) — requires DateAdapter
│   └── TimeSeriesScale (scale.timeseries.js) — evenly-spaced variant

Tick generation:

• Linear scales use the niceNum algorithm for human-friendly intervals
• Logarithmic scales use log10-based tick placement
• Time scales delegate to a DateAdapter implementation

Important

The TimeScale and TimeSeriesScale require a DateAdapter implementation. Chart.js ships only the abstract DateAdapterBase (src/core/core.adapters.ts). You must install an adapter like chartjs-adapter-date-fns, chartjs-adapter-luxon, or chartjs-adapter-moment. Without one, any method call throws: "This method is not implemented: Check that a complete date adapter is provided."

8.5 Elements (4 Visual Primitives)

Elements are the lowest-level visual components. Each element knows how to draw itself on a canvas context and calculate its bounding box for hit detection.

8.6 Platform Abstraction

The platform layer (src/platform/) provides environment-specific functionality:

Platform detection (_detectPlatform(canvas)):

• If canvas is an OffscreenCanvas or not a DOM element: BasicPlatform
• Otherwise: DomPlatform

DomPlatform provides:

• ResizeObserver for container size monitoring
• MutationObserver for canvas DOM attachment changes
• devicePixelRatio change listener (multi-monitor support)
• Throttled event proxies for pointer/touch/mouse events
• Touch-to-mouse event mapping: touchstart→mousedown, touchmove→mousemove, touchend→mouseup, pointerenter→mouseenter

BasicPlatform provides:

• Minimal acquireContext that works with non-DOM canvases
• Animations disabled by default
• No event binding

8.7 Helpers Library (18 Modules)

The src/helpers/ directory (100K chars) provides utility functions exported via chart.js/helpers:

8.8 Built-in Plugins (7)

8.9 Writing Custom Plugins

A Chart.js plugin is an object with an id property and any subset of the lifecycle hooks:

const myPlugin = {
  id: 'myPlugin',
  
  // Called once when plugin is registered
  install(chart, args, options) {},
  
  // Called when chart starts using this plugin
  start(chart, args, options) {},
  
  // Before/after each update cycle
  beforeUpdate(chart, args, options) {},
  afterUpdate(chart, args, options) {},
  
  // Before/after each draw
  beforeDraw(chart, args, options) {},
  afterDraw(chart, args, options) {},
  
  // Event handling
  beforeEvent(chart, args, options) {},
  afterEvent(chart, args, options) {},
  
  // Cleanup
  destroy(chart, args, options) {},
  uninstall(chart, args, options) {},
};

Chart.register(myPlugin);

Plugin options are resolved through the config scope chain at options.plugins[pluginId].

8.10 Writing Custom Scales

Extend the Scale base class and register:

class CustomScale extends Chart.Scale {
  static id = 'custom';
  static defaults = {};

  determineDataLimits() {
    // Set this.min and this.max
  }
  
  buildTicks() {
    // Return array of {value, label} tick objects
    return [];
  }
  
  getPixelForValue(value) {
    // Convert data value to pixel coordinate
  }
  
  getValueForPixel(pixel) {
    // Convert pixel coordinate to data value
  }
}

Chart.register(CustomScale);

9. Integration Points

9.1 Framework Integration Patterns

React: Use useRef for the canvas and useEffect for lifecycle:

useEffect(() => {
  const chart = new Chart(canvasRef.current, config);
  return () => chart.destroy(); // Critical cleanup
}, []);

Vue: Use onMounted/onBeforeUnmount:

onMounted(() => {
  chart = new Chart(canvasRef.value, config);
});
onBeforeUnmount(() => {
  chart?.destroy();
});

Angular: Use ngAfterViewInit/ngOnDestroy with @ViewChild.

Note

In all SPA frameworks, the most critical requirement is calling chart.destroy() in the cleanup/unmount hook. Without this, you will see errors about canvas reuse, memory leaks from retained event listeners, and orphaned animation loops.

9.2 Server-Side Rendering

For generating chart images on the server:

1. Install a canvas implementation: npm install canvas (node-canvas) or @napi-rs/canvas
2. Import and create a canvas:

import { createCanvas } from 'canvas';
import { Chart } from 'chart.js/auto';

const canvas = createCanvas(800, 400);
const chart = new Chart(canvas, { /* config */ });
const buffer = canvas.toBuffer('image/png');

The BasicPlatform is auto-selected and disables animations. No DOM is needed.

9.3 Web Worker Rendering

Chart.js can render in a Web Worker using OffscreenCanvas:

// Main thread
const offscreen = canvas.transferControlToOffscreen();
worker.postMessage({ canvas: offscreen }, [offscreen]);

// Worker
self.onmessage = ({ data: { canvas } }) => {
  const chart = new Chart(canvas, config);
};

The BasicPlatform is auto-detected for OffscreenCanvas instances.

9.4 Date Adapter Integration

Time-based scales require a date adapter. The adapter must extend DateAdapterBase and implement:

Popular adapters: chartjs-adapter-date-fns, chartjs-adapter-luxon, chartjs-adapter-moment, chartjs-adapter-dayjs-4.

9.5 TypeScript Integration

Type definitions are exported from dist/types.d.ts. Key types:

import type {
  ChartConfiguration,
  ChartData,
  ChartOptions,
  ChartType,
  Plugin,
  Scale,
  Element,
  DatasetController
} from 'chart.js';

Tip

The integration test suite validates TypeScript compatibility under both moduleResolution: Node and moduleResolution: NodeNext. If you encounter type resolution issues, ensure your tsconfig.json matches one of these tested configurations.

10. Troubleshooting

10.1 Error Reference

10.2 Known Issues (from GitHub)

10.3 Common Pitfalls

Canvas reuse without destroy:

Error: Canvas is already in use. Chart with ID '0' must be destroyed before...

Prevention: Always call chart.destroy() before creating a new chart on the same canvas element.

Missing scale registration: Chart renders empty with no visible errors. Prevention: When using tree-shaken imports from chart.js, ensure you register all required scale types (CategoryScale, LinearScale, etc.).

Time scale without adapter: Throws "This method is not implemented" on first render. Prevention: Install and import a date adapter before creating a time-based chart.

Decimation not activating: Data points still render at full density despite enabling the plugin. Prevention: Verify all three prerequisites: (1) line chart, (2) linear or time x-axis, (3) parsing: false.

Caution

When updating chart data in-place (e.g., chart.data.datasets[0].data.push(newPoint)), you must call chart.update() afterward. Chart.js does not observe array mutations. Failing to call update() leaves the visual state stale, and can cause tooltip/interaction errors when internal metadata is out of sync with the data.