Skip to content

Chart.js Hoja de referencia

Librería de gráficos de JavaScript simple pero flexible.

01

Primeros pasos

Configuración y primer gráfico

Chart.js renderiza sobre un elemento canvas. La propiedad type fija el tipo de gráfico. data contiene las etiquetas y los datasets con los valores y el estilo.

chartjs
<!-- include Chart.js -->
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>

<canvas id="myChart" width="400" height="400"></canvas>

<script>
const ctx = document.getElementById('myChart').getContext('2d');
new Chart(ctx, {
  type: 'bar',
  data: {
    labels: ['Red', 'Blue', 'Green'],
    datasets: [{
      label: 'Votes',
      data: [12, 19, 3],
      backgroundColor: ['red', 'blue', 'green']
    }]
  }
});
</script>

Instalación con npm e importación de módulos ES

Usa 'chart.js/auto' para la configuración más simple — importa Chart.js con cada controlador/elemento y los registra automáticamente. Para bundles de producción más pequeños prefiere el tree-shaking: importa desde 'chart.js' y registra solo las piezas que uses.

chartjs
# install
npm install chart.js

// import the auto-bundled build (registers everything)
import Chart from 'chart.js/auto';

const ctx = document.getElementById('myChart');
const chart = new Chart(ctx, {
  type: 'line',
  data: { /* ... */ },
  options: { responsive: true }
});

Canvas y contexto 2D

Chart.js puede recibir tanto el elemento <canvas> como su contexto de renderizado 2d. Cuando responsive es true, el canvas se redimensiona para llenar su contenedor, así que los atributos HTML width/height son solo respaldo. Cada canvas puede contener exactamente una instancia de Chart.

chartjs
// Chart.js accepts a canvas element OR a 2D context
const canvas = document.getElementById('myChart');
const chart = new Chart(canvas, { type: 'bar', data: {...} });

// equivalent: pass the 2d context
const ctx = canvas.getContext('2d');
const chart2 = new Chart(ctx, { type: 'bar', data: {...} });

// one chart per canvas; the canvas size is controlled by
// responsive options, NOT the width/height attributes

Tipos de gráficos disponibles

Chart.js incluye ocho tipos de gráficos. Bar, line, scatter y bubble usan ejes cartesianos; pie, doughnut y polarArea son circulares; radar tiene su propio eje radial. El campo 'type' del nivel superior selecciona el controlador usado por el conjunto de datasets, salvo que un dataset lo sobrescriba con su propio type.

chartjs
// the 8 built-in chart types
const types = ['bar', 'line', 'pie', 'doughnut',
               'radar', 'polarArea', 'bubble', 'scatter'];

// each type maps to a controller:
//   bar/line    -> Cartesian controllers
//   pie/doughnut/polarArea -> circular controllers
//   radar       -> radar controller
//   bubble/scatter -> cartesian with point parsing

new Chart(ctx, { type: 'polarArea', data: {...} });

Tree-shaking y registro

Al importar desde 'chart.js' (no /auto) nada queda registrado, así que debes registrar tú los controladores, elementos, escalas y plugins. Este enfoque tree-shakeable puede reducir considerablemente el tamaño del bundle. Olvidar registrar un componente es la causa más común del error 'scale is not a registered scale'.

chartjs
import {
  Chart,
  BarController,
  BarElement,
  CategoryScale,
  LinearScale,
  Legend,
  Title,
  Tooltip,
} from 'chart.js';

// register ONLY what you use -> smaller bundle
Chart.register(
  BarController, BarElement,
  CategoryScale, LinearScale,
  Legend, Title, Tooltip,
);

new Chart(ctx, {
  type: 'bar',
  data: { labels: ['A', 'B'], datasets: [{ data: [1, 2] }] },
});

Destruir y ciclo de vida

Cada instancia de Chart posee su canvas y sus listeners de eventos adjuntos. Llamar a destroy() lo desmonta por completo para que el canvas pueda reutilizarse — imprescindible en SPAs y en efectos de React/Vue. Crear un segundo gráfico sobre un canvas activo provoca fugas de memoria y gráficos renderizados por duplicado.

chartjs
const chart = new Chart(ctx, config);

// ...later, to re-render with new config:
chart.destroy();        // cleans up listeners and canvas
const fresh = new Chart(ctx, newConfig);

// never create two Chart instances on the same canvas;
// always destroy() the old one first.
02

Gráficos de barras

Gráfico de barras básico

Un gráfico de barras mapea cada etiqueta a una barra cuya altura equivale al valor de los datos. backgroundColor fija el relleno de la barra, borderColor/borderWidth el contorno. Establece y.beginAtZero para que las barras empiecen siempre en cero — sin él, Chart.js puede autoescalar el mínimo del eje y distorsionar visualmente las diferencias.

chartjs
new Chart(ctx, {
  type: 'bar',
  data: {
    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
    datasets: [{
      label: 'Revenue',
      data: [12, 19, 7, 15, 22],
      backgroundColor: 'rgba(54, 162, 235, 0.6)',
      borderColor: 'rgba(54, 162, 235, 1)',
      borderWidth: 1
    }]
  },
  options: { scales: { y: { beginAtZero: true } } }
});

Barras horizontales (indexAxis)

En Chart.js v3+ las barras horizontales se crean con indexAxis: 'y' sobre un tipo 'bar' — el antiguo tipo 'horizontalBar' se eliminó. La escala x se convierte en el eje de valores. Las barras horizontales son ideales para etiquetas de categoría largas que se solaparían en un gráfico vertical.

chartjs
new Chart(ctx, {
  type: 'bar',
  data: {
    labels: ['Task A', 'Task B', 'Task C'],
    datasets: [{ label: 'Hours', data: [5, 8, 3] }]
  },
  options: {
    indexAxis: 'y',   // horizontal bars (v3+ syntax)
    scales: { x: { beginAtZero: true } }
  }
});

Barras agrupadas (múltiples datasets)

Varios datasets en un gráfico de barras se colocan lado a lado (agrupados) por defecto. Chart.js solo autoasigna colores si omites backgroundColor, así que fija colores explícitos por dataset para un resultado predecible. Cada dataset comparte el mismo array de labels en el eje x.

chartjs
new Chart(ctx, {
  type: 'bar',
  data: {
    labels: ['Q1', 'Q2', 'Q3', 'Q4'],
    datasets: [
      { label: '2023', data: [20, 35, 30, 35],
        backgroundColor: 'rgba(255,99,132,0.6)' },
      { label: '2024', data: [25, 32, 34, 40],
        backgroundColor: 'rgba(54,162,235,0.6)' }
    ]
  },
  options: { scales: { y: { beginAtZero: true } } }
});

Barras apiladas

Las barras apiladas requieren stacked: true en AMBAS escalas, x e y. Las barras de cada dataset se dibujan encima de la anterior, sumando un total. El apilado muestra composición, pero hace que las series superiores sean más difíciles de comparar entre categorías que las barras agrupadas.

chartjs
new Chart(ctx, {
  type: 'bar',
  data: {
    labels: ['A', 'B', 'C'],
    datasets: [
      { label: 'Men',   data: [20, 35, 30], backgroundColor: '#36A2EB' },
      { label: 'Women', data: [25, 32, 34], backgroundColor: '#FF6384' }
    ]
  },
  options: {
    scales: {
      x: { stacked: true },
      y: { stacked: true, beginAtZero: true }
    }
  }
});

Estilo de las barras

borderRadius redondea las esquinas de las barras (un solo número se aplica a todas las esquinas; un objeto como {topLeft:8} apunta a esquinas concretas). borderSkipped vale 'start' por defecto, lo que omite un borde — fija false para dibujar los cuatro. barPercentage y categoryPercentage juntos controlan el grosor y el espaciado de las barras.

chartjs
new Chart(ctx, {
  type: 'bar',
  data: {
    labels: ['A', 'B', 'C'],
    datasets: [{
      data: [10, 20, 15],
      backgroundColor: '#FF6384',
      borderColor: '#fff',
      borderWidth: 2,
      borderRadius: 8,           // rounded corners (px or %)
      borderSkipped: false,      // draw border on all sides
      barPercentage: 0.8,        // bar width within category
      categoryPercentage: 0.7    // category width
    }]
  }
});

Barras flotantes ([min, max])

Pasar pares [min, max] como valores de datos produce barras flotantes que no empiezan en cero — perfecto para rangos como temperatura diaria mínima-máxima, apertura-cierre o intervalos de confianza. El eje y NO debería empezar en cero para barras de rango. Esto también funciona en barras horizontales.

chartjs
new Chart(ctx, {
  type: 'bar',
  data: {
    labels: ['Mon', 'Tue', 'Wed'],
    datasets: [{
      label: 'Low-High temp',
      // each value is [min, max] -> a floating bar
      data: [[10, 18], [12, 20], [8, 15]],
      backgroundColor: 'rgba(75,192,192,0.6)'
    }]
  },
  options: { scales: { y: { beginAtZero: false } } }
});
03

Gráficos de líneas

Gráfico de líneas básico

Un gráfico de líneas conecta los puntos de datos en orden. borderColor es el color de la línea; backgroundColor se usa para el relleno (si fill está activado). tension (0-1) controla la suavidad de la curva — 0 son segmentos rectos, ~0.3-0.4 da curvas bezier suaves. Usa 0 para datos precisos como precios financieros.

chartjs
new Chart(ctx, {
  type: 'line',
  data: {
    labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
    datasets: [{
      label: 'Visitors',
      data: [30, 45, 28, 60, 52],
      borderColor: 'rgba(75,192,192,1)',
      backgroundColor: 'rgba(75,192,192,0.2)',
      tension: 0.3
    }]
  },
  options: { scales: { y: { beginAtZero: true } } }
});

Múltiples líneas

