Primeiros passos
Configuração e primeiro gráfico
O Chart.js renderiza num elemento canvas. A propriedade type define o tipo de gráfico. data contém labels e datasets com valores e estilização.
<!-- 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>Instalação npm e import de ES Module
Use 'chart.js/auto' para a configuração mais simples — ele importa o Chart.js mais os controllers/elements e os registra automaticamente. Para bundles de produção menores, prefira tree-shaking: importe de 'chart.js' e registre apenas as partes que usa.
# 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 e contexto 2D
O Chart.js aceita tanto o elemento <canvas> quanto seu contexto de renderização 2d. Quando responsive é true, o canvas é redimensionado para preencher seu container, então os atributos HTML width/height servem apenas de fallback. Cada canvas pode conter exatamente uma instância 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áfico disponíveis
O Chart.js traz oito tipos de gráfico. Bar, line, scatter e bubble usam eixos cartesianos; pie, doughnut e polarArea são circulares; radar tem seu próprio eixo radial. O campo 'type' no nível superior seleciona o controller usado pelos datasets, a menos que um dataset o sobrescreva com seu próprio 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 e Register
Ao importar de 'chart.js' (não /auto), nada é registrado, então você precisa registrar controllers, elements, scales e plugins por conta própria. Essa abordagem tree-shakeable pode reduzir significativamente o tamanho do bundle. Esquecer de registrar um componente é a causa mais comum do erro '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] }] },
});Destroy e ciclo de vida
Cada instância de Chart é dona do seu canvas e dos listeners de eventos anexados. Chamar destroy() desmonta tudo para que o canvas possa ser reutilizado — essencial em SPAs e efeitos React/Vue. Criar um segundo gráfico num canvas ativo vaza memória e produz gráficos renderizados duas vezes.
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
Um gráfico de barras mapeia cada label a uma barra cuja altura equivale ao valor dos dados. backgroundColor define o preenchimento da barra, borderColor/borderWidth o contorno. Defina y.beginAtZero para que as barras sempre partam do zero — sem isso, o Chart.js pode autoescalar o mínimo do eixo e distorcer visualmente as diferenças.
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 } } }
});Barra horizontal (indexAxis)
No Chart.js v3+, barras horizontais são criadas com indexAxis: 'y' num tipo 'bar' — o antigo tipo 'horizontalBar' foi removido. A escala x vira o eixo de valores. Barras horizontais são ideais para labels de categoria longos que se sobreporiam num 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últiplos datasets)
Múltiplos datasets num gráfico de barras são colocados lado a lado (agrupados) por padrão. O Chart.js só atribui cores automaticamente se você omitir backgroundColor, então defina cores explícitas por dataset para uma saída previsível. Cada dataset compartilha o mesmo array labels no eixo 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 empilhadas
Barras empilhadas exigem stacked: true no eixo x E no y. As barras de cada dataset são desenhadas sobre a anterior, somando a um total. Empilhar mostra composição, mas torna as séries superiores mais difíceis de comparar entre categorias do que 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 }
}
}
});Estilização de barras
borderRadius arredonda os cantos da barra (um número único aplica aos cantos; um objeto como {topLeft:8} mira cantos específicos). borderSkipped assume 'start' por padrão, que omite uma borda — defina false para desenhar as quatro. barPercentage e categoryPercentage juntos controlam a espessura e o espaçamento das 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 flutuantes ([min, max])
Passar pares [min, max] como valores de dados produz barras flutuantes que não partem do zero — perfeito para faixas como mínima-máxima diária de temperatura, abertura-fechamento ou intervalos de confiança. O eixo y NÃO deve começar do zero para barras de faixa. Também funciona em barras horizontais.
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 linha
Gráfico de linha básico
Um gráfico de linha conecta pontos de dados em ordem. borderColor é a cor da linha; backgroundColor é usado para o preenchimento (se fill estiver habilitado). tension (0-1) controla a suavidade da curva — 0 são segmentos retos, ~0.3-0.4 dá curvas bezier suaves. Use 0 para dados precisos como preços financeiros.
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últiplas linhas
Cada dataset num gráfico de linha vira sua própria linha, com cor atribuída automaticamente da paleta padrão (sobrescritável com borderColor). As linhas são desenhadas na ordem dos datasets, então o último dataset renderiza por cima. Passe um label a cada dataset para que a legenda possa identificá-los.
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' } }
}
});Tension e interpolação da linha
tension adiciona suavização bezier, mas pode ultrapassar os pontos de dados (criando vales abaixo do mínimo). cubicInterpolationMode: 'monotone' suaviza sem ultrapassar — preferido para dados monotônicos como preços de ações. borderDash é um padrão [dash, gap] para linhas tracejadas/pontilhadas.
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'
}]Linhas preenchidas (fill)
fill controla a área sob a linha. true/'origin' preenche até o eixo x. Um número (1, -1, +1) preenche em direção a outro dataset por índice, útil para gráficos de banda. Um número negativo preenche em direção ao dataset anterior. Defina backgroundColor com alpha para que a linha continue visível através do preenchimento.
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:...}Estilização de pontos
Propriedades de ponto aceitam um valor único ou um array (um por ponto de dados). pointStyle suporta várias formas ('circle', 'rect', 'rectRot', 'triangle', 'star', 'cross', 'crossRot'). Defina pointRadius: 0 para ocultar os pontos completamente (útil em gráficos de linha densos) e pointHoverRadius maior para um efeito pop interativo.
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],
}]SpanGaps e dados ausentes
null, undefined e NaN representam dados ausentes e quebram a linha por padrão. spanGaps: true conecta os pontos dos dois lados da lacuna com um único segmento. Distinga NaN (ausente) de 0 (um zero real) — confundi-los é fonte comum de gráficos enganosos.
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 pizza e rosca
Gráfico de pizza básico
Um gráfico de pizza mostra partes de um total: cada valor vira uma fatia cujo ângulo é proporcional à sua participação. Forneça um backgroundColor por fatia (um array), senão o Chart.js cicla uma paleta padrão. Gráficos de pizza funcionam melhor com 3-6 categorias — mais que isso fica ilegível.
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 rosca básico
Uma rosca é uma pizza com um buraco no meio. A propriedade cutout (string de porcentagem ou número de pixels) controla o tamanho do buraco — '50%' é o visual clássico de donut. O buraco central pode exibir um rótulo resumo via plugin, e o comprimento do anel codifica o valor um pouco melhor que o ângulo da fatia.
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, rotation e circumference
rotation define o ângulo inicial em graus (padrão 0 = direita; -90 = topo). circumference controla quanto do círculo é desenhado — 180 faz uma meia-rosca, útil para gráficos estilo gauge. Ambos ficam em options (não no dataset) na v3+, embora cutout possa aparecer em qualquer um.
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
}
});Border e offset
borderColor com borderWidth separa visualmente as fatias (bordas brancas dão um visual segmentado limpo). hoverOffset empurra uma fatia para fora quando o usuário passa o mouse, dando feedback interativo claro. offset é um array (um por fatia) para 'explodir' permanentemente fatias específicas em destaque.
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
}]Meia-rosca (gauge)
Uma meia-rosca (rotation: -90, circumference: 180) é lida como um medidor gauge/progresso. Pareie com um plugin de texto central para mostrar a porcentagem, e desabilite a legenda para um visual de KPI limpo. A fatia 'restante' num cinza neutro transmite a parte não concluída.
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 porcentagem no tooltip
Tooltips de pizza/rosca mostram valores brutos por padrão. Use o callbacks.label do tooltip para calcular e exibir porcentagens em vez disso — ctx.parsed é o valor da fatia e ctx.dataset.data guarda os valores para a soma. Template literals em callbacks precisam escapar backticks e ${} quando embutidos na string de código deste 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
Um gráfico de radar traça cada label como um vértice num polígono, conectando-os numa forma fechada. fill: true sombreia o interior. A escala radial é configurada em scales.r (não x/y). Radars comparam perfis multivariados, mas podem enganar com eixos demais ou unidades não comparáveis.
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 } } }
});Estilização do radar
Datasets de radar aceitam a mesma estilização dos gráficos de linha: borderColor, fill, estilos de ponto, tension. Uma tension pequena (0.1) arredonda levemente os vértices para um visual mais suave; 0 mantém pontas retas. Use backgroundColor translúcido para que formas de radar sobrepostas continuem visíveis.
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
}]Configurações da escala radial (r)
A escala radial r controla anéis e rótulos. min/max fixam a faixa de valores nos eixos (essencial ao comparar datasets). ticks.stepSize define o espaçamento dos anéis; pointLabels estiliza os nomes das categorias ao redor do perímetro. Defina ticks.backdropColor transparente para que os números dos anéis não ofusquem as linhas do grid.
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 com múltiplos datasets
Múltiplos datasets se sobrepõem como polígonos concêntricos, ideal para comparações antes/depois ou entre concorrentes. Sempre defina o mesmo min/max em r para que as formas sejam comparáveis, e use preenchimentos translúcidos para que ambos os perfis continuem visíveis onde se sobrepõem.
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 }
]
}
});Linhas de ângulo e grid do radar
angleLines são os raios do centro a cada vértice; grid são os anéis poligonais concêntricos. Ocultar ticks (display:false) remove os rótulos numéricos dos anéis para uma estética mais limpa, mantendo os anéis em si. pointLabels controla apenas o texto de categoria em 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
Um gráfico de área polar desenha cada valor como um setor abrangendo o mesmo ângulo (360/N cada), com o raio codificando o valor. Diferente da pizza (onde ângulo = valor), aqui o raio = valor, então todas as fatias têm largura angular igual, mas comprimentos diferentes.
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 pizza
A diferença-chave: na pizza, o ÂNGULO de cada fatia é proporcional ao seu valor; na área polar, o RAIO de cada fatia é proporcional ao seu valor, enquanto os ângulos são iguais. Use área polar quando quiser que todas as categorias fiquem igualmente visíveis, mas dimensionadas pela magnitude.
// 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)
Área polar usa uma única escala radial r compartilhada pelos setores — então os valores são medidos contra o mesmo raio máximo. Definir um max explícito torna o gráfico honesto quanto à escala; sem isso o Chart.js autoescala para o maior valor, o que pode exagerar pequenas diferenç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)' }
}
}
}Estilização de borda polar
Setores de área polar aceitam a mesma estilização de borda/preenchimento que pizza/rosca. Bordas brancas separam claramente setores adjacentes. hoverBackgroundColor muda o preenchimento de um setor ao passar o mouse para feedback interativo. Diferente da rosca, não há cutout — os setores se encontram no centro.
datasets: [{
data: [11, 16, 7, 14],
backgroundColor: ['#FF6384', '#4BC0C0', '#FFCE56', '#36A2EB'],
borderColor: 'white',
borderWidth: 2,
hoverBackgroundColor: '#333'
}]Área polar com hover offset
Área polar suporta hoverBackgroundColor e hoverBorderColor, mas NÃO suporta hoverOffset / offset como a rosca, porque os setores compartilham uma escala radial. Se 'estourar' uma fatia é essencial, escolha rosca. Use mudanças de cor e tooltip para a interatividade 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 bolhas
Gráfico de bolhas básico
Os pontos de dados do gráfico de bolhas são objetos {x, y, r}, onde x e y são coordenadas e r é o RAIO da bolha em pixels. Diferente do scatter, o tamanho da bolha codifica uma terceira variável. Note que r é um raio (não área), então um valor 2x maior é visualmente 4x a área — considere escalar seus dados de tamanho com sqrt.
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 } } }
});Mapeamento de tamanho de bolha
Como humanos percebem a ÁREA da bolha e não o raio, mapeie seu valor através de Math.sqrt antes de atribuir r, para que dobrar o valor dobre a área visível. Escolha um divisor que impeça a maior bolha de sobrepor muitos vizinhos. Isso torna o gráfico 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 }] } });Cores por ponto nas bolhas
Como outros datasets do Chart.js, as propriedades de estilização de bolhas aceitam arrays para estilizar cada bolha individualmente. Use isso para codificar bolhas por categoria por cor enquanto o tamanho codifica um valor numérico separado, dando um gráfico de 4 dimensões (x, y, tamanho, cor).
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últiplos datasets de bolhas
Múltiplos datasets renderizam como grupos de bolhas de cores diferentes, cada um na legenda. Mantenha os raios das bolhas modestos ao sobrepor grupos para que as bolhas não se ocultem totalmente. Preenchimentos alfa transparentes (0.5-0.6) ajudam bolhas sobrepostas a permanecerem legíveis.
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)' }
]
}
});Estilização de hover nas bolhas
Propriedades de hover (hoverBackgroundColor, hoverBorderColor, hoverBorderWidth, hoverRadius) aplicam-se apenas à bolha sob o ponteiro. hoverRadius adiciona pixels extras ao raio no hover, fazendo a bolha alvo visivelmente se destacar. Combinado com tooltips, dá um foco interativo 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 dispersão
Gráfico de dispersão básico
Os pontos de dados do scatter são objetos {x, y} (sem raio necessário). A escala x deve ser type: 'linear' (NÃO category) para que valores numéricos de x mapeiem para posições reais. Scatter é o gráfico padrão para mostrar correlação entre duas variáveis contínuas.
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' } } }
});Dispersão com muitos pontos
Para milhares de pontos, reduza o pointRadius (1-2px) e use um backgroundColor semitransparente (alpha 0.2-0.4) para que pontos sobrepostos revelem densidade através de regiões mais escuras. Desabilite o hover de pontos em datasets muito grandes (pointHitRadius: 0) para manter a interação responsiva.
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)' }] }
});Estilização de pontos do scatter
pointStyle suporta muitas formas além do círculo padrão: 'rect', 'rectRot', 'triangle', 'star', 'cross', 'crossRot', 'dash'. pointRotation rotaciona formas não circulares. Todas as propriedades point* aceitam arrays para estilização por ponto — útil para destacar observações específicas.
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)
}]Dispersão com linha de tendência
O Chart.js não tem linha de tendência embutida, então calcule uma regressão (mínimos quadrados aqui) e adicione um dataset 'line' com dois endpoints e pointRadius:0. O type do dataset de linha sobrescreve o tipo do gráfico por dataset — é assim que gráficos mistos funcionam. fill:false o mantém como só uma linha.
// 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 }
]}
});Dispersão para linha (showLine)
showLine: true num dataset scatter conecta os pontos com uma linha, efetivamente transformando o scatter num gráfico de linha que usa coordenadas x numéricas. É a escolha certa quando os valores de x são números reais (não labels de categoria) mas você ainda quer segmentos conectando — por exemplo, séries temporais com espaçamento 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
}]}
});Dados — Datasets
Estrutura de datasets
data guarda labels (compartilhados pelos datasets) e datasets (um array de séries). Cada dataset tem um label (mostrado em legenda/tooltips), um array data alinhado com labels e propriedades de estilização. Propriedades definidas no dataset aplicam aos pontos, a menos que sejam sobrescritas por um array.
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
}
]
}Alinhamento de labels e data
O array data de cada dataset está alinhado por posição com o array labels compartilhado — data[i] é o valor para labels[i]. Um array data mais curto produz valores undefined na cauda ausente, que gráficos de linha tratam como lacunas. Mantenha labels e data sempre do mesmo comprimento para evitar lacunas surpreendentes.
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últiplos datasets
Múltiplos datasets renderizam como séries paralelas (barras agrupadas, várias linhas, radars sobrepostos). Compartilham um único array labels. Defina cores distintas por dataset — o Chart.js só colorifica automaticamente quando backgroundColor é omitido, e mesmo assim cores explícitas são mais previsíveis entre versões.
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)' }
]
}Estilização no nível do dataset
Estilo no nível do dataset aplica-se a cada ponto daquele dataset. Variantes hover* ativam no hover. hidden:true inicia o dataset oculto (o toggle da legenda pode mostrá-lo de novo). order controla a ordem z — números menores desenham depois (por cima) — útil em gráficos mistos/sobrepostos.
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
}]Parseando dados de objetos
Quando seus dados são um array de objetos, diga ao Chart.js quais campos guardam os valores dos eixos via parsing: {xAxisKey, yAxisKey}. Isso evita mapeamento manual para pares {x, y}. As chaves assumem 'x' e 'y' por padrão, então objetos {x, y} funcionam sem configuração 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 estilização por ponto
Qualquer propriedade de estilização pode ser um valor único (aplica aos pontos) ou um array (um por ponto). Isso permite destacar pontos específicos — por exemplo, defina a maioria dos backgroundColor como cinza e um como vermelho para chamar atenção. O comprimento do array deve casar com o dos dados; arrays menores ciclam.
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)
}]Options — Responsivo e escalas
Estrutura de options
options é o objeto de configuração de nível superior. Agrupa as preocupações: plugins (legend/title/tooltip), scales (x/y/r), layout (padding), animation, interaction (modo de hover) e events. quase qualquer comportamento do Chart.js é ajustado aqui, não nos datasets individuais.
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 e maintainAspectRatio
responsive:true faz o gráfico preencher a largura do container e re-renderizar ao redimensionar. maintainAspectRatio:false libera a altura para que a altura CSS do container seja respeitada — defina ambos e envolva o canvas numa <div> dimensionada. Com maintainAspectRatio:true (padrão), o gráfico mantém uma proporção fixa de largura/altura.
<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>Visão geral das escalas
scales configura cada eixo. O id (x, y, r) é a chave da escala; type seleciona a classe da escala. Tipos comuns: 'category' (labels de texto), 'linear' (números), 'logarithmic', 'time' (exige um adaptador de datas), 'radialLinear' (radar/polar). title.display + text adicionam um rótulo ao eixo.
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, radialLinearVisão geral dos plugins
plugins agrupa os plugins embutidos title, legend e tooltip, além das opções de plugins personalizados registrados, pelo id deles. title adiciona um título acima do canvas. legend controla a chave dos datasets. tooltip controla os popups de hover. Plugins personalizados leem suas opções deste mesmo 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 adiciona espaço dentro do canvas entre a área do gráfico e a borda do canvas — útil quando títulos, rótulos de eixo ou tooltips grandes seriam cortados. Um número único preenche os lados igualmente; a 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 }Defaults globais (Chart.defaults)
Chart.defaults guarda a configuração padrão global — defina valores uma vez no startup da app e cada gráfico os herda. É o lugar certo para branding (font family, cor base, animação padrão). Opções por gráfico sempre sobrescrevem os defaults, então você ainda pode personalizar gráficos individuais.
// 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 } } });Eixos — X e Y
Eixo linear
Um eixo linear mapeia números proporcionalmente. beginAtZero força o eixo a começar em 0 (recomendado para gráficos de barras). min/max definem limites rígidos; suggestedMin/suggestedMax são dicas suaves que o Chart.js pode expandir para caber os ticks. ticks.callback personaliza o texto do rótulo (por exemplo, anexar uma unidade).
options: {
scales: {
y: {
type: 'linear',
beginAtZero: true,
min: 0, max: 100, // hard limits
ticks: { stepSize: 10, callback: (v) => v + '%' }
}
}
}Eixo de categoria
Um eixo de categoria mostra labels de texto em posições fixas. É o eixo x padrão para gráficos de barras/linha. ticks.autoSkip:false força os labels a aparecer (caso contrário o Chart.js descarta os sobrepostos). maxRotation inclina os labels para evitar sobreposição quando há muitas categorias.
options: {
scales: {
x: {
type: 'category',
labels: ['Mon','Tue','Wed'], // optional; usually from data.labels
ticks: { autoSkip: false, maxRotation: 45, minRotation: 0 }
}
}
}Eixo temporal
Um eixo temporal traça objetos Date ou strings ISO proporcionalmente ao tempo, com lacunas onde não há dados. Exige um pacote adaptador de datas (chartjs-adapter-date-fns, -luxon, -dayjs). time.unit fixa a granularidade dos ticks ('day','month','year'); sem isso o Chart.js escolhe uma unidade automaticamente.
# 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' } } } }
});Eixo logarítmico
Um eixo logarítmico espaça os ticks em potências de 10, essencial para dados que atravessam ordens de magnitude (população, preços, frequências). Não pode exibir 0 nem valores negativos. ticks.callback permite formatar compactamente os rótulos de potências de dez (por exemplo, notação 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 do eixo e callback de ticks
title.display + title.text adicionam um rótulo ao eixo (desligado por padrão — defina display:true). ticks.callback recebe cada valor de tick e retorna a string de exibição, permitindo formatar números como moeda, porcentagens, abreviações k/M ou qualquer texto personalizado sem alterar os dados subjacentes.
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 são limites RÍGIDOS: o eixo permanece dentro deles mesmo que os dados excedam a faixa (dados são cortados). suggestedMin/suggestedMax são dicas SUAVES: o Chart.js os usa como base, mas pode expandir para produzir valores de tick redondos. Prefira suggested* quando quiser números redondos bonitos; use min/max rígidos para escalas fixas como porcentagens.
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 }
}
}
}Legenda
Básico da legenda
A legenda lista o label de cada dataset com uma amostra de cor. display:true mostra (padrão), display:false oculta. position aceita 'top', 'bottom', 'left', 'right' ou 'center' (chartArea). Clicar num item da legenda alterna a visibilidade daquele dataset por padrão — uma interação de filtragem embutida.
new Chart(ctx, {
type: 'bar',
data: { labels: ['A','B'], datasets: [{ label: 'Sales', data: [10,20] }] },
options: {
plugins: {
legend: { display: true, position: 'top' }
}
}
});Posição e alinhamento da legenda
position define o lado da legenda; align controla seu posicionamento ao longo desse lado ('start'/'center'/'end'). labels configura a amostra (boxWidth/boxHeight) e a estilização do texto. maxWidth limita a área da legenda para que legendas muito longas quebrem linha em vez de empurrar o gráfico para o 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 da legenda (toggle personalizado)
Sobrescreva legend.onClick para personalizar o comportamento do clique. O padrão alterna a visibilidade do dataset. A assinatura é (event, legendItem, legend). Chamar chart.update() depois de mudar o estado re-renderiza. Use isso para confirmar antes de ocultar, sincronizar com UI externa ou implementar comportamento de seleção ú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 labels da legenda
generateLabels retorna um array de objetos de label que controla totalmente o que aparece na legenda. O texto de cada item, as cores da amostra e o estado hidden podem ser personalizados — útil para adicionar contagens, unidades ou derivar uma legenda de dados que não são datasets. O flag hidden e o datasetIndex ligam os cliques de volta ao dataset certo.
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 legenda e legenda externa
Para controle total do estilo, desabilite a legenda embutida (display:false) e renderize sua própria legenda em HTML. Itere chart.data.datasets, renderize botões/amostras e alterne dataset.hidden + chart.update() ao clicar. Comum quando se quer casar com um design system em que a legenda padrão em canvas não se encaixa.
// 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
Básico do tooltip
Tooltips aparecem no hover mostrando o label do dataset e o valor. enabled:true por padrão. Propriedades de estilização (backgroundColor, titleColor, bodyColor, padding, cornerRadius) controlam a aparência. displayColors alterna as pequenas amostras de cor ao lado de cada item — útil quando muitos datasets se sobrepõem.
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 do tooltip
callbacks.label retorna o texto para cada linha do tooltip. ctx.dataset.label é o nome da série, ctx.parsed.y guarda o valor (use ctx.parsed para pizza/radar). Formate moeda, anexe unidades ou calcule totais aqui. A string retornada (ou array de strings) vira o corpo do tooltip.
plugins: {
tooltip: {
callbacks: {
label: (ctx) => {
const label = ctx.dataset.label || '';
const value = ctx.parsed.y ?? ctx.parsed;
return `${label}: $${value}`;
}
}
}
}Callback title do tooltip
callbacks.title controla o cabeçalho do tooltip (padrão: o label do eixo x). A função recebe um array de itens do tooltip (útil quando mode:'index' agrupa vários datasets). Retornar uma string vazia '' suprime o título por completo. Combine callbacks de title e label para conteúdo 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 externo em HTML
external permite renderizar o tooltip como HTML real — para estilização rica, imagens ou links impossíveis no canvas. Defina enabled:false para que o tooltip padrão não renderize duas vezes. O callback recebe um contexto com um objeto tooltip contendo caretX/caretY (posição) e as linhas do corpo. Posicione o elemento HTML nessas 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 do tooltip (interaction)
interaction.mode controla o alvo do tooltip. 'point' mostra só o ponto sob o cursor; 'index' mostra os datasets no mesmo x (ótimo para barras/linhas agrupadas); 'nearest' encontra o ponto único mais próximo. intersect:false dispara o tooltip quando o ponteiro está em qualquer lugar da coluna, não só sobre um ponto — geralmente o que os usuários esperam.
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 } }
}Estilização e filtros do tooltip
filter pula linhas do tooltip que não atendem a uma condição (por exemplo, ocultar valores zero/vazios). callbacks.footer adiciona uma linha de resumo após os itens — perfeito para exibir um total. bodyFont/titleFont estilizam o texto; caretSize e caretPadding controlam a pequena seta indicadora.
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
}
}Animação
Duração da animação
animation.duration define o comprimento total da animação em milissegundos (padrão 1000). easing controla a curva de aceleração — 'easeOutQuart' (o padrão) começa rápido e desacelera, o que parece responsivo. Encurte a duração (200-400ms) para dashboards de dados que atualizam com frequência.
options: {
animation: {
duration: 1000, // total duration in ms
easing: 'easeOutQuart'
}
}
// easing options: 'linear','easeInQuad','easeOutQuad','easeInOutQuad',
// 'easeInCubic','easeOutCubic','easeInOutCubic','easeOutBounce',...Desabilitando a animação
Defina animation:false para desligar todas as animações por completo — melhor para dashboards críticos de desempenho ou ao alimentar atualizações rápidas. animation:{duration:0} mantém o sistema de animação ativo, mas instantâneo (o hover continua funcionando). O objeto animations (plural) permite desabilitar propriedades específicas como y enquanto anima outras.
// 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 }
}
}Funções de easing
Easing muda como uma animação progride ao longo do tempo, afetando drasticamente a sensação. 'easeOutQuart' (padrão) parece profissional e responsivo. 'easeOutBounce' ou 'easeInOutBack' são divertidos, mas podem parecer artificiais em gráficos de dados. Combine o easing com a linguagem de movimento geral da sua 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 da animação
onComplete dispara quando uma animação termina — útil para encadear ações como habilitar um botão de exportar ou disparar uma renderização seguinte. onProgress dispara a cada frame de animação com a contagem de passos. Evite trabalho pesado no onProgress, pois roda 60 vezes 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
}
}
}Animação por propriedade (animations)
O objeto animations (plural) configura propriedades individuais de forma independente. Cada entrada pode especificar from/to (ou uma função do contexto de parsing), duration, easing e loop. Animar tension de 1 para 0.3 produz um efeito de 'linha se acomodando'; animar y a partir da base do eixo produz um efeito de 'crescer para cima'.
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 e cliques
Handler onClick
options.onClick dispara quando o usuário clica em qualquer lugar do gráfico. O argumento elements é um array dos elementos do gráfico clicados (barras/pontos), cada um com .datasetIndex e .index. Se elements estiver vazio, o clique acertou o canvas em branco. Essa é a forma padrão de tornar gráficos interativos (drill-down, seleção).
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 encontra os elementos do gráfico sob um evento nativo de mouse, com as mesmas opções de modo da interaction ('nearest', 'index', 'x', etc.). O 4º argumento useFinalPosition deve ser true para hit-testing das posições finais renderizadas. Use quando precisar de busca de elementos fora do 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 dispara a cada movimento do mouse sobre o gráfico. Use para feedback de UI barato, como mudar o cursor (como mostrado) ou destacar elementos externos relacionados. Evite operações caras aqui — dispara com muita frequência. Para lógica mais pesada, use onClick ou faça debounce do handler.
options: {
onHover(event, elements, chart) {
// change cursor to a pointer when hovering a bar
event.native.target.style.cursor =
elements.length ? 'pointer' : 'default';
}
}Hover e elementos ativos
A configuração hover controla como o gráfico destaca elementos sob o ponteiro. mode:'nearest' + intersect:true destaca o ponto único mais próximo. animationDuration suaviza a transição do destaque. chart.setActiveElements dispara programaticamente o estado de hover — útil para sincronizar destaques do gráfico com 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 quais eventos DOM o gráfico escuta. Reduzir a lista (por exemplo, só 'click') desabilita efeitos de hover para uma sensação estática e melhora o desempenho em dashboards. Para contextos mobile só de toque, inclua touchstart/touchmove. Um array vazio desabilita toda interação.
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+)Exemplo de drill-down
Um padrão comum: clicar numa barra troca o dataset por uma visão mais detalhada (drill-down). Capture o índice clicado, substitua chart.data.labels e chart.data.datasets[...].data, e depois chame chart.update() para animar a transição. Mantenha uma pilha de visões se quiser um botão voltar.
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 mistos
Gráfico misto barra + linha
Misture tipos de gráfico definindo type em datasets individuais — sobrescreve o tipo do gráfico para aquela série. A combinação barra + linha é a mistura mais comum (por exemplo, receita em barras, taxa de crescimento em linha). Use um segundo eixo y (y1) quando as séries tiverem unidades ou escalas diferentes.
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 } } } }
});Sobrescrita de type do dataset
Qualquer dataset pode sobrescrever o tipo do gráfico, permitindo combinar bar, line e scatter num único gráfico. Datasets sem type explícito herdam o tipo do gráfico. Cuidado com a ordem z: os datasets são desenhados na ordem do array, então coloque séries de fundo (barras) antes das de frente (linhas).
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últiplos eixos Y (y, y1, y2)
Defina múltiplos eixos y com ids personalizados (y, y1, y2) e atribua datasets via yAxisID. grid.drawOnChartArea:false impede o segundo eixo de desenhar linhas de grid sobre o primeiro. position:'right' empilha à direita; adicione offset:true a um terceiro eixo para não sobrepor o segundo. Colore cada eixo para casar com sua série.
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'Dados mistos de formas diferentes
Gráficos mistos podem combinar uma série de valores (barras) com linhas de referência (alvo constante, tendência). Defina pointRadius:0 e fill:false nos datasets de linha para que renderizem como linhas puras, sem marcadores nem preenchimentos. Esse padrão é comum em dashboards de desempenho (real vs alvo).
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 }
]
}
});Dicas de estilização mista
Em gráficos mistos, defina dataset.order para que a linha desenhe acima das barras (order menor = por cima). Codifique por cor os ticks e o título de cada eixo para casar com sua série, para que leitores saibam qual escala pertence a qual linha. Desabilite o grid do segundo eixo (drawOnChartArea:false) para evitar linhas de grid duplicadas.
// 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 embutidos
O Chart.js traz três plugins embutidos: Title (título do gráfico acima do canvas), Legend (a chave dos datasets) e Tooltip (popups de hover). São configurados em options.plugins pelo id e habilitados por padrão (exceto Title, que precisa de display:true para mostrar seu 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 inline
Passe um array de objetos de plugin a um único gráfico via a opção plugins. Cada plugin tem um id e funções de hook (beforeInit, afterInit, beforeDraw, afterDraw, beforeUpdate, etc.). Plugins inline aplicam-se só àquela instância de gráfico. ctx.save()/restore() delimitam qualquer mudança de estado do canvas que você fizer.
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)
Hooks de plugin rodam em cada estágio do ciclo de vida do gráfico: init, update, render, draw, resize, destroy. Hooks before* podem cancelar uma ação retornando false. Os mais comuns para desenho personalizado são afterDraw (desenha por cima do gráfico) ou beforeDraw (desenha atrás dos dados). Cada hook recebe a instância do 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: linha vertical no índice
Um plugin personalizado comum desenha uma linha guia vertical na posição do tooltip (como um crosshair padrão). afterDraw lê a coordenada x do elemento de tooltip ativo e traça uma linha tracejada do topo à base da área do gráfico. Envolva o estado do canvas em save()/restore() para que o estilo da linha tracejada não vaze.
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 na rosca
Desenhar texto de resumo centralizado é o caso de uso clássico de um plugin de rosca. afterDatasetsDraw roda depois das fatias para que o texto fique por cima. Calcule o total (ou qualquer resumo) e renderize no centro geométrico do chartArea. Isso transforma uma rosca num widget de 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] });Registrando plugin globalmente
Chart.register(plugin) faz um plugin aplicar a cada gráfico criado depois — ideal para plugins em toda a app como marcas d'água, branding ou analytics. Para um gráfico pontual, use o array inline plugins. Chart.unregister remove. Plugins registrados leem sua configuração 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 insteadUpdate e destroy
chart.update()
Depois de mutar chart.data ou chart.options, chame chart.update() para re-renderizar. Por padrão, a mudança anima do estado anterior. Passe 'none' como mode para pular a animação (útil para atualizações de alta frequência). Mutar e depois atualizar é bem mais barato que destruir e recriar o 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 update
update(mode) aceita uma string de modo que controla o comportamento. 'none' desabilita a animação para um refresh silencioso. 'reset' rebobina para os valores pré-animação e reanima (bom para reproduzir a entrada). 'active' atualiza apenas os elementos em hover para re-renderizações baratas de hover. O padrão (sem argumento) anima normalmente.
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) elementsAtualizando dados e labels
Você pode substituir data/labels por completo ou mutá-los no lugar (push/shift). Para gráficos de streaming ao vivo (por exemplo, uma janela de 60 segundos), anexe o novo valor e desloque o mais antigo, e depois update('none') para um refresh suave sem animação — chamar o update animado padrão a cada tick causa uma lag irregular.
// 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 o gráfico: remove listeners de eventos, cancela animações, limpa o canvas e libera memória. Sempre chame destroy quando o container de um gráfico for removido (limpeza do useEffect no React, mudança de rota). Não destruir vaza memória e pode lançar erros 'Canvas is already in use' ao reutilizar um 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() e clear()
chart.resize() recalcula o tamanho do gráfico — com responsive:true isso acontece automaticamente ao redimensionar a janela, então chamadas manuais são raras. chart.clear() limpa o canvas sem destruir o gráfico (o próximo update redesenha). chart.resize(width, height) força dimensões específicas em pixels, sobrescrevendo o dimensionamento 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 e device pixel ratio
Container responsivo
Para um gráfico responsivo, envolva o canvas num container posicionado com width/height explícitos e defina responsive:true + maintainAspectRatio:false. O canvas preenche o container e re-renderiza ao redimensionar a janela. Sem maintainAspectRatio:false, o gráfico mantém uma proporção fixa e ignora a altura do container.
<!-- 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 (padrão) mantém o canvas numa proporção fixa de largura/altura definida por aspectRatio (padrão 2 = 2:1). maintainAspectRatio:false libera a altura para o container. Pie/doughnut assumem aspectRatio:1 (quadrado) por padrão, já que círculos parecem errados num retângulo largo.
// 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 = largura / altura. Com maintainAspectRatio:true, as dimensões do canvas seguem essa proporção. Use uma proporção maior (3-4) para tiles largos de dashboard, menor (1-1.5) para painéis altos. Pie/doughnut assumem 1 por padrão porque círculos precisam de um canvas quadrado para não parecerem 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-likeFunção chart.resize()
O Chart.js escuta eventos de resize da janela automaticamente quando responsive:true, mas mudanças de layout de transições CSS, sidebars colapsáveis ou troca de abas podem não disparar um resize da janela. Nesses casos, chame chart.resize() manualmente depois que o tamanho do container se estabilizar (por exemplo, num setTimeout ou handler de 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 (renderização nítida)
devicePixelRatio escala o backing store do canvas para que as linhas continuem nítidas em telas high-DPI/retina (o padrão usa window.devicePixelRatio, geralmente 2 ou 3). Limitar a 2 mantém o texto nítido enquanto reduz a carga de pixels em celulares 3x. Definir 1 produz saída borrada em retina, mas maximiza a velocidade de renderização.
// 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 }Padrão ResizeObserver
Um ResizeObserver no container do gráfico captura mudanças de tamanho vindas de CSS flexbox/grid, sidebars colapsáveis e troca de abas que o resize da janela não pega. Desconecte o observer e chame chart.destroy() na sua limpeza para evitar vazamentos. É o padrão responsivo mais robusto para layouts complexos.
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();
}Snippets 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?