chartjs-plugin-datalabels

chartjs-plugin-datalabels renders data labels directly on Chart.js data elements — bars, points, arcs, and more — with per-dataset and per-label overrides for color, alignment, anchor, rotation, and formatting. It plugs into Chart.js’s plugin system via a single Chart.register call and works with any chart type Chart.js supports, from pie and doughnut charts to complex mixed and stacked bar charts.

Rather than drawing labels as a fixed overlay, the plugin computes label geometry per element (arcs use angle/radius math, bars and points use dimension-aware positioning) and resolves collisions against a hitbox model to keep dense charts readable. Options can be scriptable functions evaluated per data point, letting label content, color, and visibility respond to the underlying data at render time.

What You Get

• Per-dataset and per-label datalabel configuration overriding global defaults
• Automatic label positioning with anchor/align/offset controls plus a collision-aware hitbox layout pass
• Scriptable options (functions evaluated per data point) for dynamic label content, color, and formatting
• Built-in TypeScript type definitions that extend Chart.js’s own plugin option types
• Label click/enter/leave event listeners for interactive labels

Common Use Cases

• Displaying exact values or percentages on pie/doughnut slices without a separate legend
• Highlighting key data points on line/bar charts (totals, thresholds, outliers)
• Building dashboards where every chart needs consistent label formatting across chart types
• Conditionally showing/hiding labels based on data density to avoid overlap
• Adding interactive labels that respond to click/hover events

Under The Hood

Architecture

plugin.js is the Chart.js plugin entry point — it registers lifecycle hooks into Chart.js’s plugin API that call configure() to merge per-chart, per-dataset, and per-label option objects (global defaults from defaults.js merged with each dataset’s datalabels overrides), then builds a Label instance (label.js) per data element that computes text content and a geometry box. layout.js runs a general layout/collision pass across all active labels using hitbox.js’s box model to keep labels within their allowed positioning area and reduce overlap. positioners.js resolves Chart.js-specific anchor points per element type (arc, point, bar). Data flows from Chart.js’s render loop through the plugin’s draw hook, into configure(), into per-element Label objects, through layout() for final positioning, and out to each Label’s own canvas draw call. Because every consumer’s per-dataset overrides and the merge() calls in plugin.js assume the option shape defined in defaults.js, changing that shape would ripple through the whole configuration-resolution pipeline.

Tech Stack

A plain JavaScript library with no runtime framework — ES modules with a single peerDependency on chart.js (>=3.0.0, developed against ^4.0.0). Built with Rollup (commonjs/node-resolve/terser plugins) into UMD and ESM bundles. Type definitions are hand-authored under types/ and checked separately via a dedicated TypeScript test project. Linting runs through ESLint with eslint-config-chartjs. The documentation site is built with VuePress from the docs/ directory and deployed to Netlify. There is no server or database component — it is purely a browser-side canvas-rendering plugin.

Code Quality

Tests live under test/specs (54 spec files) and run through Karma + Jasmine against a real Firefox instance rather than a DOM-mocking harness, with coverage collected via karma-coverage and rollup-plugin-istanbul instrumentation. Type correctness is verified independently by compiling a types/test project against the shipped .d.ts files. Naming is consistent camelCase throughout src/, and error handling favors defensive early returns appropriate for a rendering-only library with little I/O. A GitHub Actions workflow and ESLint config are both present. The codebase is compact (137 total commits) with low recent commit activity and open issues in the double digits, suggesting a stable but lightly maintained project rather than an actively evolving one.

What Makes It Unique

Most chart-labeling approaches fall back to static image annotation, a manually-positioned DOM overlay, or a second SVG layer synced by hand. This plugin instead reads label geometry directly from Chart.js’s own internal element models (arc angle/radius, bar/point bounding boxes) and hooks into Chart.js’s plugin lifecycle so labels automatically re-lay-out on every re-render and animation frame, with no manual DOM synchronization required. Its collision-avoidance layout pass, which re-flows overlapping label boxes across the whole chart rather than always drawing at a fixed anchor, is a meaningfully non-trivial layout algorithm relative to simpler labeling plugins — though architecturally it remains a conventional “plugin extends host library” design rather than a novel rendering technique.