Cada dataset en un gráfico de líneas se convierte en su propia línea, con color autoasignado de la paleta por defecto (sobrescribible con borderColor). Las líneas se dibujan en el orden de los datasets, así que el último dataset se renderiza encima. Dale un label a cada dataset para que la leyenda pueda identificarlos.

chartjs
new Chart(ctx, {
  type: 'line',
  data: {
    labels: ['Jan', 'Feb', 'Mar', 'Apr'],
    datasets: [
      { label: 'Plan',  data: [10, 20, 25, 30], borderColor: 'red' },
      { label: 'Actual', data: [8, 22, 24, 33], borderColor: 'blue' }
    ]
  },
  options: {
    scales: { y: { beginAtZero: true } },
    plugins: { legend: { position: 'top' } }
  }
});

Tensión e interpolación de la línea

tension añade suavizado bezier pero puede sobrepasar los puntos de datos (creando hundimientos por debajo del mínimo). cubicInterpolationMode: 'monotone' suaviza sin sobrepasar — preferible para datos monótonos como precios de acciones. borderDash es un patrón [dash, gap] para líneas discontinuas/punteadas.

chartjs
datasets: [{
  data: [1, 5, 2, 6, 3],
  tension: 0,                  // straight lines
  // tension: 0.4,             // smooth bezier
  cubicInterpolationMode: 'monotone',  // no overshoot
  borderDash: [5, 5],          // dashed line
  borderWidth: 2,
  borderColor: 'purple'
}]

Líneas con relleno (fill)

fill controla el área bajo la línea. true/'origin' rellena hasta el eje x. Un número (1, -1, +1) rellena hacia otro dataset por índice, útil para gráficos de bandas. Un número negativo rellena hacia el dataset anterior. Fija un backgroundColor con alfa para que la línea siga viéndose a través del relleno.

chartjs
datasets: [
  { label: 'A', data: [3,5,4,6], fill: true,  backgroundColor: 'rgba(255,99,132,0.3)' },
  { label: 'B', data: [1,2,3,2], fill: 'origin', backgroundColor: 'rgba(54,162,235,0.3)' },
  { label: 'C', data: [2,4,3,5], fill: 1,       backgroundColor: 'rgba(75,192,192,0.3)' }
]
// fill values: false | true/'origin' | 1/-1/+1 | '-1' | {target:...}

Estilo de los puntos

Las propiedades de punto aceptan un único valor o un array (uno por punto de datos). pointStyle soporta muchas formas ('circle', 'rect', 'rectRot', 'triangle', 'star', 'cross', 'crossRot'). Fija pointRadius: 0 para ocultar los puntos por completo (útil en gráficos de líneas densos) y pointHoverRadius más grande para un efecto pop interactivo.

chartjs
datasets: [{
  data: [4, 6, 5, 7],
  showLine: true,
  pointRadius: 5,           // point size (0 hides points)
  pointHoverRadius: 9,
  pointBackgroundColor: 'white',
  pointBorderColor: 'black',
  pointBorderWidth: 2,
  pointStyle: 'rectRot',    // 'circle','rect','triangle','star','cross'...
  // per-point arrays also work:
  // pointRadius: [0, 0, 6, 0],
}]

Span gaps y datos faltantes

null, undefined y NaN representan datos faltantes y rompen la línea por defecto. spanGaps: true conecta los puntos a ambos lados del hueco con un solo segmento. Distingue NaN (falta) de 0 (un cero real) — confundirlos es una fuente habitual de gráficos engañosos.

chartjs
datasets: [{
  data: [5, null, 7, NaN, 9, undefined, 11],
  spanGaps: true,    // connect across null/NaN gaps
  // spanGaps: false -> the line breaks at missing points
}]

// also skip points entirely by setting them to NaN
// NaN is "no data"; 0 is a legitimate zero value
04

Gráficos de pie y doughnut

Gráfico de pie básico

Un gráfico de pie muestra partes de un conjunto: cada valor se convierte en un sector cuyo ángulo es proporcional a su cuota. Proporciona un backgroundColor por porción (un array); si no, Chart.js cicla una paleta por defecto. Los gráficos de pie funcionan mejor con 3-6 categorías — más se vuelve ilegible.

chartjs
new Chart(ctx, {
  type: 'pie',
  data: {
    labels: ['Rent', 'Food', 'Fun', 'Save'],
    datasets: [{
      data: [1200, 600, 400, 800],
      backgroundColor: ['#FF6384', '#36A2EB', '#FFCE56', '#4BC0C0']
    }]
  }
});

Gráfico de doughnut básico

Un doughnut es un pie con un agujero en el centro. La propiedad cutout (cadena de porcentaje o número de píxeles) controla el tamaño del agujero — '50%' es el aspecto clásico de donut. El agujero central puede alojar una etiqueta resumen mediante un plugin, y la longitud del anillo codifica el valor ligeramente mejor que el ángulo del sector.

chartjs
new Chart(ctx, {
  type: 'doughnut',
  data: {
    labels: ['A', 'B', 'C'],
    datasets: [{
      data: [40, 35, 25],
      backgroundColor: ['#FF6384', '#36A2EB', '#FFCE56'],
      cutout: '50%'      // size of the inner hole
    }]
  }
});

Cutout, rotación y circunferencia

rotation fija el ángulo de inicio en grados (0 por defecto = derecha; -90 = arriba). circumference controla cuánto círculo se dibuja — 180 hace un medio doughnut, útil para gráficos tipo indicador. Ambos viven bajo options (no en el dataset) en v3+, aunque cutout puede aparecer en cualquiera de los dos.

chartjs
new Chart(ctx, {
  type: 'doughnut',
  data: { labels: ['A','B','C'], datasets: [{ data: [30,40,30], backgroundColor: ['#f00','#0f0','#00f'] }] },
  options: {
    cutout: '60%',
    rotation: -90,        // start at top (degrees)
    circumference: 360    // full circle; 180 = half doughnut
  }
});

Borde y offset

borderColor con borderWidth separa visualmente los sectores (los bordes blancos dan un aspecto segmentado limpio). hoverOffset empuja un sector hacia afuera cuando el usuario pasa el ratón, dando una clara retroalimentación interactiva. offset es un array (uno por sector) para 'explotar' permanentemente sectores concretos y darles énfasis.

chartjs
datasets: [{
  data: [30, 40, 30],
  backgroundColor: ['#FF6384', '#36A2EB', '#FFCE56'],
  borderColor: 'white',
  borderWidth: 3,
  hoverOffset: 16,        // pop slice out on hover
  offset: [0, 20, 0]      // permanently offset 2nd slice
}]

Medio doughnut (indicador)

Un medio doughnut (rotation: -90, circumference: 180) se lee como un indicador/medidor de progreso. Emparéjalo con un plugin de texto central para mostrar el porcentaje, y desactiva la leyenda para un aspecto KPI limpio. El sector 'restante' en gris neutro transmite la parte no completada.

chartjs
new Chart(ctx, {
  type: 'doughnut',
  data: {
    labels: ['Done', 'Remaining'],
    datasets: [{
      data: [72, 28],
      backgroundColor: ['#4BC0C0', '#E0E0E0']
    }]
  },
  options: {
    rotation: -90,
    circumference: 180,
    plugins: { legend: { display: false } }
  }
});

Callback de porcentaje del tooltip

Los tooltips de pie/doughnut muestran los valores crudos por defecto. Usa el callbacks.label del tooltip para calcular y mostrar porcentajes en su lugar — ctx.parsed es el valor del sector y ctx.dataset.data contiene los valores que entran en la suma. Los template literals en los callbacks deben escapar backticks y ${} al incrustarse en la cadena de código de este cheatsheet.

chartjs
options: {
  plugins: {
    tooltip: {
      callbacks: {
        label: (ctx) => {
          const total = ctx.dataset.data.reduce((a, b) => a + b, 0);
          const pct = (ctx.parsed / total * 100).toFixed(1);
          return `${ctx.label}: ${ctx.parsed} (${pct}%)`;
        }
      }
    }
  }
}
05

Gráficos de radar

Gráfico de radar básico

Un gráfico de radar sitúa cada etiqueta como un vértice en un polígono, conectándolos en una forma cerrada. fill: true sombrea el interior. La escala radial se configura bajo scales.r (no x/y). Los radares comparan perfiles multivariables pero pueden engañar con demasiados ejes o unidades no comparables.

chartjs
new Chart(ctx, {
  type: 'radar',
  data: {
    labels: ['Speed', 'Power', 'Range', 'Comfort', 'Price'],
    datasets: [{
      label: 'Model X',
      data: [8, 7, 6, 9, 5],
      borderColor: 'rgba(255,99,132,1)',
      backgroundColor: 'rgba(255,99,132,0.2)',
      fill: true
    }]
  },
  options: { scales: { r: { beginAtZero: true } } }
});

Estilo del radar

Los datasets de radar aceptan el mismo estilo que los gráficos de líneas: borderColor, fill, estilo de puntos, tension. Una tension pequeña (0.1) redondea ligeramente los vértices para un aspecto más suave; 0 mantiene las puntas rectas. Usa un backgroundColor translúcido para que las formas de radar superpuestas sigan siendo visibles.

chartjs
datasets: [{
  data: [7, 8, 6, 9, 5],
  borderColor: 'blue',
  backgroundColor: 'rgba(0,0,255,0.2)',
  borderWidth: 2,
  pointRadius: 4,
  pointBackgroundColor: 'blue',
  fill: true,
  tension: 0.1            // slight curve between vertices
}]

Ajustes de la escala radial (r)

La escala radial r controla los anillos y las etiquetas. min/max fijan el rango de valores en los distintos ejes (esencial al comparar datasets). ticks.stepSize fija el espaciado de los anillos; pointLabels estiliza los nombres de las categorías alrededor del perímetro. Pon ticks.backdropColor transparente para que los números de los anillos no tapen las líneas de la cuadrícula.

