Chart.js Configuration (v4.5.1)

Comprehensive guide to configuring Chart.js options, animations, legends, tooltips, and interactions.

Configuration Structure

const config = {
  type: 'line',
  data: { /* datasets, labels */ },
  options: {
    responsive: true,
    maintainAspectRatio: true,
    aspectRatio: 2,
    events: ['mousemove', 'mouseout', 'click', 'touchstart', 'touchmove'],
    onClick: (event, elements, chart) => { /* handle click */ },
    onHover: (event, elements, chart) => { /* handle hover */ },
    plugins: {
      legend: { /* legend options */ },
      tooltip: { /* tooltip options */ },
      title: { /* title options */ }
    },
    scales: { /* axis options */ },
    animation: { /* animation options */ },
    interaction: { /* interaction options */ },
    layout: { /* layout options */ }
  },
  plugins: []  // Inline plugins
};

Responsive Configuration

Namespace: options

| Option | Type | Default | Description | |--------|------|---------|-------------| | responsive | boolean | true | Resize with container | | maintainAspectRatio | boolean | true | Keep aspect ratio | | aspectRatio | number | 2 (radial: 1) | Width/height ratio | | resizeDelay | number | 0 | Debounce resize (ms) | | onResize | function | null | Callback on resize |

Container Requirements

Chart.js requires the container to be relatively positioned and dedicated to the chart canvas only:

<div class="chart-container" style="position: relative; height: 40vh; width: 80vw">
  <canvas id="chart"></canvas>
</div>

Flexbox/Grid Layout

To prevent overflow in flexbox/grid layouts, set min-width: 0 on the container:

<div class="grid-container" style="display: grid">
  <div class="chart-container" style="min-width: 0">
    <canvas id="chart"></canvas>
  </div>
</div>

For fixed-size charts, set responsive: false and define canvas dimensions directly.

See examples/responsive-chart.html for complete responsive setup including print handling.

Legend Configuration

Namespace: options.plugins.legend

| Option | Type | Default | Description | |--------|------|---------|-------------| | display | boolean | true | Show legend | | position | string | 'top' | top, bottom, left, right, chartArea | | align | string | 'center' | start, center, end | | reverse | boolean | false | Reverse order | | maxHeight | number | - | Maximum height (px) | | maxWidth | number | - | Maximum width (px) | | fullSize | boolean | true | Take full canvas width/height | | rtl | boolean | - | Right-to-left rendering | | onClick | function | - | Click handler | | onHover | function | - | Hover handler | | onLeave | function | - | Mouse leave handler |

Legend Labels

labels: {
  boxWidth: 40,
  boxHeight: 12,
  color: '#666',
  font: { size: 12 },
  padding: 10,
  usePointStyle: false,
  pointStyle: 'circle',
  filter: (item, data) => item.text !== 'Hidden',  // Filter items
  sort: (a, b, data) => a.text.localeCompare(b.text)  // Sort items
}

Hide Legend

plugins: { legend: { display: false } }

For custom click handlers and Legend Item Interface, see references/legend-customization.md.

Tooltip Configuration

Namespace: options.plugins.tooltip

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | true | Enable on-canvas tooltips | | external | function | null | External (HTML) tooltip handler | | mode | string | interaction.mode | point, index, dataset, nearest | | intersect | boolean | interaction.intersect | Require intersection | | position | string | 'average' | average, nearest, or custom | | backgroundColor | Color | 'rgba(0,0,0,0.8)' | Background color | | padding | number | 6 | Padding inside tooltip | | cornerRadius | number | 6 | Border radius | | displayColors | boolean | true | Show color boxes |

Tooltip Callbacks

callbacks: {
  title: (items) => items[0].label,
  label: (context) => `${context.dataset.label}: ${context.parsed.y}`,
  footer: (items) => `Total: ${items.reduce((a, b) => a + b.parsed.y, 0)}`
}

Additional callbacks: beforeTitle, afterTitle, beforeBody, afterBody, beforeLabel, afterLabel, labelColor, labelTextColor, labelPointStyle, beforeFooter, afterFooter.

Disable Tooltips

plugins: { tooltip: { enabled: false } }

For external HTML tooltips, custom positioners, and the full Tooltip Model, see references/tooltip-customization.md and examples/custom-tooltip.html.

Title Configuration

Namespace: options.plugins.title

plugins: {
  title: {
    display: true,
    text: 'Chart Title',
    color: '#666',
    font: { size: 16, weight: 'bold' },
    padding: { top: 10, bottom: 10 },
    align: 'center',      // start, center, end
    position: 'top',      // top, bottom, left, right
    fullSize: true        // Take full canvas width
  },
  subtitle: {
    display: true,
    text: 'Chart Subtitle',
    color: '#999',
    font: { size: 12 }
  }
}

Animation Configuration

Chart.js animation has three configuration levels:

| Key | Namespace | Purpose | |-----|-----------|---------| | animation | options.animation | Base animation settings | | animations | options.animations | Per-property animations | | transitions | options.transitions | Mode-specific animations |

Base Animation

