A highly customizable Chart.js plugin that displays labels on data elements for any type of charts. This plugin provides extensive configuration options for label positioning, formatting, styling, and event handling, supporting features like custom formatters, multiple positioning strategies, responsive design considerations, and interactive events.
npm install chartjs-plugin-datalabelsimport ChartDataLabels from 'chartjs-plugin-datalabels';For CommonJS:
const ChartDataLabels = require('chartjs-plugin-datalabels');import Chart from 'chart.js/auto';
import ChartDataLabels from 'chartjs-plugin-datalabels';
// Register the plugin globally
Chart.register(ChartDataLabels);
// Or use it per chart
const chart = new Chart(ctx, {
type: 'bar',
data: {
labels: ['Red', 'Blue', 'Yellow'],
datasets: [{
label: 'My Dataset',
data: [12, 19, 3],
backgroundColor: ['red', 'blue', 'yellow']
}]
},
options: {
plugins: {
datalabels: {
color: 'white',
formatter: (value, context) => {
return value + '%';
}
}
}
},
plugins: [ChartDataLabels] // If not registered globally
});Chart.js Plugin Datalabels is built around several key components:
Core plugin integration with Chart.js, including registration methods and configuration hierarchies. Essential for getting started with the plugin.
// Plugin object with Chart.js integration
const plugin: Plugin;
// Global registration
Chart.register(plugin);
// Per-chart usage
plugins: [plugin]Comprehensive styling and appearance options for labels including colors, fonts, borders, shadows, and backgrounds. Covers all visual aspects of label presentation.
interface LabelOptions {
// Core styling options
/** @default undefined (inherits from Chart.defaults.color) */
color?: Indexable<Color> | Scriptable<Color>;
/** @default null (no background) */
backgroundColor?: Indexable<Color | null> | Scriptable<Color | null>;
/** @default null (no border) */
borderColor?: Indexable<Color | null> | Scriptable<Color | null>;
/** @default 0 (no border) */
borderWidth?: Indexable<number> | Scriptable<number>;
/** @default 0 (not rounded) */
borderRadius?: Indexable<number> | Scriptable<number>;
/** @default { family: undefined, lineHeight: 1.2, size: undefined, style: undefined, weight: null } */
font?: Indexable<Font> | Scriptable<Font>;
/** @default 1 (fully opaque) */
opacity?: Indexable<number> | Scriptable<number>;
/** @default { top: 4, right: 4, bottom: 4, left: 4 } */
padding?: Indexable<Padding> | Scriptable<Padding>;
}Advanced positioning system for precise label placement including anchor points, alignment options, offset distances, rotation, and clipping behaviors.
interface PositioningOptions {
/** @default 'center' */
anchor?: Indexable<Anchor> | Scriptable<Anchor>;
/** @default 'center' */
align?: Indexable<Align> | Scriptable<Align>;
/** @default 4 */
offset?: Indexable<number> | Scriptable<number>;
/** @default 0 */
rotation?: Indexable<number> | Scriptable<number>;
/** @default false */
clamp?: Indexable<boolean> | Scriptable<boolean>;
/** @default false */
clip?: Indexable<boolean> | Scriptable<boolean>;
}Label content control including custom formatters, display conditions, text alignment, and multi-line text handling. Essential for controlling what and how content is shown.
interface ContentOptions {
/** @default true */
display?: Indexable<boolean | string> | Scriptable<boolean | string>;
/** @default built-in formatter (converts data to string) */
formatter?: (value: any, context: Context) => any | null;
/** @default 'start' */
textAlign?: Indexable<TextAlign> | Scriptable<TextAlign>;
}Interactive label functionality with event listeners for click, hover, enter, and leave events. Enables dynamic label behavior and user interactions.
interface EventOptions {
listeners?: {
click?: Listener;
enter?: Listener;
leave?: Listener;
};
}
type Listener = (context: Context, event: ChartEvent) => boolean | void;Advanced multi-label system allowing multiple labels per data point with individual styling and positioning. Perfect for complex data visualization requirements.
interface Options extends LabelOptions {
labels?: Record<string, LabelOptions | null>;
}interface Context {
active: boolean;
chart: Chart;
dataIndex: number;
dataset: ChartDataset;
datasetIndex: number;
}
interface Font {
family?: string;
lineHeight?: string | number;
size?: number;
style?: 'normal' | 'italic' | 'oblique';
weight?: 'normal' | 'bold' | 'bolder' | 'lighter' | number;
}
interface Padding {
top?: number;
right?: number;
bottom?: number;
left?: number;
}
type Indexable<T> = T | T[];
type Scriptable<T> = T | ((context: Context) => T);interface Plugin {
id: string;
defaults?: any;
beforeInit?: (chart: Chart) => void;
beforeUpdate?: (chart: Chart) => void;
afterDatasetUpdate?: (chart: Chart, args: any, options: any) => void;
afterUpdate?: (chart: Chart) => void;
afterDatasetsDraw?: (chart: Chart) => void;
beforeEvent?: (chart: Chart, args: any) => void;
afterEvent?: (chart: Chart) => void;
}
interface Chart {
id: string;
width: number;
height: number;
ctx: CanvasRenderingContext2D;
data: ChartData;
config: ChartConfiguration;
isDatasetVisible(datasetIndex: number): boolean;
getDataVisibility(index: number): boolean;
getActiveElements(): any[];
render(): void;
update(): void;
}
interface ChartDataset {
label?: string;
data: any[];
backgroundColor?: Color | Color[];
borderColor?: Color | Color[];
datalabels?: Options | boolean;
[key: string]: any;
}
interface ChartData {
labels?: string[];
datasets: ChartDataset[];
}
interface ChartEvent {
type: string;
x?: number;
y?: number;
native?: Event;
}
type ChartType = 'bar' | 'line' | 'scatter' | 'bubble' | 'pie' | 'doughnut' | 'polarArea' | 'radar' | string;
interface ChartConfiguration {
type: ChartType;
data: ChartData;
options?: any;
plugins?: Plugin[];
}type Align = 'bottom' | 'center' | 'end' | 'left' | 'right' | 'start' | 'top' | number;
type Anchor = 'center' | 'end' | 'start';
type Color = string | CanvasGradient | CanvasPattern;
type TextAlign = 'left' | 'right' | 'start' | 'center' | 'end';
type Listener = (context: Context, event: ChartEvent) => boolean | void;