chartjs
options: {
  scales: {
    r: {
      min: 0,
      max: 10,
      ticks: { stepSize: 2, backdropColor: 'transparent' },
      pointLabels: { font: { size: 13 }, color: '#333' },
      grid: { color: '#ccc' },
      angleLines: { color: '#ccc' }
    }
  }
}

Radar con múltiples datasets

Varios datasets se superponen como polígonos concéntricos, ideal para comparaciones antes/después o entre competidores. Fija siempre el mismo min/max en r para que las formas sean comparables, y usa rellenos translúcidos para que ambos perfiles sigan viéndose donde se solapan.

chartjs
new Chart(ctx, {
  type: 'radar',
  data: {
    labels: ['A', 'B', 'C', 'D', 'E'],
    datasets: [
      { label: 'Before', data: [5,6,4,7,5], borderColor: 'red',  backgroundColor: 'rgba(255,0,0,0.15)', fill: true },
      { label: 'After',  data: [7,8,6,9,7], borderColor: 'blue', backgroundColor: 'rgba(0,0,255,0.15)', fill: true }
    ]
  }
});

Líneas de ángulo y cuadrícula del radar

angleLines son los radios desde el centro a cada vértice; grid son los anillos poligonales concéntricos. Ocultar los ticks (display:false) elimina las etiquetas numéricas de los anillos para una estética más limpia, manteniendo los anillos en sí. pointLabels controla solo el texto de categoría en cada vértice.

chartjs
options: {
  scales: {
    r: {
      angleLines: { display: true, color: 'rgba(0,0,0,0.2)', lineWidth: 1 },
      grid: { display: true, color: 'rgba(0,0,0,0.1)' },
      pointLabels: { display: true, color: '#000', font: { weight: 'bold' } },
      ticks: { display: false }   // hide numeric ring labels for a cleaner look
    }
  }
}
06

Gráficos de área polar

Gráfico de área polar básico

Un gráfico de área polar dibuja cada valor como un sector que abarca el mismo ángulo (360/N cada uno), con el radio codificando el valor. A diferencia del pie (donde ángulo = valor), aquí radio = valor, así que los sectores tienen el mismo ancho angular pero distinta longitud.

chartjs
new Chart(ctx, {
  type: 'polarArea',
  data: {
    labels: ['North', 'South', 'East', 'West'],
    datasets: [{
      data: [11, 16, 7, 14],
      backgroundColor: ['#FF6384', '#4BC0C0', '#FFCE56', '#36A2EB']
    }]
  },
  options: { scales: { r: { beginAtZero: true } } }
});

Área polar vs pie

La diferencia clave: en un pie, el ÁNGULO de cada sector es proporcional a su valor; en un área polar, el RADIO de cada sector es proporcional a su valor mientras los ángulos son iguales. Usa área polar cuando quieras que todas las categorías sean igual de visibles pero dimensionadas por magnitud.

chartjs
// PIE:    angle = value,  radius = constant
new Chart(ctx, { type: 'pie',     data: { datasets: [{ data: [10, 20, 30] }] } });

// POLAR:  angle = constant, radius = value
new Chart(ctx, { type: 'polarArea', data: { datasets: [{ data: [10, 20, 30] }] } });

// polar area is better when values differ widely AND
// you want every category to occupy an equal angular share

Escala polar (r)

El área polar usa una única escala radial r compartida por los sectores — así cada valor se mide contra el mismo radio máximo. Fijar un max explícito hace que el gráfico sea honesto con la escala; sin él, Chart.js autoescala al valor mayor, lo que puede exagerar las diferencias pequeñas.

chartjs
options: {
  scales: {
    r: {
      min: 0,
      max: 20,
      ticks: { stepSize: 5 },
      grid: { color: 'rgba(0,0,0,0.15)' },
      angleLines: { color: 'rgba(0,0,0,0.15)' }
    }
  }
}

Estilo de borde polar

Los sectores de área polar aceptan el mismo estilo de borde/relleno que pie/doughnut. Los bordes blancos separan con claridad los sectores adyacentes. hoverBackgroundColor cambia el relleno de un sector al pasar el ratón como retroalimentación interactiva. A diferencia del doughnut no hay cutout — los sectores se unen en el centro.

chartjs
datasets: [{
  data: [11, 16, 7, 14],
  backgroundColor: ['#FF6384', '#4BC0C0', '#FFCE56', '#36A2EB'],
  borderColor: 'white',
  borderWidth: 2,
  hoverBackgroundColor: '#333'
}]

Polar con hover offset

El área polar soporta hoverBackgroundColor y hoverBorderColor pero NO soporta hoverOffset / offset de la misma forma que el doughnut, porque los sectores comparten una escala radial. Si 'sacar' un sector es esencial, elige doughnut en su lugar. Usa cambios de color y tooltip para la interactividad del polar.

chartjs
datasets: [{
  data: [11, 16, 7, 14],
  backgroundColor: ['#FF6384', '#4BC0C0', '#FFCE56', '#36A2EB'],
  hoverOffset: 12     // not supported on polarArea the same way as doughnut;
                      // use hoverBackgroundColor + tooltips for interactivity
}]
// for true "pop out" use 'doughnut' instead
07

Gráficos de burbujas

Gráfico de burbujas básico

Los puntos de datos del gráfico de burbujas son objetos {x, y, r} donde x e y son coordenadas y r es el RADIO de la burbuja en píxeles. A diferencia del scatter, el tamaño de la burbuja codifica una tercera variable. Ten en cuenta que r es un radio (no un área), así que un valor 2 veces mayor es visualmente 4 veces el área — considera escalar con raíz cuadrada tus datos de tamaño.

chartjs
new Chart(ctx, {
  type: 'bubble',
  data: {
    datasets: [{
      label: 'Products',
      data: [
        { x: 10, y: 20, r: 15 },
        { x: 15, y: 10, r: 10 },
        { x:  7, y: 25, r:  8 }
      ],
      backgroundColor: 'rgba(255,99,132,0.6)'
    }]
  },
  options: { scales: { y: { beginAtZero: true } } }
});

Mapeo del tamaño de burbuja

Como los humanos percibimos el ÁREA de la burbuja más que el radio, mapea tu valor con Math.sqrt antes de asignar r, de modo que duplicar el valor duplique el área visible. Elige un divisor que evite que la burbuja más grande solape demasiados vecinos. Esto hace que el gráfico sea perceptualmente honesto.

chartjs
const raw = [{x:1,y:2,pop:1000}, {x:2,y:3,pop:5000}, {x:3,y:1,pop:20000}];

// map a real-world value to a pixel radius with sqrt scaling
// so bubble AREA (not radius) is proportional to the value
const data = raw.map(d => ({
  x: d.x,
  y: d.y,
  r: Math.sqrt(d.pop) / 10    // tune the divisor for your dataset
}));

new Chart(ctx, { type: 'bubble', data: { datasets: [{ data }] } });

Colores de burbuja por punto

Como otros datasets de Chart.js, las propiedades de estilo de burbuja aceptan arrays para estilizar cada burbuja individualmente. Úsalo para codificar por color las burbujas por categoría mientras el tamaño codifica un valor numérico aparte, obteniendo un gráfico de 4 dimensiones (x, y, tamaño, color).

chartjs
datasets: [{
  data: [
    { x: 10, y: 20, r: 15 },
    { x: 15, y: 10, r: 10 }
  ],
  // arrays give per-point styling
  backgroundColor: ['rgba(255,99,132,0.6)', 'rgba(54,162,235,0.6)'],
  borderColor:     ['rgba(255,99,132,1)',   'rgba(54,162,235,1)'],
  borderWidth: 2
}]

Múltiples datasets de burbujas

Varios datasets se renderizan como grupos de burbujas de distinto color, cada uno en la leyenda. Mantén los radios de burbuja moderados al superponer grupos para que las burbujas no se tapen por completo entre sí. Los rellenos transparentes con alfa (0.5-0.6) ayudan a que las burbujas solapadas sigan siendo legibles.

chartjs
new Chart(ctx, {
  type: 'bubble',
  data: {
    datasets: [
      { label: 'Asia',   data: [{x:1,y:2,r:10},{x:3,y:4,r:8}],  backgroundColor: 'rgba(255,99,132,0.6)' },
      { label: 'Europe', data: [{x:2,y:5,r:12},{x:4,y:2,r:7}],  backgroundColor: 'rgba(54,162,235,0.6)' }
    ]
  }
});

Estilo hover de las burbujas

Las propiedades hover (hoverBackgroundColor, hoverBorderColor, hoverBorderWidth, hoverRadius) se aplican solo a la burbuja bajo el puntero. hoverRadius añade píxeles extra al radio al pasar el ratón, haciendo que la burbuja objetivo destaque visiblemente. Combinado con tooltips, da un foco interactivo claro.

chartjs
datasets: [{
  data: [{x:1,y:2,r:10}],
  backgroundColor: 'rgba(75,192,192,0.5)',
  hoverBackgroundColor: 'rgba(75,192,192,0.9)',
  hoverBorderColor: 'black',
  hoverBorderWidth: 3,
  hoverRadius: 2      // EXTRA radius added on hover (v3+ uses hoverRadius)
}]
08

Gráficos de dispersión

Gráfico de dispersión básico

Los puntos de datos del gráfico de dispersión son objetos {x, y} (sin radio necesario). La escala x debería ser type: 'linear' (NO category) para que los valores numéricos de x se mapeen a posiciones reales. El scatter es el gráfico estándar para mostrar la correlación entre dos variables continuas.

chartjs
new Chart(ctx, {
  type: 'scatter',
  data: {
    datasets: [{
      label: 'Observations',
      data: [
        { x: 1.2, y: 2.3 },
        { x: 1.8, y: 3.1 },
        { x: 2.5, y: 4.0 },
        { x: 3.1, y: 4.8 }
      ],
      backgroundColor: 'rgba(75,192,192,0.7)'
    }]
  },
  options: { scales: { x: { type: 'linear', position: 'bottom' } } }
});

