Skip to content

Chart.js Folha de referência

Biblioteca de gráficos JavaScript simples, porém flexível.

01

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.

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

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

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

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.

chartjs
# install
npm install chart.js

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

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

Canvas 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.

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

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

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

Tipos de grá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.

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

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

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

Tree-Shaking 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'.

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

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

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

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.

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

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

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

Gráficos de barras

Gráfico de barras básico

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.

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

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.

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

Barras agrupadas (mú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.

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

Barras 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.

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

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.

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

Barras 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.

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

Gráficos de 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.

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

Mú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.

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

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.

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

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.

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

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.

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

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.

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

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

Gráficos de 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.

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

Gráfico de 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.

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

Cutout, 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.

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

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.

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

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.

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

Callback de 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.

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

Gráficos de radar

Gráfico de radar básico

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.

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

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.

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

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.

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

Radar 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.

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

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.

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

Gráficos de área polar

Gráfico de área polar básico

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.

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

Área polar vs 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.

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

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

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

Escala polar (r)

Á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.

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

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.

chartjs
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.

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

Gráficos de 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.

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

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.

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

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

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

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).

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

Mú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.

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

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.

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

Gráficos de 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.

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

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.

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

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

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.

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

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.

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

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

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.

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

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.

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

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.

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

Mú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.

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

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.

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

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.

chartjs
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.

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

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.

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

Responsive 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.

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

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

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.

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

Visã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.

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

Layout (padding)

layout.padding 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.

chartjs
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.

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

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

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).

chartjs
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.

chartjs
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.

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

import 'chartjs-adapter-date-fns';

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

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).

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

Título 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.

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

Min/Max vs suggestedMin/Max

min/max 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.

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

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.

chartjs
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.

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

onClick 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).

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

Callback de 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.

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

Ocultar 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.

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

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

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

Tooltips

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.

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

Callback label 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.

chartjs
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.

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

Tooltip 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.

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

Modo 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.

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

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.

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

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.

chartjs
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.

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

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

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

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.

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

onComplete 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.

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

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'.

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

Eventos 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).

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

getElementsAtEventForMode

getElementsAtEventForMode 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.

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

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

onHover

options.onHover 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.

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

Hover 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.

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

Lista de eventos

events limita 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.

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

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.

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

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

Gráficos 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.

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

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).

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

Mú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.

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

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).

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

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.

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

Plugins

Plugins 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).

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

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

Plugin personalizado 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.

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

Hooks de plugin (ciclo de vida)

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.

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

Plugin: 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.

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

Plugin: texto central 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.

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

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].

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

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

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

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

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

Update 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.

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

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

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

Modos de 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.

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

Atualizando 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.

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

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

chart.destroy()

destroy() desmonta 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.

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

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

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

// destroy also removes event listeners and frees memory

chart.resize() 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.

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

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

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

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

Responsivo 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.

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

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

maintainAspectRatio

maintainAspectRatio:true (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.

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

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

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

aspectRatio

aspectRatio = 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.

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

Funçã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).

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

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

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

devicePixelRatio (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.

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

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

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

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.

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

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

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

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.