animation: {
  duration: 1000,
  easing: 'easeOutQuart',
  delay: 0,
  loop: false,
  onProgress: (animation) => { /* during animation */ },
  onComplete: (animation) => { /* when complete */ }
}

Per-Property Animations

animations: {
  tension: {
    duration: 1000,
    easing: 'linear',
    from: 1,
    to: 0,
    loop: true
  },
  colors: {
    type: 'color',
    duration: 500,
    from: 'transparent'
  }
}

Transitions

Control animations for specific modes (active, hide, show, reset, resize):

transitions: {
  active: { animation: { duration: 400 } },
  resize: { animation: { duration: 0 } },
  show: {
    animations: {
      colors: { from: 'transparent' },
      visible: { type: 'boolean', duration: 0 }
    }
  }
}

Disable Animations

animation: false  // Disable all
// Or per-mode:
transitions: { active: { animation: { duration: 0 } } }

Easing Functions

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

For animation callbacks and advanced patterns, see references/advanced-animations.md.

Interaction Configuration

Namespace: options.interaction

| Option | Type | Default | Description | |--------|------|---------|-------------| | mode | string | 'nearest' | How to find elements | | intersect | boolean | true | Must intersect element | | axis | string | 'x' | x, y, xy, or r | | includeInvisible | boolean | false | Include hidden elements |

Interaction Modes

| Mode | Description | |------|-------------| | 'point' | Elements at same position | | 'index' | Elements at same index | | 'dataset' | Elements in same dataset | | 'nearest' | Nearest element | | 'x' | Elements at same x-axis value | | 'y' | Elements at same y-axis value |

Event Handling

Namespace: options

| Option | Type | Default | Description | |--------|------|---------|-------------| | events | string[] | ['mousemove', 'mouseout', 'click', 'touchstart', 'touchmove'] | Browser events to listen for | | onClick | function | null | Click handler over chart area | | onHover | function | null | Hover handler over chart area |

options: {
  events: ['click'],  // Only respond to clicks
  onClick: (event, elements, chart) => {
    if (elements.length > 0) {
      const { datasetIndex, index } = elements[0];
      console.log(chart.data.datasets[datasetIndex].data[index]);
    }
  },
  onHover: (event, elements, chart) => {
    chart.canvas.style.cursor = elements.length ? 'pointer' : 'default';
  }
}

Convert Event to Data Values

onClick: (e) => {
  const position = Chart.helpers.getRelativePosition(e, chart);
  const dataX = chart.scales.x.getValueForPixel(position.x);
  const dataY = chart.scales.y.getValueForPixel(position.y);
}

Layout Configuration

Namespace: options.layout

layout: {
  padding: { top: 20, right: 20, bottom: 20, left: 20 },
  autoPadding: true  // Auto-adjust for labels
}

Font Configuration

Global defaults:

Chart.defaults.font.family = "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif";
Chart.defaults.font.size = 12;
Chart.defaults.font.weight = 'normal';
Chart.defaults.font.lineHeight = 1.2;
Chart.defaults.color = '#666';

Per-element font:

font: { family: 'Arial', size: 18, weight: 'bold', style: 'italic', lineHeight: 1.2 }

Color Configuration

Supported formats: named ('red'), hex ('#ff0000'), RGB ('rgb(255,0,0)'), RGBA ('rgba(255,0,0,0.5)'), HSL ('hsl(0,100%,50%)'), HSLA.

Global color defaults:

Chart.defaults.backgroundColor = 'rgba(0, 0, 0, 0.1)';
Chart.defaults.borderColor = 'rgba(0, 0, 0, 0.1)';
Chart.defaults.color = '#666';

Element Configuration

Default styles for chart elements:

// Points (line, radar, scatter)
Chart.defaults.elements.point.radius = 3;
Chart.defaults.elements.point.hoverRadius = 4;

// Lines
Chart.defaults.elements.line.tension = 0;
Chart.defaults.elements.line.borderWidth = 3;

// Bars
Chart.defaults.elements.bar.borderWidth = 0;
Chart.defaults.elements.bar.borderRadius = 0;

// Arcs (pie, doughnut, polar)
Chart.defaults.elements.arc.borderWidth = 2;

Global Defaults

Chart.defaults.responsive = true;
Chart.defaults.maintainAspectRatio = true;
Chart.defaults.interaction.mode = 'nearest';
Chart.defaults.plugins.legend.position = 'bottom';
Chart.defaults.datasets.line.tension = 0.4;

Additional Configuration

Other configuration topics not covered in detail here:

• Decimation: Reduce data points for large datasets (options.plugins.decimation)
• Locale: Number/date formatting (options.locale)
• Device Pixel Ratio: Canvas resolution (options.devicePixelRatio)
• Canvas Background: Background color plugin for exports

References

• references/advanced-animations.md - Transitions, callbacks, animation object
• references/tooltip-customization.md - External tooltips, Tooltip Model, custom positioners
• references/legend-customization.md - Legend Item Interface, custom handlers

Examples

• examples/responsive-chart.html - Proper container setup, flexbox, print handling
• examples/custom-tooltip.html - External HTML tooltip implementation
• examples/interactive-legend.html - Custom legend click behavior