Dispersión con muchos puntos

Para miles de puntos, reduce pointRadius (1-2px) y usa un backgroundColor semitransparente (alfa 0.2-0.4) para que los puntos solapados revelen la densidad mediante regiones más oscuras. Desactiva el hover de puntos en datasets muy grandes (pointHitRadius: 0) para que la interacción siga siendo ágil.

chartjs
const n = 2000;
const data = Array.from({ length: n }, () => ({
  x: Math.random() * 100,
  y: Math.random() * 100
}));

new Chart(ctx, {
  type: 'scatter',
  data: { datasets: [{ data, pointRadius: 1.5, backgroundColor: 'rgba(0,0,0,0.3)' }] }
});

Estilo de los puntos del scatter

pointStyle soporta muchas formas además del círculo por defecto: 'rect', 'rectRot', 'triangle', 'star', 'cross', 'crossRot', 'dash'. pointRotation rota las formas no circulares. Todas las propiedades point* aceptan arrays para estilizar punto a punto — útil para resaltar observaciones concretas.

chartjs
datasets: [{
  data: [{x:1,y:2},{x:2,y:3}],
  pointRadius: 8,
  pointHoverRadius: 12,
  pointStyle: 'triangle',          // 'circle','rect','star','cross',...
  pointBackgroundColor: 'red',
  pointBorderColor: 'darkred',
  pointBorderWidth: 2,
  pointRotation: 45                // rotation in degrees (for shapes)
}]

Dispersión con línea de tendencia

Chart.js no tiene línea de tendencia integrada, así que calcula una regresión (mínimos cuadrados aquí) y añade un dataset 'line' con dos extremos y pointRadius:0. El type del dataset de línea sobrescribe el tipo del gráfico por dataset — así funcionan también los gráficos mixtos. fill:false lo mantiene como pura línea.

chartjs
// simple least-squares fit
const pts = [{x:1,y:2},{x:2,y:3.5},{x:3,y:4.2},{x:4,y:5.1}];
const n = pts.length;
const mX = pts.reduce((s,p)=>s+p.x,0)/n;
const mY = pts.reduce((s,p)=>s+p.y,0)/n;
const slope = pts.reduce((s,p)=>s+(p.x-mX)*(p.y-mY),0) / pts.reduce((s,p)=>s+(p.x-mX)**2,0);
const intercept = mY - slope*mX;

new Chart(ctx, {
  type: 'scatter',
  data: { datasets: [
    { data: pts, backgroundColor: 'blue' },
    { type: 'line', data: [{x:0,y:intercept},{x:5,y:slope*5+intercept}],
      borderColor: 'red', pointRadius: 0, fill: false }
  ]}
});

Dispersión a línea (showLine)

showLine: true en un dataset de scatter conecta los puntos con una línea, convirtiendo efectivamente el scatter en un gráfico de líneas que usa coordenadas x numéricas. Es la elección correcta cuando los valores de x son números reales (no etiquetas de categoría) pero aún quieres segmentos conectores — por ejemplo, series temporales con espaciado irregular.

chartjs
new Chart(ctx, {
  type: 'scatter',
  data: { datasets: [{
    data: [{x:1,y:2},{x:2,y:3},{x:3,y:5}],
    showLine: true,            // connect points with a line
    borderColor: 'green',
    backgroundColor: 'green',
    pointRadius: 4
  }]}
});
09

Datos — Datasets

Estructura de los datasets

data contiene labels (compartidas entre los datasets) y datasets (un array de series). Cada dataset tiene un label (mostrado en leyenda/tooltips), un array data alineado con labels, y propiedades de estilo. Las propiedades fijadas en el dataset se aplican a cada punto salvo que un array las sobrescriba.

chartjs
data: {
  labels: ['A', 'B', 'C'],          // shared category labels
  datasets: [
    {
      label: 'Series 1',             // legend + tooltip label
      data: [10, 20, 30],            // values (one per label)
      backgroundColor: 'rgba(0,0,255,0.5)',
      borderColor: 'blue',
      borderWidth: 1,
      // ... type-specific styling
    }
  ]
}

Alineación de labels y data

El array data de cada dataset está alineado posicionalmente con el array de labels compartido — data[i] es el valor de labels[i]. Un array data más corto produce valores undefined para la cola faltante, que los gráficos de líneas tratan como huecos. Mantén siempre labels y data con la misma longitud para evitar huecos inesperados.

chartjs
data: {
  labels: ['Jan', 'Feb', 'Mar'],
  datasets: [
    { data: [10, 20, 30] },          // Jan=10, Feb=20, Mar=30
    { data: [5, 15] }                // Jan=5, Feb=15, Mar=undefined
  ]
}
// data[i] always corresponds to labels[i]; a shorter data array
// leaves the remaining positions as undefined (missing data)

Múltiples datasets

Varios datasets se renderizan como series paralelas (barras agrupadas, múltiples líneas, radares superpuestos). Comparten un solo array de labels. Fija colores distintos por dataset — Chart.js solo colorea automáticamente cuando se omite backgroundColor, y aun así los colores explícitos son más predecibles entre versiones.

chartjs
data: {
  labels: ['Q1','Q2','Q3','Q4'],
  datasets: [
    { label: '2023', data: [20,35,30,35], backgroundColor: 'rgba(255,99,132,0.6)' },
    { label: '2024', data: [25,32,34,40], backgroundColor: 'rgba(54,162,235,0.6)' },
    { label: '2025', data: [28,38,36,45], backgroundColor: 'rgba(75,192,192,0.6)' }
  ]
}

Estilo a nivel de dataset

El estilo a nivel de dataset se aplica a cada punto de ese dataset. Las variantes hover* se activan al pasar el ratón. hidden:true inicia el dataset oculto (el toggle de la leyenda puede volver a mostrarlo). order controla el orden z — los números menores se dibujan después (encima) — útil en gráficos mixtos/superpuestos.

chartjs
datasets: [{
  label: 'Revenue',
  data: [10, 20, 30],
  backgroundColor: 'rgba(54,162,235,0.6)',
  borderColor: 'rgba(54,162,235,1)',
  borderWidth: 2,
  hoverBackgroundColor: 'rgba(54,162,235,0.9)',
  hidden: false,                  // set true to hide from view + legend toggle
  order: 0                        // lower order draws on top
}]

Parsear datos de objetos

Cuando tus datos son un array de objetos, indica a Chart.js qué campos contienen los valores de los ejes mediante parsing: {xAxisKey, yAxisKey}. Esto evita el mapeo manual a pares {x, y}. Las claves por defecto son 'x' e 'y', así que los objetos {x, y} funcionan sin configuración de parsing.

chartjs
new Chart(ctx, {
  type: 'bar',
  data: {
    datasets: [{
      data: [
        { name: 'Red', votes: 12 },
        { name: 'Blue', votes: 19 }
      ],
      parsing: { xAxisKey: 'name', yAxisKey: 'votes' }
    }]
  }
});

Arrays de estilo por punto

Cualquier propiedad de estilo puede ser un único valor (se aplica a cada punto) o un array (uno por punto). Esto permite resaltar puntos concretos — por ejemplo, pon la mayoría de los backgroundColor en gris y uno en rojo para llamar la atención. La longitud del array debería coincidir con la de los datos; los arrays más cortos ciclan.

chartjs
datasets: [{
  data: [10, 20, 30, 40],
  // every styling property accepts an array (one value per point)
  backgroundColor: ['red', 'green', 'blue', 'orange'],
  borderColor:     ['darkred', 'darkgreen', 'darkblue', 'darkorange'],
  borderWidth: [1, 2, 3, 4],
  pointRadius: [3, 6, 9, 12]   // (line/scatter only)
}]
10

Opciones — Responsivo y escalas

Estructura de options

options es el objeto de configuración de nivel superior. Agrupa las preocupaciones: plugins (legend/title/tooltip), scales (x/y/r), layout (padding), animation, interaction (modo hover) y events. La mayor parte del comportamiento de Chart.js se ajusta aquí en lugar de en los datasets individuales.

chartjs
new Chart(ctx, {
  type: 'bar',
  data: { /* ... */ },
  options: {
    responsive: true,
    maintainAspectRatio: true,
    plugins: { legend: {}, title: {}, tooltip: {} },
    scales:  { x: {}, y: {} },
    layout:  { padding: 10 },
    animation: { duration: 800 },
    interaction: { mode: 'nearest', intersect: false },
    events: ['mousemove', 'click', 'touchstart']
  }
});

Responsive y maintainAspectRatio

responsive:true hace que el gráfico llene el ancho de su contenedor y se re-renderice al redimensionar. maintainAspectRatio:false libera la altura para que se respete la altura CSS del contenedor — fija ambos y envuelve el canvas en un <div> con tamaño. Con maintainAspectRatio:true (por defecto) el gráfico mantiene una relación ancho/alto fija.

chartjs
<div style="width:100%; height:400px;">
  <canvas id="c"></canvas>
</div>

<script>
new Chart(document.getElementById('c'), {
  type: 'line',
  data: { /* ... */ },
  options: {
    responsive: true,           // resize with container
    maintainAspectRatio: false  // let the container control height
  }
});
</script>

Vista general de las escalas

scales configura cada eje. El id (x, y, r) es la clave de la escala; type selecciona la clase de escala. Tipos comunes: 'category' (etiquetas de texto), 'linear' (números), 'logarithmic', 'time' (requiere un adaptador de fechas), 'radialLinear' (radar/polar). title.display + text añade una etiqueta al eje.

chartjs
options: {
  scales: {
    x: { type: 'category', title: { display: true, text: 'Month' } },
    y: { type: 'linear',   title: { display: true, text: 'Value' },
         beginAtZero: true },
    r: { type: 'radialLinear' }   // for radar/polarArea
  }
}
// built-in scale types: category, linear, logarithmic, time,
//                       timeseries, radialLinear

