chartjs-configuration

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

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

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

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:

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

Interaction Modes

Event Handling

Namespace: options

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