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.
<!-- 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.
# 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.
// 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 attributesTipos 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.
// 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'.
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.
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.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.
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.
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.
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.
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.
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.
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 } } }
});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.
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.
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.
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.
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.
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.
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 valueGrá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.
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.
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.
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.
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.
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.
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}%)`;
}
}
}
}
}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.
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.
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.
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.
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.
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
}
}
}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.
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.
// 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 shareEscala 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.
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.
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.
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' insteadGrá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.
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.
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).
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.
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.
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)
}]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.
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.
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.
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.
// 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.
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
}]}
});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.
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.
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.
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.
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.
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.
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)
}]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.
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.
<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.
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, radialLinearVista 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.
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.
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.
// 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 } } });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).
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.
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.
# 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).
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.
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.
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 }
}
}
}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.
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.
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).
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.
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.
// 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);
});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.
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.
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.
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.
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.
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.
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
}
}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.
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.
// 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.
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 endsonComplete 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.
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'.
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) }
}
}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).
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.
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.
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.
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.
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.
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();
}}
});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.
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).
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.
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).
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.
// 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 } }
}}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).
// 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.
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.
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.
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.
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].
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 insteadActualizar 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.
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 animationModos 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.
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) elementsActualizar 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.
// 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 datachart.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.
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 memorychart.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.
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);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.
<!-- 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.
// 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.
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-likeFunció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).
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.
// 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.
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();
}Fragmentos de Chart.js relacionados
Copy-paste ready code for common tasks.
Bar Chart
Vertical bar chart with custom colors and rounded corners.
Line Chart
Smooth line chart with fill, tension, and hover styling.
Pie Chart
Pie chart with per-slice colors and legend positioning.
Doughnut Chart
Doughnut chart with cutout control and centered title.
Radar Chart
Multi-series radar chart for comparing entities across dimensions.
Responsive Chart
Chart that fills its container with maintainAspectRatio disabled.
Options Configuration
Title, legend, axis formatting, animations, and live updates.
Tooltips
Custom-styled tooltips with title, label, and footer callbacks.
Was this helpful?