Vista general de los plugins

plugins agrupa los plugins integrados title, legend y tooltip, además de las opciones de los plugins personalizados registrados, por su id. title añade un título al gráfico sobre el canvas. legend controla la clave de datasets. tooltip controla las ventanas emergentes al pasar el ratón. Los plugins personalizados leen sus opciones de este mismo objeto plugins.

chartjs
options: {
  plugins: {
    title:   { display: true, text: 'My Chart', font: { size: 18 } },
    legend:  { display: true, position: 'top' },
    tooltip: { enabled: true, mode: 'index', intersect: false },
    // a custom inline plugin:
    myPlugin: { prop: 'value' }
  }
}

Layout (padding)

layout.padding añade espacio dentro del canvas entre el área del gráfico y el borde del canvas — útil cuando los títulos, las etiquetas de los ejes o los tooltips grandes quedarían recortados. Un solo número rellena por igual los cuatro lados; la forma de objeto permite valores por lado.

chartjs
options: {
  layout: {
    padding: {
      top: 10, right: 20, bottom: 10, left: 20
    }
  }
}
// or a single number for all four sides:
// layout: { padding: 15 }

Valores por defecto globales (Chart.defaults)

Chart.defaults contiene la configuración por defecto global — fija los valores una vez al arrancar la app y cada gráfico los hereda. Es el lugar adecuado para la identidad de marca (familia de fuentes, color base, animación por defecto). Las opciones por gráfico siempre sobrescriben los valores por defecto, así que aún puedes personalizar gráficos individuales.

chartjs
// set once, applies to every chart created afterwards
Chart.defaults.font.family = "'Segoe UI', sans-serif";
Chart.defaults.font.size = 13;
Chart.defaults.color = '#333';
Chart.defaults.borderColor = '#ddd';
Chart.defaults.plugins.legend.labels.color = '#333';
Chart.defaults.animation.duration = 600;

// per-chart override still wins:
new Chart(ctx, { options: { font: { size: 16 } } });
11

Ejes — X e Y

Eje lineal

Un eje lineal mapea números proporcionalmente. beginAtZero fuerza al eje a empezar en 0 (recomendado para gráficos de barras). min/max fijan límites duros; suggestedMin/suggestedMax son sugerencias blandas que Chart.js puede ampliar para encajar los ticks. ticks.callback personaliza el texto de la etiqueta (por ejemplo, añadir una unidad).

chartjs
options: {
  scales: {
    y: {
      type: 'linear',
      beginAtZero: true,
      min: 0, max: 100,        // hard limits
      ticks: { stepSize: 10, callback: (v) => v + '%' }
    }
  }
}

Eje de categorías

Un eje de categorías muestra etiquetas de texto en posiciones fijas. Es el eje x por defecto de los gráficos de barras/líneas. ticks.autoSkip:false fuerza a mostrar todas las etiquetas (si no, Chart.js descarta las que se solapan). maxRotation inclina las etiquetas para evitar el solapamiento cuando hay muchas categorías.

chartjs
options: {
  scales: {
    x: {
      type: 'category',
      labels: ['Mon','Tue','Wed'],   // optional; usually from data.labels
      ticks: { autoSkip: false, maxRotation: 45, minRotation: 0 }
    }
  }
}

Eje temporal

Un eje temporal traza objetos Date o cadenas ISO proporcionalmente al tiempo, con huecos donde no hay datos. Requiere un paquete de adaptador de fechas (chartjs-adapter-date-fns, -luxon, -dayjs). time.unit fija la granularidad de los ticks ('day','month','year'); sin ella, Chart.js elige una unidad automáticamente.

chartjs
# install a date adapter
npm install chart.js date-fns date-fns-tz

import 'chartjs-adapter-date-fns';

new Chart(ctx, {
  type: 'line',
  data: { datasets: [{ data: [
    {x: new Date('2024-01-01'), y: 10},
    {x: new Date('2024-02-01'), y: 20},
    {x: new Date('2024-04-01'), y: 15}
  ]}]},
  options: { scales: { x: { type: 'time', time: { unit: 'month' } } } }
});

Eje logarítmico

Un eje logarítmico espacia los ticks por potencias de 10, esencial para datos que abarcan órdenes de magnitud (población, precios, frecuencias). No puede mostrar 0 ni valores negativos. ticks.callback te permite formatear las etiquetas de potencias de diez de forma compacta (por ejemplo, notación científica).

chartjs
new Chart(ctx, {
  type: 'line',
  data: { datasets: [{ data: [1, 10, 100, 1000, 10000] }] },
  options: {
    scales: {
      y: { type: 'logarithmic',
           ticks: { callback: (v) => v >= 1 ? v.toExponential(0) : v } }
    }
  }
});

Título del eje y callback de ticks

title.display + title.text añaden una etiqueta al eje (desactivada por defecto — fija display:true). ticks.callback recibe cada valor de tick y devuelve la cadena a mostrar, permitiéndote formatear los números como moneda, porcentajes, abreviaturas k/M o cualquier texto personalizado sin alterar los datos subyacentes.

chartjs
options: {
  scales: {
    y: {
      title: { display: true, text: 'Revenue (USD)', color: '#333', font: { size: 14, weight: 'bold' } },
      ticks: {
        callback: function(value) {
          if (value >= 1000) return (value/1000) + 'k';
          return value;
        }
      }
    }
  }
}

min/max vs suggestedMin/Max

min/max son límites DUROS: el eje se mantiene dentro de ellos incluso si los datos exceden el rango (los datos se recortan). suggestedMin/suggestedMax son sugerencias BLANDAS: Chart.js las usa como base pero puede ampliarlas para producir valores de tick redondos. Prefiere suggested* cuando quieras números redondos bonitos; usa min/max duros para escalas fijas como porcentajes.

chartjs
options: {
  scales: {
    y: {
      // hard limits — chart never goes outside this range
      min: 0, max: 100,
      // OR soft hints — Chart.js may expand to fit nice ticks:
      // suggestedMin: 0, suggestedMax: 100,
      ticks: { stepSize: 20 }
    }
  }
}
12

Leyenda

Fundamentos de la leyenda

La leyenda lista la etiqueta de cada dataset con una muestra de color. display:true la muestra (por defecto), display:false la oculta. position acepta 'top', 'bottom', 'left', 'right' o 'center' (chartArea). Hacer clic en un ítem de la leyenda alterna la visibilidad de ese dataset por defecto — una interacción de filtrado integrada.

chartjs
new Chart(ctx, {
  type: 'bar',
  data: { labels: ['A','B'], datasets: [{ label: 'Sales', data: [10,20] }] },
  options: {
    plugins: {
      legend: { display: true, position: 'top' }
    }
  }
});

Posición y alineación de la leyenda

position fija el lado de la leyenda; align controla su colocación a lo largo de ese lado ('start'/'center'/'end'). labels configura la muestra (boxWidth/boxHeight) y el estilo del texto. maxWidth limita el área de la leyenda para que las leyendas muy largas se envuelvan en lugar de empujar el gráfico a un lado.

chartjs
plugins: {
  legend: {
    position: 'bottom',
    align: 'center',     // 'start' | 'center' | 'end'
    maxWidth: 300,
    labels: {
      boxWidth: 20,
      boxHeight: 20,
      padding: 15,
      color: '#333',
      font: { size: 12 }
    }
  }
}

onClick de la leyenda (toggle personalizado)

Sobrescribe legend.onClick para personalizar el comportamiento del clic. El predeterminado alterna la visibilidad del dataset. La firma es (event, legendItem, legend). Llamar a chart.update() tras cambiar el estado re-renderiza. Úsalo para confirmar antes de ocultar, sincronizar con una UI externa o implementar comportamiento de selección única (radio).

chartjs
plugins: {
  legend: {
    onClick(e, item, legend) {
      const chart = legend.chart;
      const dataset = chart.data.datasets[item.datasetIndex];
      // custom: toggle visibility AND log the action
      dataset.hidden = !dataset.hidden;
      console.log('Toggled', dataset.label, '->', dataset.hidden);
      chart.update();
    }
  }
}

Callback de las etiquetas de la leyenda

generateLabels devuelve un array de objetos de etiqueta que controla por completo lo que aparece en la leyenda. El texto de cada ítem, los colores de la muestra y el estado hidden pueden personalizarse — útil para añadir contadores, unidades o derivar una leyenda de datos que no son datasets. El flag hidden y datasetIndex enlazan los clics de vuelta al dataset correcto.

chartjs
plugins: {
  legend: {
    labels: {
      generateLabels(chart) {
        return chart.data.datasets.map((ds, i) => ({
          text: `${ds.label} (${ds.data.length} pts)`,
          fillStyle: ds.backgroundColor,
          strokeStyle: ds.borderColor,
          lineWidth: ds.borderWidth,
          hidden: ds.hidden,
          datasetIndex: i
        }));
      }
    }
  }
}

Ocultar la leyenda y leyenda externa

Para control total del estilo, desactiva la leyenda integrada (display:false) y renderiza tu propia leyenda HTML. Itera chart.data.datasets, renderiza botones/muestras y alterna dataset.hidden + chart.update() al hacer clic. Es común al adaptarse a un sistema de diseño donde la leyenda de canvas por defecto no encaja.

chartjs
// hide the built-in legend entirely
options: { plugins: { legend: { display: false } } }

// build your own external legend HTML, then wire it to the chart:
const chart = new Chart(ctx, { /* ... */, options: { plugins: { legend: { display: false } } } });

chart.data.datasets.forEach((ds, i) => {
  const btn = document.createElement('button');
  btn.textContent = ds.label;
  btn.onclick = () => { ds.hidden = !ds.hidden; chart.update(); };
  document.getElementById('legend').appendChild(btn);
});
13

Tooltips

Fundamentos del tooltip

