or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

content-formatting.md event-handling.md index.md label-positioning.md label-styling.md multi-label.md plugin-integration.md

tile.json

tessl/npm-chartjs-plugin-datalabels

Chart.js plugin to display labels on data elements

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/chartjs-plugin-datalabels@2.2.x

To install, run

npx @tessl/cli install tessl/npm-chartjs-plugin-datalabels@2.2.0

Chart.js Plugin Datalabels

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.

Package Information

Package Name: chartjs-plugin-datalabels
Package Type: npm
Language: JavaScript/TypeScript
Installation: npm install chartjs-plugin-datalabels
Chart.js Version: Requires Chart.js 3.x or higher

Core Imports

import ChartDataLabels from 'chartjs-plugin-datalabels';

For CommonJS:

const ChartDataLabels = require('chartjs-plugin-datalabels');

Basic Usage

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
});

Architecture

Chart.js Plugin Datalabels is built around several key components:

Plugin System: Integrates with Chart.js lifecycle hooks for seamless operation
Configuration Engine: Hierarchical options system supporting global, chart, and dataset-level configuration
Layout Engine: Automatic label positioning with collision detection and clipping support
Event System: Interactive label handling with click, hover, enter, and leave events
Scriptable Options: Dynamic configuration using functions that receive contextual information
Multi-label Support: Ability to display multiple labels per data point with individual styling

Capabilities

Plugin Registration and Configuration

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]

Plugin Integration

Label Options and Styling

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>;
}

Label Styling

Label Positioning and Alignment

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 Positioning

Content Formatting and Display

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>;
}

Content Formatting

Event Handling and Interactions

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;

Event Handling

Multi-label Configuration

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>;
}

Multi-label System

Types

Core Types

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);

Chart.js Integration Types

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 Aliases

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;