Los tooltips aparecen al pasar el ratón mostrando la etiqueta del dataset y el valor. enabled:true por defecto. Las propiedades de estilo (backgroundColor, titleColor, bodyColor, padding, cornerRadius) controlan el aspecto. displayColors alterna las pequeñas muestras de color junto a cada ítem — útil cuando muchos datasets se solapan.

chartjs
options: {
  plugins: {
    tooltip: {
      enabled: true,           // show tooltips
      backgroundColor: 'rgba(0,0,0,0.8)',
      titleColor: 'white',
      bodyColor: 'white',
      borderColor: 'gray',
      borderWidth: 1,
      padding: 10,
      cornerRadius: 4,
      displayColors: true      // show color boxes
    }
  }
}

Callback label del tooltip

callbacks.label devuelve el texto de cada fila del tooltip. ctx.dataset.label es el nombre de la serie, ctx.parsed.y contiene el valor (usa ctx.parsed para pie/radar). Formatea moneda, añade unidades o calcula totales aquí. La cadena devuelta (o array de cadenas) se convierte en el cuerpo del tooltip.

chartjs
plugins: {
  tooltip: {
    callbacks: {
      label: (ctx) => {
        const label = ctx.dataset.label || '';
        const value = ctx.parsed.y ?? ctx.parsed;
        return `${label}: $${value}`;
      }
    }
  }
}

Callback title del tooltip

callbacks.title controla el encabezado del tooltip (por defecto: la etiqueta del eje x). La función recibe un array de ítems del tooltip (útil cuando mode:'index' agrupa varios datasets). Devolver una cadena vacía '' suprime el título por completo. Combina los callbacks title y label para un contenido de tooltip totalmente personalizado.

chartjs
plugins: {
  tooltip: {
    callbacks: {
      title: (items) => {
        // items[0].label is the x-axis label / category
        return 'Period: ' + items[0].label;
      },
      label: (ctx) => ctx.dataset.label + ': ' + ctx.formattedValue
    }
  }
}

Tooltip HTML externo

external permite renderizar el tooltip como HTML real — para estilos ricos, imágenes o enlaces imposibles en canvas. Fija enabled:false para que el tooltip por defecto no se renderice por duplicado. El callback recibe un contexto con un objeto tooltip que contiene caretX/caretY (posición) y las líneas del cuerpo. Posiciona el elemento HTML en esas coordenadas.

chartjs
plugins: {
  tooltip: {
    enabled: false,                  // disable default canvas tooltip
    external(context) {
      const { tooltip } = context;
      let el = document.getElementById('tt');
      if (!el) { el = document.createElement('div'); el.id = 'tt'; document.body.appendChild(el); }
      if (tooltip.opacity === 0) { el.style.opacity = 0; return; }
      el.innerHTML = tooltip.body.map(b => b.lines.join('')).join('<br>');
      el.style.position = 'fixed';
      el.style.left = tooltip.caretX + 'px';
      el.style.top  = tooltip.caretY + 'px';
      el.style.opacity = 1;
    }
  }
}

Modo del tooltip (interaction)

interaction.mode controla a qué apunta el tooltip. 'point' muestra solo el punto bajo el cursor; 'index' muestra cada dataset en la misma x (genial para barras/líneas agrupadas); 'nearest' encuentra el punto individual más cercano. intersect:false dispara el tooltip cuando el puntero está en cualquier parte de la columna, no solo sobre un punto — normalmente lo que los usuarios esperan.

chartjs
options: {
  interaction: {
    mode: 'index',     // 'point' | 'nearest' | 'index' | 'x' | 'y' | 'dataset'
    intersect: false   // trigger even when not directly over a point
  },
  plugins: { tooltip: { mode: 'index', intersect: false } }
}

Estilo del tooltip y filtros

filter salta las filas del tooltip que no cumplen una condición (por ejemplo, ocultar valores cero o vacíos). callbacks.footer añade una fila de resumen tras los ítems — perfecto para mostrar un total. bodyFont/titleFont estilizan el texto; caretSize y caretPadding controlan la pequeña flecha del puntero.

chartjs
plugins: {
  tooltip: {
    filter: (item) => item.parsed.y !== 0,   // hide zero values
    callbacks: { footer: (items) => 'Total: ' + items.reduce((s,i)=>s+i.parsed.y,0) },
    bodyFont: { size: 13, weight: 'bold' },
    titleFont: { size: 14 },
    caretSize: 6,
    caretPadding: 8
  }
}
14

Animación

Duración de la animación

animation.duration fija la duración total de la animación en milisegundos (1000 por defecto). easing controla la curva de aceleración — 'easeOutQuart' (el predeterminado) arranca rápido y desacelera, lo que se siente responsivo. Acorta la duración (200-400ms) en dashboards de datos que se actualizan con frecuencia.

chartjs
options: {
  animation: {
    duration: 1000,      // total duration in ms
    easing: 'easeOutQuart'
  }
}
// easing options: 'linear','easeInQuad','easeOutQuad','easeInOutQuad',
// 'easeInCubic','easeOutCubic','easeInOutCubic','easeOutBounce',...

Desactivar la animación

Fija animation:false para desactivar todas las animaciones por completo — lo mejor para dashboards de rendimiento crítico o al alimentar actualizaciones rápidas. animation:{duration:0} mantiene el sistema de animación activo pero instantáneo (el hover sigue funcionando). El objeto animations en plural permite desactivar propiedades concretas como y mientras se animan otras.

chartjs
// disable ALL animations
options: { animation: false }

// disable only the initial draw, keep hover animations:
options: { animation: { duration: 0 } }

// per-property: animate everything except the y axis
options: {
  animations: {
    y: { duration: 0 }
  }
}

Funciones de easing

El easing cambia cómo progresa una animación en el tiempo, afectando drásticamente la sensación. 'easeOutQuart' (por defecto) se siente profesional y responsivo. 'easeOutBounce' o 'easeInOutBack' son juguetones pero pueden parecer artificiales en gráficos de datos. Ajusta el easing al lenguaje de movimiento general de tu app.

chartjs
options: {
  animation: {
    duration: 1200,
    easing: 'easeInOutBack'   // slight overshoot for a playful feel
  }
}
// common easings:
// 'linear'            constant speed (mechanical)
// 'easeOutQuart'      default; snappy start, smooth end
// 'easeInOutCubic'    symmetric in/out
// 'easeOutBounce'     bouncy landing
// 'easeInOutBack'     overshoots at both ends

onComplete de la animación

onComplete se dispara cuando termina una animación — útil para encadenar acciones como habilitar un botón de exportación o disparar un render posterior. onProgress se dispara en cada fotograma de animación con el contador de pasos. Evita el trabajo pesado en onProgress, ya que se ejecuta 60 veces por segundo.

chartjs
options: {
  animation: {
    onComplete: function() {
      console.log('Animation finished');
      // e.g. enable a "download PNG" button now that the chart is stable
      document.getElementById('downloadBtn').disabled = false;
    },
    onProgress: function(ctx) {
      // fired each frame; ctx.currentStep / ctx.numSteps
    }
  }
}

Animación por propiedad (animations)

El objeto animations en plural configura propiedades individuales de forma independiente. Cada entrada puede especificar from/to (o una función del contexto de parsing), duration, easing y loop. Animar tension de 1 a 0.3 produce un efecto de 'la línea se asienta'; animar y desde la línea base del eje produce un efecto de 'crecer hacia arriba'.

chartjs
options: {
  animations: {
    tension: {
      duration: 1500,
      easing: 'easeOutBounce',
      from: 1,           // start very curved
      to: 0.3,           // settle at a gentle curve
      loop: false
    },
    colors: { duration: 800 },
    y: { from: ctx => ctx.chart.scales.y.getPixelForValue(0) }
  }
}
15

Eventos y clics

Manejador onClick

options.onClick se dispara cuando el usuario hace clic en cualquier parte del gráfico. El argumento elements es un array de elementos del gráfico clicados (barras/puntos), cada uno con .datasetIndex e .index. Si elements está vacío, el clic dio en el canvas vacío. Esta es la forma estándar de hacer los gráficos interactivos (drill-down, selección).

chartjs
new Chart(ctx, {
  type: 'bar',
  data: { labels: ['A','B','C'], datasets: [{ data: [10,20,30] }] },
  options: {
    onClick(event, elements, chart) {
      if (elements.length > 0) {
        const el = elements[0];
        const label = chart.data.labels[el.index];
        const value = chart.data.datasets[el.datasetIndex].data[el.index];
        alert(`Clicked ${label} = ${value}`);
      }
    }
  }
});

getElementsAtEventForMode

getElementsAtEventForMode encuentra los elementos del gráfico bajo un evento nativo de ratón, con las mismas opciones de modo que interaction ('nearest', 'index', 'x', etc.). El cuarto argumento useFinalPosition debe ser true para el hit-testing sobre las posiciones finales renderizadas. Úsalo cuando necesites búsquedas de elementos fuera de options.onClick.

chartjs
const chart = new Chart(ctx, { /* ... */ });

canvas.addEventListener('click', (e) => {
  const points = chart.getElementsAtEventForMode(
    e, 'nearest', { intersect: true }, true   // (event, mode, options, useFinalPosition)
  );
  if (points.length) {
    const p = points[0];
    console.log('dataset', p.datasetIndex, 'index', p.index);
  }
});

onHover

options.onHover se dispara en cada movimiento del ratón sobre el gráfico. Úsalo para retroalimentación de UI barata, como cambiar el cursor (como se muestra) o resaltar elementos externos relacionados. Evita operaciones costosas aquí — se dispara con mucha frecuencia. Para lógica más pesada, usa onClick o aplica debounce al manejador.

chartjs
options: {
  onHover(event, elements, chart) {
    // change cursor to a pointer when hovering a bar
    event.native.target.style.cursor =
      elements.length ? 'pointer' : 'default';
  }
}

Hover y elementos activos

La configuración hover controla cómo el gráfico resalta los elementos bajo el puntero. mode:'nearest' + intersect:true resalta el único punto más cercano. animationDuration suaviza la transición del resaltado. chart.setActiveElements dispara programáticamente el estado hover — útil para sincronizar los resaltados del gráfico con una UI externa.

chartjs
options: {
  hover: {
    mode: 'nearest',
    intersect: true,
    animationDuration: 200   // smooth transition when hover target changes
  }
}
// programmatically set the hovered element:
chart.setActiveElements([{ datasetIndex: 0, index: 2 }]);
chart.update();

Lista de eventos

events limita qué eventos del DOM escucha el gráfico. Reducir la lista (por ejemplo, solo a 'click') desactiva los efectos hover para una sensación estática y mejora el rendimiento en dashboards. Para contextos móviles de solo táctil, incluye touchstart/touchmove. Un array vacío desactiva toda interacción.

chartjs
options: {
  events: ['mousemove', 'mouseout', 'click', 'touchstart', 'touchmove']
  // restrict to just click for a non-interactive "static" feel:
  // events: ['click']
}
// supported events: mousemove, mouseout, click, touchstart, touchmove,
//                   touchend, pointer events (Chart.js v3.4+)

Ejemplo de drill-down

Un patrón común: hacer clic en una barra cambia el dataset a una vista más detallada (drill-down). Captura el índice clicado, reemplaza chart.data.labels y chart.data.datasets[...].data, y llama a chart.update() para animar la transición. Mantén una pila de vistas si quieres un botón de volver.

chartjs
const monthly = { labels: ['Jan','Feb','Mar'], data: [100,120,90] };
const daily = { labels: Array.from({length:28},(_,i)=>'D'+(i+1)),
                data: Array.from({length:28},()=>Math.random()*50) };

const chart = new Chart(ctx, {
  type: 'bar',
  data: { labels: monthly.labels, datasets: [{ data: monthly.data }] },
  options: { onClick(evt, els) {
    if (!els.length) return;
    const idx = els[0].index;
    chart.data.labels = daily.labels;
    chart.data.datasets[0].data = daily.data;
    chart.update();
  }}
});
16

Gráficos mixtos

Gráfico mixto de barras + líneas

Mezcla tipos de gráficos fijando type en datasets individuales — sobrescribe el tipo a nivel de gráfico para esa serie. La combinación de barras + líneas es la mezcla más común (por ejemplo, ingresos como barras, tasa de crecimiento como línea). Usa un segundo eje y (y1) cuando las series tengan unidades o escalas distintas.

chartjs
new Chart(ctx, {
  type: 'bar',                          // default type for all datasets
  data: {
    labels: ['Jan','Feb','Mar','Apr'],
    datasets: [
      { type: 'bar',  label: 'Revenue', data: [20,35,30,40], backgroundColor: '#36A2EB', yAxisID: 'y' },
      { type: 'line', label: 'Growth',  data: [5,8,6,12],    borderColor: '#FF6384', yAxisID: 'y1', fill: false }
    ]
  },
  options: { scales: { y: { position: 'left' }, y1: { position: 'right', grid: { drawOnChartArea: false } } } }
});

Sobrescritura del type del dataset

Cualquier dataset puede sobrescribir el tipo a nivel de gráfico, permitiendo combinar bar, line y scatter en un solo gráfico. Los datasets sin type explícito heredan el tipo del gráfico. Cuida el orden z: los datasets se dibujan en orden de array, así que coloca las series de fondo (barras) antes que las de primer plano (líneas).

chartjs
new Chart(ctx, {
  type: 'line',                // chart-level default
  data: {
    labels: ['A','B','C'],
    datasets: [
      { data: [1,2,3] },                          // inherits 'line'
      { type: 'bar', data: [3,2,1] },              // becomes a bar
      { type: 'scatter', data: [{x:0,y:2},{x:2,y:3}], pointRadius: 5 }  // scatter points
    ]
  }
});

Múltiples ejes Y (y, y1, y2)

Define varios ejes y con ids personalizados (y, y1, y2) y asigna los datasets mediante yAxisID. grid.drawOnChartArea:false evita que el segundo eje dibuje líneas de cuadrícula sobre el primero. position:'right' lo apila a la derecha; añade offset:true a un tercer eje para que no se solape con el segundo. Colorea cada eje para que coincida con su serie.

chartjs
options: {
  scales: {
    y:  { type: 'linear', position: 'left',  title: { display: true, text: 'Price ($)' } },
    y1: { type: 'linear', position: 'right', title: { display: true, text: 'Volume' }, grid: { drawOnChartArea: false } },
    y2: { type: 'linear', position: 'right', offset: true, title: { display: true, text: '%' } }
  }
}
// assign each dataset: yAxisID: 'y' | 'y1' | 'y2'

Datos mixtos con formas distintas

Los gráficos mixtos pueden combinar una serie de valores (barras) con líneas de referencia (objetivo constante, tendencia). Fija pointRadius:0 y fill:false en los datasets de línea para que se rendericen como líneas puras sin marcadores ni rellenos. Este patrón es común en dashboards de rendimiento (real vs objetivo).

chartjs
new Chart(ctx, {
  type: 'bar',
  data: {
    labels: ['Mon','Tue','Wed','Thu','Fri'],
    datasets: [
      { type:'bar',  label:'Tasks', data:[8,6,7,9,5], backgroundColor:'rgba(54,162,235,0.6)' },
      { type:'line', label:'Target',data:[7,7,7,7,7], borderColor:'red', borderWidth:2, pointRadius:0, fill:false },
      { type:'line', label:'Trend', data:[6,6.5,7,8,8.5], borderColor:'green', borderDash:[5,5], pointRadius:0, fill:false }
    ]
  }
});

Consejos de estilo mixto

En gráficos mixtos, fija dataset.order para que la línea se dibuje sobre las barras (order menor = encima). Codifica por color los ticks y el título de cada eje para que coincidan con su serie y los lectores sepan qué escala pertenece a qué línea. Desactiva la cuadrícula del segundo eje (drawOnChartArea:false) para evitar líneas de cuadrícula dobles.

chartjs
// 1. assign order so lines draw on top of bars
datasets: [
  { type:'bar',  data:[...], order: 2 },
  { type:'line', data:[...], order: 1 }   // lower order draws later (on top)
]
// 2. give each axis a matching color
options: { scales: {
  y:  { ticks: { color: '#36A2EB' }, title: { text: 'Revenue', color: '#36A2EB' } },
  y1: { ticks: { color: '#FF6384' }, title: { text: 'Growth',  color: '#FF6384' }, position: 'right', grid: { drawOnChartArea: false } }
}}
17

Plugins

Plugins integrados

Chart.js incluye tres plugins integrados: Title (título del gráfico sobre el canvas), Legend (la clave de datasets) y Tooltip (ventanas emergentes al pasar el ratón). Se configuran bajo options.plugins por su id y están activados por defecto (salvo Title, que necesita display:true para mostrar su texto).

chartjs
// three built-in plugins (always available):
//   Legend   -> options.plugins.legend
//   Title    -> options.plugins.title
//   Tooltip  -> options.plugins.tooltip

new Chart(ctx, {
  type: 'line',
  data: { /* ... */ },
  options: {
    plugins: {
      title:  { display: true, text: 'Sales 2024', font: { size: 18 } },
      legend: { position: 'bottom' },
      tooltip:{ mode: 'index', intersect: false }
    }
  }
});

Plugin personalizado en línea

Pasa un array de objetos plugin a un solo gráfico mediante la opción plugins. Cada plugin tiene un id y funciones de hook (beforeInit, afterInit, beforeDraw, afterDraw, beforeUpdate, etc.). Los plugins en línea se aplican solo a esa instancia del gráfico. ctx.save()/restore() acotan cualquier cambio de estado del canvas que hagas.

chartjs
new Chart(ctx, {
  type: 'line',
  data: { /* ... */ },
  options: { /* ... */ },
  plugins: [{
    id: 'centerText',
    afterDraw(chart) {
      const { ctx, chartArea } = chart;
      ctx.save();
      ctx.font = 'bold 24px Arial';
      ctx.fillStyle = 'black';
      ctx.textAlign = 'center';
      ctx.textBaseline = 'middle';
      ctx.fillText('Hello', (chartArea.left+chartArea.right)/2,
                            (chartArea.top+chartArea.bottom)/2);
      ctx.restore();
    }
  }]
});

Hooks de plugin (ciclo de vida)

Los hooks de plugin se ejecutan en cada etapa del ciclo de vida del gráfico: init, update, render, draw, resize, destroy. Los hooks before* pueden cancelar una acción devolviendo false. El más común para dibujo personalizado es afterDraw (dibujar sobre el gráfico) o beforeDraw (dibujar detrás de los datos). Cada hook recibe la instancia del gráfico.

chartjs
const plugin = {
  id: 'myHook',
  beforeInit(chart)  { console.log('before init'); },
  afterInit(chart)   { console.log('chart ready'); },
  beforeUpdate(chart){ console.log('about to update'); },
  beforeDraw(chart)  { console.log('before draw'); },
  afterDraw(chart)   { console.log('after draw'); },
  beforeRender(chart){ console.log('before first render'); },
  resize(chart, size){ console.log('resized', size); },
  destroy(chart)     { console.log('destroyed'); }
};

Plugin: línea vertical en un índice

Un plugin personalizado común dibuja una guía vertical en la posición del tooltip (como la mira por defecto). afterDraw lee la coordenada x del elemento tooltip activo y traza una línea discontinua de arriba a abajo del área del gráfico. Envuelve el estado del canvas en save()/restore() para que el estilo de línea discontinua no se filtre.

chartjs
const verticalLine = {
  id: 'verticalLine',
  afterDraw(chart) {
    if (chart.tooltip?._active?.length) {
      const x = chart.tooltip._active[0].element.x;
      const { top, bottom } = chart.chartArea;
      const ctx = chart.ctx;
      ctx.save();
      ctx.beginPath();
      ctx.moveTo(x, top);
      ctx.lineTo(x, bottom);
      ctx.lineWidth = 1;
      ctx.strokeStyle = 'gray';
      ctx.setLineDash([4, 4]);
      ctx.stroke();
      ctx.restore();
    }
  }
};

Plugin: texto central para doughnut

Dibujar un texto de resumen centrado es el caso de uso clásico de un plugin para doughnut. afterDatasetsDraw se ejecuta tras los sectores, así que el texto queda encima. Calcula el total (o cualquier resumen) y renderízalo en el centro geométrico del chartArea. Esto convierte un doughnut en un widget KPI informativo.

chartjs
const centerText = {
  id: 'centerText',
  afterDatasetsDraw(chart) {
    const { ctx, data } = chart;
    const total = data.datasets[0].data.reduce((a,b)=>a+b, 0);
    ctx.save();
    ctx.font = 'bold 28px Arial';
    ctx.fillStyle = '#333';
    ctx.textAlign = 'center';
    ctx.textBaseline = 'middle';
    const { left, right, top, bottom } = chart.chartArea;
    ctx.fillText(total, (left+right)/2, (top+bottom)/2);
    ctx.restore();
  }
};
new Chart(ctx, { type:'doughnut', data:{...}, plugins:[centerText] });

Registrar plugin globalmente

Chart.register(plugin) hace que un plugin se aplique a cada gráfico creado a partir de entonces — ideal para plugins de toda la app como marcas de agua, branding o analítica. Para un gráfico puntual, usa el array plugins en línea en su lugar. Chart.unregister lo elimina. Los plugins registrados leen su configuración de options.plugins[id].

chartjs
import { Chart } from 'chart.js';

const myPlugin = { id: 'watermark', afterDraw(chart) { /* ... */ } };

// register once -> applies to EVERY chart
Chart.register(myPlugin);

// or unregister later
Chart.unregister(myPlugin);

// per-chart-only: skip Chart.register and pass via options.plugins instead
18

Actualizar y destruir

chart.update()

Tras mutar chart.data o chart.options, llama a chart.update() para re-renderizar. Por defecto el cambio se anima desde el estado anterior. Pasa 'none' como modo para saltarte la animación (útil para actualizaciones de alta frecuencia). Mutar y actualizar es mucho más barato que destruir y recrear el gráfico.

chartjs
const chart = new Chart(ctx, config);

// mutate the data/config, then update:
chart.data.labels.push('Jun');
chart.data.datasets[0].data.push(28);
chart.options.scales.y.max = 50;

chart.update();   // animate to the new state
// chart.update('none');   // skip animation

Modos de actualización

update(mode) acepta una cadena de modo que controla el comportamiento. 'none' desactiva la animación para un refresco silencioso. 'reset' rebobina a los valores previos a la animación y vuelve a animar (bueno para repetir la entrada). 'active' actualiza solo los elementos bajo el cursor para re-renders de hover baratos. El predeterminado (sin argumento) anima con normalidad.

chartjs
chart.update();             // default: animates the change
chart.update('none');       // no animation
chart.update('reset');      // reset to pre-animation state, then animate
chart.update('resize');     // re-compute layout (call after container resize)
chart.update('show');       // show currently-hidden dataset animations
chart.update('hide');       // hide dataset animations
chart.update('active');     // update only the active (hovered) elements

Actualizar datos y etiquetas

Puedes reemplazar data/labels por completo o mutarlos in situ (push/shift). Para gráficos de transmisión en vivo (por ejemplo, una ventana de 60 segundos), añade el nuevo valor y desplaza el más antiguo, y luego update('none') para un refresco suave sin animación — llamar a la actualización animada por defecto en cada tick causa un lag entrecortado.

chartjs
// replace the entire data array
chart.data.datasets[0].data = [5, 10, 15, 20];
chart.data.labels = ['A','B','C','D'];
chart.update();

// or append streaming data (and trim the oldest):
const arr = chart.data.datasets[0].data;
arr.push(newValue);
if (arr.length > 60) arr.shift();
chart.update('none');   // instant update for live data

chart.destroy()

destroy() desmonta el gráfico: elimina los listeners de eventos, cancela las animaciones, limpia el canvas y libera memoria. Llama siempre a destroy cuando el contenedor de un gráfico se elimina (limpieza de useEffect en React, cambio de ruta). No destruir provoca fugas de memoria y puede lanzar errores 'Canvas is already in use' al reutilizar un canvas.

chartjs
const chart = new Chart(ctx, config);

// when done (route change, component unmount, etc.):
chart.destroy();

// after destroy the canvas is free; a new Chart can reuse it:
const fresh = new Chart(ctx, newConfig);

// destroy also removes event listeners and frees memory

chart.resize() y clear()

chart.resize() recalcula el tamaño del gráfico — con responsive:true esto ocurre automáticamente al redimensionar la ventana, así que las llamadas manuales son raras. chart.clear() blanquea el canvas sin destruir el gráfico (la próxima actualización vuelve a dibujar). chart.resize(width, height) fuerza dimensiones de píxeles concretas, sobrescribiendo el tamaño responsivo.

chartjs
const chart = new Chart(ctx, config);

// manually trigger a resize (rarely needed; responsive:true auto-resizes)
chart.resize();

// clear the canvas (chart stays alive, just blank until next render):
chart.clear();
chart.draw();   // re-draw without recomputing layout

// resize the canvas to explicit dimensions:
chart.resize(800, 400);
19

Responsivo y device pixel ratio

Contenedor responsivo

Para un gráfico responsivo, envuelve el canvas en un contenedor posicionado con width/height explícitos y fija responsive:true + maintainAspectRatio:false. El canvas llena el contenedor y se re-renderiza al redimensionar la ventana. Sin maintainAspectRatio:false, el gráfico mantiene una relación de aspecto fija e ignora la altura del contenedor.

chartjs
<!-- container controls the size -->
<div style="position: relative; width: 100%; height: 400px;">
  <canvas id="c"></canvas>
</div>

<script>
new Chart(document.getElementById('c'), {
  type: 'line',
  data: { /* ... */ },
  options: { responsive: true, maintainAspectRatio: false }
});
</script>

maintainAspectRatio

maintainAspectRatio:true (por defecto) mantiene el canvas en una relación ancho/alto fija definida por aspectRatio (2 por defecto = 2:1). maintainAspectRatio:false libera la altura al contenedor. Pie/doughnut usan aspectRatio:1 (cuadrado) por defecto, ya que los círculos se ven mal en un rectángulo ancho.

chartjs
// default: chart keeps a 2:1 (width:height) aspect ratio
options: { responsive: true, maintainAspectRatio: true, aspectRatio: 2 }

// let the container control height:
options: { responsive: true, maintainAspectRatio: false }

// square charts:
options: { responsive: true, maintainAspectRatio: true, aspectRatio: 1 }

aspectRatio

aspectRatio = ancho / alto. Con maintainAspectRatio:true, las dimensiones del canvas siguen esta relación. Usa una relación mayor (3-4) para tiles anchos de dashboard y menor (1-1.5) para paneles altos. Pie/doughnut usan 1 por defecto porque los círculos necesitan un canvas cuadrado para no parecer elipses.

chartjs
new Chart(ctx, {
  type: 'bar',
  data: { /* ... */ },
  options: {
    responsive: true,
    maintainAspectRatio: true,
    aspectRatio: 3    // width:height = 3:1 (wide, short chart)
  }
});
// common ratios:
//   2  -> default for bar/line
//   1  -> pie/doughnut (square)
//   3  -> wide dashboards
//   16/9 -> video-like

Función chart.resize()

Chart.js escucha automáticamente los eventos de redimensionado de la ventana cuando responsive:true, pero los cambios de layout por transiciones CSS, sidebars colapsables o cambios de pestaña pueden no disparar un resize de ventana. En esos casos, llama a chart.resize() manualmente después de que el tamaño del contenedor se haya asentado (por ejemplo, en un setTimeout o en un manejador transitionend).

chartjs
const chart = new Chart(ctx, { /* responsive: true */ });

// manually trigger a re-layout (e.g. after a sidebar collapses)
window.dispatchEvent(new Event('resize'));
// or:
chart.resize();

// explicit size:
chart.resize(600, 300);

devicePixelRatio (renderizado nítido)

devicePixelRatio escala el backing store del canvas para que las líneas se mantengan nítidas en pantallas de alta densidad/retina (por defecto usa window.devicePixelRatio, normalmente 2 o 3). Limitarlo a 2 mantiene el texto nítido mientras reduce la carga de píxeles en teléfonos 3x. Fijarlo a 1 produce una salida borrosa en retina pero maximiza la velocidad de renderizado.

chartjs
// let Chart.js use the screen's full pixel density (default):
new Chart(ctx, { options: { devicePixelRatio: window.devicePixelRatio } });

// cap DPR for performance on retina displays (fewer pixels to render):
options: { devicePixelRatio: 2 }

// ignore DPR (renders at 1x — blurry on retina but fastest):
options: { devicePixelRatio: 1 }

Patrón ResizeObserver

Un ResizeObserver sobre el contenedor del gráfico detecta los cambios de tamaño de flexbox/grid de CSS, sidebars colapsables y cambios de pestaña que el resize de ventana no capta. Desconecta el observador y llama a chart.destroy() en tu limpieza para evitar fugas. Este es el patrón responsivo más robusto para layouts complejos.

chartjs
const canvas = document.getElementById('c');
const chart = new Chart(canvas, config);

// observe the CONTAINER, not the canvas:
const ro = new ResizeObserver(() => chart.resize());
ro.observe(canvas.parentElement);

// cleanup on destroy:
function teardown() {
  ro.disconnect();
  chart.destroy();
}

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.