Démarrage
Installation et premier graphique
Chart.js se rend sur un élément canvas. La propriété type définit le type de graphique. data contient les labels et les datasets avec valeurs et styles.
<!-- 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>Installation npm et import ES Module
Utilisez 'chart.js/auto' pour la configuration la plus simple — il importe Chart.js avec tous les contrôleurs/éléments et les enregistre automatiquement. Pour des bundles de production plus légers, préférez le tree-shaking : importez depuis 'chart.js' et n'enregistrez que les morceaux utilisés.
# 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 et contexte 2D
Chart.js accepte l'élément <canvas> ou son contexte de rendu 2d. Quand responsive est true, le canvas est redimensionné pour remplir son conteneur, les attributs HTML width/height ne sont donc que des solutions de repli. Chaque canvas ne peut contenir qu'une seule instance 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 attributesTypes de graphiques disponibles
Chart.js livre huit types de graphiques. Bar, line, scatter et bubble utilisent des axes cartésiens ; pie, doughnut et polarArea sont circulaires ; radar a son propre axe radial. Le champ 'type' au niveau racine sélectionne le contrôleur utilisé pour tous les datasets, sauf si un dataset le remplace par son propre 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 et registre
En important depuis 'chart.js' (pas /auto), rien n'est enregistré : vous devez enregistrer vous-même les contrôleurs, éléments, échelles et plugins. Cette approche tree-shakeable peut réduire fortement la taille du bundle. Oublier d'enregistrer un composant est la cause la plus courante de l'erreur '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] }] },
});Destruction et cycle de vie
Chaque instance de Chart possède son canvas et ses écouteurs d'événements attachés. Appeler destroy() démonte tout, le canvas pouvant être réutilisé — essentiel dans les SPA et les effets React/Vue. Créer un second graphique sur un canvas actif fuit la mémoire et produit des graphiques doublement rendus.
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.Graphiques en barres
Graphique en barres de base
Un graphique en barres associe chaque label à une barre dont la hauteur égale la valeur. backgroundColor définit le remplissage, borderColor/borderWidth le contour. Réglez y.beginAtZero pour que les barres partent toujours de zéro — sans cela, Chart.js peut auto-ajuster le minimum de l'axe et déformer visuellement les écarts.
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 } } }
});Barres horizontales (indexAxis)
Dans Chart.js v3+, les barres horizontales se créent avec indexAxis: 'y' sur un type 'bar' — l'ancien type 'horizontalBar' a été retiré. L'échelle x devient l'axe des valeurs. Les barres horizontales sont idéales pour les labels de catégories longs qui se chevaucheraient en 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 } }
}
});Barres groupées (plusieurs datasets)
Plusieurs datasets dans un graphique en barres sont placés côte à côte (groupés) par défaut. Chart.js n'attribue des couleurs automatiquement que si vous omettez backgroundColor : définissez donc des couleurs explicites par dataset pour un résultat prévisible. Chaque dataset partage le même tableau labels sur l'axe 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 } } }
});Barres empilées
Les barres empilées exigent stacked: true sur LES DEUX échelles x et y. Les barres de chaque dataset se dessinent au-dessus des précédentes, en sommant vers un total. L'empilement montre la composition, mais rend les séries supérieures plus difficiles à comparer entre catégories que les barres groupées.
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 }
}
}
});Style des barres
borderRadius arrondit les coins des barres (un nombre s'applique à tous les coins ; un objet comme {topLeft:8} vise des coins précis). borderSkipped vaut 'start' par défaut et omet une bordure — mettez false pour tracer les quatre. barPercentage et categoryPercentage contrôlent ensemble épaisseur et espacement des barres.
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
}]
}
});Barres flottantes ([min, max])
Passer des paires [min, max] comme valeurs produit des barres flottantes qui ne partent pas de zéro — parfait pour des plages comme température mini-maxi du jour, ouverture-clôture ou intervalles de confiance. L'axe y ne doit PAS commencer à zéro pour des barres de plages. Fonctionne aussi sur les barres horizontales.
new Chart(ctx, {
type: 'bar',
data: {
labels: ['Mon', 'Tue', 'Wed'],
datasets: [{
label: 'Low-High temp',
// each value is [min, max] -> a floating bar
data: [[10, 18], [12, 20], [8, 15]],
backgroundColor: 'rgba(75,192,192,0.6)'
}]
},
options: { scales: { y: { beginAtZero: false } } }
});Graphiques en courbe
Courbe de base
Un graphique en courbe relie les points dans l'ordre. borderColor est la couleur de la ligne ; backgroundColor sert au remplissage (si fill est actif). tension (0-1) contrôle la douceur de la courbe — 0 donne des segments droits, ~0,3-0,4 des courbes de Bézier douces. Utilisez 0 pour des données précises comme les cours financiers.
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 } } }
});Plusieurs courbes
Chaque dataset d'un graphique en courbe devient sa propre ligne, avec une couleur auto-attribuée de la palette par défaut (remplaçable via borderColor). Les lignes se tracent dans l'ordre des datasets : le dernier dataset s'affiche au-dessus. Donnez un label à chaque dataset pour que la légende les identifie.
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 et interpolation
tension ajoute un lissage de Bézier mais peut dépasser les points de données (creusant sous le minimum). cubicInterpolationMode: 'monotone' lisse sans dépassement — préféré pour les données monotones comme les cours de bourse. borderDash est un motif [tiret, écart] pour des lignes pointillées.
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'
}]Lignes remplies (fill)
fill contrôle l'aire sous la ligne. true/'origin' remplit jusqu'à l'axe x. Un nombre (1, -1, +1) remplit vers un autre dataset par index, utile pour les graphiques à bande. Un nombre négatif remplit vers le dataset précédent. Réglez backgroundColor avec de l'alpha pour que la ligne reste visible à travers le remplissage.
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:...}Style des points
Les propriétés de point acceptent une valeur unique ou un tableau (un par point). pointStyle gère de nombreuses formes ('circle', 'rect', 'rectRot', 'triangle', 'star', 'cross', 'crossRot'). Mettez pointRadius: 0 pour masquer les points (utile sur les courbes denses) et pointHoverRadius plus grand pour un effet interactif.
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],
}]Combler les trous et données manquantes
null, undefined et NaN représentent des données manquantes et coupent la ligne par défaut. spanGaps: true relie les points de part et d'autre d'un trou avec un seul segment. Distinguez NaN (manquant) de 0 (un vrai zéro) — les confondre est une source fréquente de graphiques trompeurs.
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 valueCamemberts et anneaux
Camembert de base
Un camembert montre les parties d'un tout : chaque valeur devient un secteur dont l'angle est proportionnel à sa part. Fournissez une backgroundColor par part (un tableau), sinon Chart.js fait tourner une palette par défaut. Les camemberts fonctionnent mieux avec 3-6 catégories — au-delà c'est illisible.
new Chart(ctx, {
type: 'pie',
data: {
labels: ['Rent', 'Food', 'Fun', 'Save'],
datasets: [{
data: [1200, 600, 400, 800],
backgroundColor: ['#FF6384', '#36A2EB', '#FFCE56', '#4BC0C0']
}]
}
});Anneau (doughnut) de base
Un doughnut est un camembert troué au centre. La propriété cutout (pourcentage en chaîne ou nombre de pixels) contrôle la taille du trou — '50%' donne le look beignet classique. Le trou central peut porter un label de synthèse via un plugin, et la longueur de l'anneau encode la valeur un peu mieux que l'angle.
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 et circonférence
rotation fixe l'angle de départ en degrés (défaut 0 = droite ; -90 = haut). circumference contrôle la portion de cercle tracée — 180 donne un demi-doughnut, utile pour des graphiques façon jauge. Les deux vivent sous options (pas le dataset) en v3+, bien que cutout puisse apparaître aux deux endroits.
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
}
});Bordure et décalage
borderColor avec borderWidth sépare visuellement les secteurs (des bordures blanches donnent un look segmenté net). hoverOffset pousse une part vers l'extérieur au survol, offrant un retour interactif clair. offset est un tableau (un par part) pour « exploser » en permanence des secteurs précis.
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
}]Demi-doughnut (jauge)
Un demi-doughnut (rotation: -90, circumference: 180) se lit comme une jauge/compteur de progression. Associez-lui un plugin de texte central pour afficher le pourcentage, et désactivez la légende pour un look KPI épuré. La part « restante » en gris neutre représente la portion non accomplie.
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 pourcentage du tooltip
Les tooltips camembert/doughnut affichent les valeurs brutes par défaut. Utilisez le callback tooltip callbacks.label pour calculer et afficher des pourcentages à la place — ctx.parsed est la valeur de la part et ctx.dataset.data contient toutes les valeurs pour la somme. Les template literals dans les callbacks doivent échapper backticks et ${} quand ils sont intégrés dans la chaîne de code de ce 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}%)`;
}
}
}
}
}Graphiques radar
Radar de base
Un radar place chaque label comme un sommet sur un polygone, reliés en une forme fermée. fill: true ombrage l'intérieur. L'échelle radiale se configure sous scales.r (pas x/y). Les radars comparent des profils multivariés mais peuvent tromper avec trop d'axes ou des unités non comparables.
new Chart(ctx, {
type: 'radar',
data: {
labels: ['Speed', 'Power', 'Range', 'Comfort', 'Price'],
datasets: [{
label: 'Model X',
data: [8, 7, 6, 9, 5],
borderColor: 'rgba(255,99,132,1)',
backgroundColor: 'rgba(255,99,132,0.2)',
fill: true
}]
},
options: { scales: { r: { beginAtZero: true } } }
});Style du radar
Les datasets radar acceptent les mêmes styles que les courbes : borderColor, fill, style des points, tension. Une faible tension (0,1) arrondit légèrement les sommets pour un rendu plus doux ; 0 garde des pointes droites. Utilisez un backgroundColor translucide pour que les formes radar superposées restent visibles.
datasets: [{
data: [7, 8, 6, 9, 5],
borderColor: 'blue',
backgroundColor: 'rgba(0,0,255,0.2)',
borderWidth: 2,
pointRadius: 4,
pointBackgroundColor: 'blue',
fill: true,
tension: 0.1 // slight curve between vertices
}]Réglages de l'échelle radiale (r)
L'échelle radiale r contrôle les anneaux et labels. min/max fixent la plage de valeurs sur tous les axes (essentiel pour comparer des datasets). ticks.stepSize règle l'espacement des anneaux ; pointLabels stylise les noms de catégories sur le pourtour. Mettez ticks.backdropColor transparent pour que les numéros d'anneaux ne masquent pas le quadrillage.
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 avec plusieurs datasets
Plusieurs datasets se superposent en polygones concentriques, idéal pour des comparaisons avant/après ou entre concurrents. Fixez toujours le même min/max sur r pour que les formes soient comparables, et utilisez des remplissages translucides pour que les deux profils restent visibles là où ils se chevauchent.
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 }
]
}
});Rayons angulaires et grille du radar
angleLines sont les rayons du centre vers chaque sommet ; grid est les anneaux polygonaux concentriques. Masquer les ticks (display:false) retire les labels numériques des anneaux pour une esthétique plus propre tout en gardant les anneaux. pointLabels ne contrôle que le texte de catégorie à chaque sommet.
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
}
}
}Graphiques en aire polaire
Aire polaire de base
Une aire polaire trace chaque valeur comme un secteur couvrant le même angle (360/N chacun), le rayon encodant la valeur. Contrairement au camembert (où angle = valeur), ici rayon = valeur : tous les secteurs ont la même largeur angulaire mais des longueurs différentes.
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 } } }
});Aire polaire vs camembert
La différence clé : dans un camembert, l'ANGLE de chaque part est proportionnel à sa valeur ; dans une aire polaire, c'est le RAYON de chaque secteur qui est proportionnel à sa valeur, les angles étant égaux. Utilisez l'aire polaire quand vous voulez chaque catégorie également visible mais dimensionnée par l'ampleur.
// 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Échelle polaire (r)
L'aire polaire utilise une seule échelle radiale r partagée par tous les secteurs — toutes les valeurs se mesurent donc au même rayon maximum. Définir un max explicite rend le graphique honnête sur l'échelle ; sans lui, Chart.js ajuste automatiquement à la plus grande valeur, ce qui peut exagérer les petits écarts.
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)' }
}
}
}Style des bordures polaires
Les secteurs d'aire polaire acceptent les mêmes styles bordure/remplissage que le camembert/doughnut. Des bordures blanches séparent nettement les secteurs adjacents. hoverBackgroundColor change le remplissage d'un secteur au survol pour un retour interactif. Contrairement au doughnut, pas de cutout — les secteurs se rejoignent au centre.
datasets: [{
data: [11, 16, 7, 14],
backgroundColor: ['#FF6384', '#4BC0C0', '#FFCE56', '#36A2EB'],
borderColor: 'white',
borderWidth: 2,
hoverBackgroundColor: '#333'
}]Polaire avec décalage au survol
L'aire polaire accepte hoverBackgroundColor et hoverBorderColor mais ne prend PAS en charge hoverOffset / offset comme le doughnut, car les secteurs partagent une échelle radiale. Si « faire ressortir » une part est indispensable, choisissez le doughnut. Utilisez couleur et tooltip pour l'interactivité polaire.
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' insteadGraphiques à bulles
Bulles de base
Les points d'un graphique à bulles sont des objets {x, y, r} où x et y sont les coordonnées et r le RAYON de la bulle en pixels. Contrairement au nuage de points, la taille de la bulle encode une troisième variable. Notez que r est un rayon (pas une aire) : une valeur 2x plus grande paraît 4x l'aire — pensez à passer vos tailles au 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 } } }
});Correspondance des tailles de bulles
Comme l'humain perçoit l'AIRE des bulles plutôt que le rayon, faites passer votre valeur par Math.sqrt avant d'assigner r, pour que doubler la valeur double l'aire visible. Choisissez un diviseur qui empêche la plus grande bulle de recouvrir trop de voisines. Le graphique devient perceptuellement honnête.
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 }] } });Couleurs par point
Comme les autres datasets Chart.js, les propriétés de style des bulles acceptent des tableaux pour styler chaque bulle individuellement. Utilisez cela pour coder des bulles par catégorie par la couleur, la taille encodant une valeur numérique distincte — un graphique à 4 dimensions (x, y, taille, couleur).
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
}]Plusieurs datasets de bulles
Plusieurs datasets se rendent en groupes de bulles de couleurs différentes, chacun présent dans la légende. Gardez des rayons modestes quand vous superposez des groupes pour que les bulles ne se masquent pas entièrement. Des remplissages alpha-transparents (0,5-0,6) aident les bulles qui se chevauchent à rester lisibles.
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)' }
]
}
});Style de survol des bulles
Les propriétés de survol (hoverBackgroundColor, hoverBorderColor, hoverBorderWidth, hoverRadius) ne s'appliquent qu'à la bulle sous le pointeur. hoverRadius ajoute des pixels au rayon au survol, faisant ressortir visiblement la bulle visée. Combiné aux tooltips, cela donne un focus interactif clair.
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)
}]Nuages de points
Nuage de points de base
Les points d'un nuage sont des objets {x, y} (pas de rayon nécessaire). L'échelle x doit être de type 'linear' (PAS 'category') pour que les valeurs numériques x se mappent aux vraies positions. Le nuage de points est le graphique standard pour montrer la corrélation entre deux variables continues.
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' } } }
});Nuage avec beaucoup de points
Pour des milliers de points, réduisez pointRadius (1-2px) et utilisez un backgroundColor semi-transparent (alpha 0,2-0,4) pour que les points superposés révèlent la densité par les zones plus foncées. Désactivez le survol des points pour les très gros datasets (pointHitRadius: 0) afin de garder une interaction réactive.
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)' }] }
});Style des points du nuage
pointStyle gère de nombreuses formes au-delà du cercle par défaut : 'rect', 'rectRot', 'triangle', 'star', 'cross', 'crossRot', 'dash'. pointRotation fait pivoter les formes non circulaires. Toutes les propriétés point* acceptent des tableaux pour un style par point — utile pour mettre en évidence des observations précises.
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)
}]Nuage avec droite de tendance
Chart.js n'a pas de droite de tendance intégrée : calculez une régression (moindres carrés ici) et ajoutez un dataset 'line' avec deux extrémités et pointRadius:0. Le type du dataset line l'emporte sur le type du graphique pour cette série — c'est aussi ainsi que fonctionnent les graphiques mixtes. fill:false la garde en simple ligne.
// 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 }
]}
});Nuage vers ligne (showLine)
showLine: true sur un dataset de nuage relie les points par une ligne, transformant effectivement le nuage en graphique en courbe à coordonnées x numériques. C'est le bon choix quand les valeurs x sont des nombres réels (pas des labels de catégorie) mais que vous voulez quand même des segments connectés — ex. séries temporelles à espacement irrégulier.
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
}]}
});Données — Datasets
Structure des datasets
data contient labels (partagés par tous les datasets) et datasets (un tableau de séries). Chaque dataset a un label (affiché en légende/tooltips), un tableau data aligné sur les labels et des propriétés de style. Les propriétés du dataset s'appliquent à chaque point, sauf surcharge par un tableau.
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
}
]
}Alignement labels et data
Le tableau data de chaque dataset est aligné par position sur le tableau labels partagé — data[i] est la valeur de labels[i]. Un tableau data plus court produit des valeurs undefined pour la fin manquante, que les courbes traitent comme des trous. Gardez toujours labels et data de même longueur pour éviter des trous surprenants.
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)Plusieurs datasets
Plusieurs datasets se rendent en séries parallèles (barres groupées, courbes multiples, radars superposés). Ils partagent un tableau labels unique. Définissez des couleurs distinctes par dataset — Chart.js ne colore automatiquement que si backgroundColor est omis, et même là, des couleurs explicites restent plus prévisibles entre versions.
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)' }
]
}Style au niveau du dataset
Le style au niveau du dataset s'applique à chaque point de celui-ci. Les variantes hover* s'activent au survol. hidden:true démarre le dataset masqué (le bouton de légende peut le réafficher). order contrôle l'ordre z — les valeurs basses se tracent plus tard (au-dessus) — utile dans les graphiques mixtes/superposés.
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
}]Parser des données objets
Quand vos données sont un tableau d'objets, indiquez à Chart.js quels champs portent les valeurs d'axes via parsing: {xAxisKey, yAxisKey}. Cela évite un mappage manuel en paires {x, y}. Les clés valent 'x' et 'y' par défaut, les objets {x, y} fonctionnent donc sans config de parsing.
new Chart(ctx, {
type: 'bar',
data: {
datasets: [{
data: [
{ name: 'Red', votes: 12 },
{ name: 'Blue', votes: 19 }
],
parsing: { xAxisKey: 'name', yAxisKey: 'votes' }
}]
}
});Tableaux de style par point
N'importe quelle propriété de style peut être une valeur unique (s'applique à tous les points) ou un tableau (un par point). Cela permet de mettre en évidence des points précis — ex. mettre la plupart des backgroundColor en gris et une en rouge pour attirer l'œil. La longueur du tableau devrait suivre celle des données ; les tableaux plus courts bouclent.
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 — Responsive et échelles
Structure des options
options est l'objet de configuration racine. Il regroupe les préoccupations : plugins (légende/titre/tooltip), scales (x/y/r), layout (padding), animation, interaction (mode de survol) et events. Presque tout comportement de Chart.js se règle ici plutôt que sur les datasets individuels.
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 et maintainAspectRatio
responsive:true fait remplir au graphique la largeur de son conteneur et re-rend au redimensionnement. maintainAspectRatio:false libère la hauteur pour que la hauteur CSS du conteneur soit honorée — réglez les deux et enveloppez le canvas dans un <div> dimensionné. Avec maintainAspectRatio:true (défaut), le graphique garde un rapport largeur/hauteur fixe.
<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>Aperçu des échelles
scales configure chaque axe. L'id (x, y, r) est la clé de l'échelle ; type sélectionne la classe d'échelle. Types courants : 'category' (labels texte), 'linear' (nombres), 'logarithmic', 'time' (exige un adaptateur de dates), 'radialLinear' (radar/polaire). title.display + text ajoute un label d'axe.
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, radialLinearAperçu des plugins
plugins regroupe les plugins intégrés title, legend et tooltip plus les options de tout plugin personnalisé enregistré, par leur id. title ajoute un titre au-dessus du canvas. legend contrôle la clé des datasets. tooltip contrôle les popups de survol. Les plugins personnalisés lisent leurs options dans ce même objet 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 ajoute de l'espace à l'intérieur du canvas entre la zone du graphique et le bord du canvas — utile quand titres, labels d'axes ou gros tooltips seraient sinon coupés. Un nombre unique remplit tous les côtés également ; la forme objet permet des valeurs par côté.
options: {
layout: {
padding: {
top: 10, right: 20, bottom: 10, left: 20
}
}
}
// or a single number for all four sides:
// layout: { padding: 15 }Défauts globaux (Chart.defaults)
Chart.defaults contient la configuration par défaut globale — réglez les valeurs une fois au démarrage de l'app et chaque graphique en hérite. C'est le bon endroit pour l'identité visuelle (police, couleur de base, animation par défaut). Les options par graphique l'emportent toujours sur les défauts, on peut donc encore personnaliser chaque graphique.
// 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 } } });Axes — X et Y
Axe linéaire
Un axe linéaire mappe les nombres proportionnellement. beginAtZero force l'axe à démarrer à 0 (recommandé pour les barres). min/max fixent des limites strictes ; suggestedMin/suggestedMax sont des indications souples que Chart.js peut étendre pour caser les ticks. ticks.callback personnalise le texte des labels (ex. ajouter une unité).
options: {
scales: {
y: {
type: 'linear',
beginAtZero: true,
min: 0, max: 100, // hard limits
ticks: { stepSize: 10, callback: (v) => v + '%' }
}
}
}Axe de catégorie
Un axe de catégorie affiche des labels texte à des positions fixes. C'est l'axe x par défaut des graphiques en barres/courbe. ticks.autoSkip:false force l'affichage de chaque label (sinon Chart.js supprime les chevauchants). maxRotation incline les labels pour prévenir le chevauchement quand il y a beaucoup de catégories.
options: {
scales: {
x: {
type: 'category',
labels: ['Mon','Tue','Wed'], // optional; usually from data.labels
ticks: { autoSkip: false, maxRotation: 45, minRotation: 0 }
}
}
}Axe temporel
Un axe temporel trace des objets Date ou des chaînes ISO proportionnellement au temps, avec des trous là où il n'y a pas de données. Il exige un package d'adaptateur de dates (chartjs-adapter-date-fns, -luxon, -dayjs). time.unit fixe la granularité des ticks ('day','month','year') ; sans lui, Chart.js choisit une unité automatiquement.
# 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' } } } }
});Axe logarithmique
Un axe logarithmique espace les ticks par puissances de 10, essentiel pour des données couvrant des ordres de grandeur (population, prix, fréquences). Il ne peut afficher ni 0 ni de valeurs négatives. ticks.callback permet de formater les labels en puissances de dix de façon compacte (ex. notation scientifique).
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 } }
}
}
});Titre d'axe et callback des ticks
title.display + title.text ajoutent un label d'axe (désactivé par défaut — mettez display:true). ticks.callback reçoit chaque valeur de tick et renvoie la chaîne affichée, permettant de formater les nombres en devise, pourcentages, abréviations k/M ou tout texte personnalisé sans altérer les données sous-jacentes.
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 sont des limites DURES : l'axe y reste même si les données dépassent la plage (données coupées). suggestedMin/suggestedMax sont des indications SOUPLES : Chart.js les prend comme base mais peut élargir pour produire des ticks ronds. Préférez suggested* pour de jolis nombres ronds ; min/max durs pour des échelles fixes comme les pourcentages.
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 }
}
}
}Légende
Bases de la légende
La légende liste le label de chaque dataset avec un échantillon de couleur. display:true l'affiche (défaut), display:false la masque. position accepte 'top', 'bottom', 'left', 'right' ou 'center' (chartArea). Cliquer un élément de légende bascule par défaut la visibilité de ce dataset — une interaction de filtrage intégrée.
new Chart(ctx, {
type: 'bar',
data: { labels: ['A','B'], datasets: [{ label: 'Sales', data: [10,20] }] },
options: {
plugins: {
legend: { display: true, position: 'top' }
}
}
});Position et alignement de la légende
position fixe le côté de la légende ; align contrôle son placement le long de ce côté ('start'/'center'/'end'). labels configure l'échantillon (boxWidth/boxHeight) et le style du texte. maxWidth limite la zone de légende pour que les légendes très longues se replient au lieu de pousser le graphique de côté.
plugins: {
legend: {
position: 'bottom',
align: 'center', // 'start' | 'center' | 'end'
maxWidth: 300,
labels: {
boxWidth: 20,
boxHeight: 20,
padding: 15,
color: '#333',
font: { size: 12 }
}
}
}legend.onClick (bascule personnalisée)
Surchargez legend.onClick pour personnaliser le comportement au clic. Le défaut bascule la visibilité du dataset. La signature est (event, legendItem, legend). Appeler chart.update() après changement d'état re-rend. Utilisez-le pour confirmer avant de masquer, se synchroniser avec une UI externe, ou implémenter une sélection unique (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 des labels de légende
generateLabels renvoie un tableau d'objets label qui contrôlent entièrement ce qui apparaît dans la légende. Le texte de chaque élément, ses couleurs et son état hidden sont personnalisables — utile pour ajouter des comptes, des unités ou dériver une légende de données hors datasets. Le flag hidden et datasetIndex relient les clics au bon dataset.
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
}));
}
}
}
}Masquer la légende et légende externe
Pour un contrôle stylistique complet, désactivez la légende intégrée (display:false) et affichez votre propre légende HTML. Itérez chart.data.datasets, affichez boutons/échantillons, et basculez dataset.hidden + chart.update() au clic. Courant quand on doit coller à un design system où la légende canvas par défaut ne rentre pas.
// 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);
});Info-bulles
Bases du tooltip
Les tooltips apparaissent au survol, montrant le label du dataset et la valeur. enabled:true par défaut. Les propriétés de style (backgroundColor, titleColor, bodyColor, padding, cornerRadius) contrôlent l'apparence. displayColors bascule les petits échantillons de couleur à côté de chaque élément — utile quand beaucoup de datasets se chevauchent.
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 du tooltip
callbacks.label renvoie le texte de chaque ligne du tooltip. ctx.dataset.label est le nom de la série, ctx.parsed.y porte la valeur (utilisez ctx.parsed pour camembert/radar). Formatez la devise, ajoutez des unités ou calculez des totaux ici. La chaîne renvoyée (ou le tableau de chaînes) devient le corps du tooltip.
plugins: {
tooltip: {
callbacks: {
label: (ctx) => {
const label = ctx.dataset.label || '';
const value = ctx.parsed.y ?? ctx.parsed;
return `${label}: $${value}`;
}
}
}
}Callback title du tooltip
callbacks.title contrôle l'en-tête du tooltip (défaut : le label de l'axe x). La fonction reçoit un tableau d'éléments de tooltip (utile quand mode:'index' regroupe plusieurs datasets). Renvoyer une chaîne vide '' supprime entièrement le titre. Combinez les callbacks title et label pour un contenu de tooltip totalement personnalisé.
plugins: {
tooltip: {
callbacks: {
title: (items) => {
// items[0].label is the x-axis label / category
return 'Period: ' + items[0].label;
},
label: (ctx) => ctx.dataset.label + ': ' + ctx.formattedValue
}
}
}Tooltip HTML externe
external permet de rendre le tooltip en vrai HTML — pour du style riche, des images ou des liens impossibles sur canvas. Mettez enabled:false pour que le tooltip par défaut ne se double pas. Le callback reçoit un contexte avec un objet tooltip portant caretX/caretY (position) et les lignes du corps. Positionnez l'élément HTML à ces coordonnées.
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;
}
}
}Mode du tooltip (interaction)
interaction.mode contrôle ce que vise le tooltip. 'point' ne montre que le point survolé ; 'index' montre tous les datasets au même x (parfait pour barres/courbes groupées) ; 'nearest' trouve le point unique le plus proche. intersect:false déclenche le tooltip dès que le pointeur est dans la colonne, pas seulement sur un point — généralement ce que les utilisateurs attendent.
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 } }
}Style et filtres du tooltip
filter saute les lignes de tooltip qui ne remplissent pas une condition (ex. masquer les valeurs nulles/vides). callbacks.footer ajoute une ligne de synthèse après tous les éléments — parfait pour afficher un total. bodyFont/titleFont stylisent le texte ; caretSize et caretPadding contrôlent la petite flèche.
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
}
}Animation
Durée d'animation
animation.duration fixe la durée totale de l'animation en millisecondes (défaut 1000). easing contrôle la courbe d'accélération — 'easeOutQuart' (défaut) démarre vite et décélère, ce qui paraît réactif. Raccourcissez la durée (200-400 ms) pour des dashboards de données mis à jour fréquemment.
options: {
animation: {
duration: 1000, // total duration in ms
easing: 'easeOutQuart'
}
}
// easing options: 'linear','easeInQuad','easeOutQuad','easeInOutQuad',
// 'easeInCubic','easeOutCubic','easeInOutCubic','easeOutBounce',...Désactiver l'animation
Mettez animation:false pour couper toutes les animations — idéal pour les dashboards exigeants en performance ou avec des mises à jour rapides. animation:{duration:0} garde le système d'animation actif mais instantané (le survol fonctionne encore). L'objet animations au pluriel permet de désactiver des propriétés précises comme y tout en animant les autres.
// 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 }
}
}Fonctions d'easing
L'easing change la progression d'une animation dans le temps, affectant fortement la sensation. 'easeOutQuart' (défaut) paraît professionnel et réactif. 'easeOutBounce' ou 'easeInOutBack' sont ludiques mais peuvent sembler gadgets sur des graphiques de données. Accordez l'easing au langage de mouvement général de votre 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 endsAnimation onComplete
onComplete se déclenche à la fin d'une animation — utile pour enchaîner des actions comme activer un bouton d'export ou déclencher un rendu suivant. onProgress se déclenche à chaque frame avec le nombre d'étapes. Évitez le travail lourd dans onProgress car il tourne 60 fois par seconde.
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
}
}
}Animation par propriété (animations)
L'objet animations au pluriel configure les propriétés individuellement. Chaque entrée peut préciser from/to (ou une fonction du contexte de parsing), duration, easing et loop. Animer tension de 1 à 0,3 produit un effet « la ligne se stabilise » ; animer y depuis la base de l'axe produit un effet de « croissance ».
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) }
}
}Événements et clics
Gestionnaire onClick
options.onClick se déclenche quand l'utilisateur clique n'importe où sur le graphique. L'argument elements est un tableau des éléments cliqués (barres/points), chacun avec .datasetIndex et .index. Si elements est vide, le clic a touché du canvas vide. C'est la façon standard de rendre les graphiques interactifs (drill-down, sélection).
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 trouve les éléments du graphique sous un événement souris natif, avec les mêmes options de mode que interaction ('nearest', 'index', 'x', etc.). Le 4e argument useFinalPosition doit être true pour le hit-testing des positions finales rendues. Utilisez-le quand vous cherchez des éléments hors options.onClick.
const chart = new Chart(ctx, { /* ... */ });
canvas.addEventListener('click', (e) => {
const points = chart.getElementsAtEventForMode(
e, 'nearest', { intersect: true }, true // (event, mode, options, useFinalPosition)
);
if (points.length) {
const p = points[0];
console.log('dataset', p.datasetIndex, 'index', p.index);
}
});onHover
options.onHover se déclenche à chaque mouvement de souris sur le graphique. Utilisez-le pour des retours UI peu coûteux comme changer le curseur (comme montré) ou surligner des éléments externes liés. Évitez les opérations coûteuses ici — il se déclenche très souvent. Pour de la logique plus lourde, utilisez onClick ou débouncz le handler.
options: {
onHover(event, elements, chart) {
// change cursor to a pointer when hovering a bar
event.native.target.style.cursor =
elements.length ? 'pointer' : 'default';
}
}Survol et éléments actifs
La config hover contrôle comment le graphique met en évidence les éléments sous le pointeur. mode:'nearest' + intersect:true surligne le point unique le plus proche. animationDuration lisse la transition de surbrillance. chart.setActiveElements déclenche par programme l'état de survol — utile pour synchroniser les surlignages avec une UI externe.
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();Liste des événements
events limite les événements DOM écoutés par le graphique. Réduire la liste (ex. à 'click' seul) désactive les effets de survol pour un rendu statique et améliore les performances des dashboards. Pour les contextes mobiles tactiles uniquement, incluez touchstart/touchmove. Un tableau vide désactive toute interaction.
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+)Exemple de drill-down
Un pattern courant : cliquer une barre échange le dataset pour une vue plus détaillée (drill-down). Capturez l'index cliqué, remplacez chart.data.labels et chart.data.datasets[...].data, puis appelez chart.update() pour animer la transition. Gardez une pile de vues si vous voulez un bouton retour.
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();
}}
});Graphiques mixtes
Graphique mixte barres + courbe
Mélangez les types en réglant type sur les datasets individuels — il l'emporte sur le type du graphique pour cette série. Le combo barres + courbe est le mélange le plus courant (ex. revenus en barres, taux de croissance en ligne). Utilisez un second axe y (y1) quand les séries ont des unités ou échelles différentes.
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 } } } }
});Surcharge du type par dataset
N'importe quel dataset peut surcharger le type du graphique, permettant de combiner barres, courbe et nuage en un graphique. Les datasets sans type explicite héritent du type du graphique. Attention à l'ordre z : les datasets se tracent dans l'ordre du tableau, placez donc les séries d'arrière-plan (barres) avant celles de premier plan (lignes).
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
]
}
});Axes Y multiples (y, y1, y2)
Définissez plusieurs axes y avec des ids personnalisés (y, y1, y2) et assignez les datasets via yAxisID. grid.drawOnChartArea:false empêche le second axe de tracer son quadrillage par-dessus le premier. position:'right' l'empile à droite ; ajoutez offset:true à un troisième axe pour qu'il ne chevauche pas le second. Colorez chaque axe pour qu'il corresponde à sa 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'Données mixtes de formes différentes
Les graphiques mixtes peuvent combiner une série de valeurs (barres) avec des lignes de référence (cible constante, tendance). Mettez pointRadius:0 et fill:false sur les datasets de ligne pour qu'ils se rendent en lignes pures, sans marqueurs ni remplissage. Ce pattern est courant dans les dashboards de performance (réel vs cible).
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 }
]
}
});Conseils de style mixte
Dans les graphiques mixtes, réglez dataset.order pour que la ligne se trace au-dessus des barres (order plus bas = au-dessus). Codifiez par couleur les ticks et le titre de chaque axe pour qu'ils correspondent à sa série, afin que le lecteur sache quelle échelle appartient à quelle ligne. Désactivez le quadrillage du second axe (drawOnChartArea:false) pour éviter le double quadrillage.
// 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 intégrés
Chart.js livre trois plugins intégrés : Title (titre du graphique au-dessus du canvas), Legend (la clé des datasets) et Tooltip (popups de survol). Ils se configurent sous options.plugins par leur id et sont actifs par défaut (sauf Title, qui exige display:true pour afficher son texte).
// 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 inline personnalisé
Passez un tableau d'objets plugin à un seul graphique via l'option plugins. Chaque plugin a un id et des fonctions de hooks (beforeInit, afterInit, beforeDraw, afterDraw, beforeUpdate, etc.). Les plugins inline ne s'appliquent qu'à cette instance. ctx.save()/restore() encadrent toute modification d'état du canvas.
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 (cycle de vie)
Les hooks de plugin s'exécutent à chaque étape du cycle de vie du graphique : init, update, render, draw, resize, destroy. Les hooks before* peuvent annuler une action en renvoyant false. Les plus courants pour le dessin personnalisé sont afterDraw (dessiner par-dessus) ou beforeDraw (dessiner derrière les données). Chaque hook reçoit l'instance du graphique.
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 : ligne verticale à l'index
Un plugin personnalisé courant trace une ligne guide verticale à la position du tooltip (comme le réticule par défaut). afterDraw lit la coordonnée x de l'élément tooltip actif et trace une ligne pointillée du haut en bas de la zone du graphique. Encadrez l'état du canvas de save()/restore() pour que le style pointillé ne fuit pas.
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 : texte central du doughnut
Dessiner un texte de synthèse centré est le cas d'usage classique d'un plugin doughnut. afterDatasetsDraw s'exécute après les secteurs pour que le texte se place au-dessus. Calculez le total (ou toute synthèse) et affichez-le au centre géométrique du chartArea. Cela transforme un doughnut en widget KPI informatif.
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] });Enregistrer un plugin globalement
Chart.register(plugin) fait s'appliquer un plugin à tout graphique créé ensuite — idéal pour des plugins à l'échelle de l'app comme filigranes, identité ou analytique. Pour un graphique ponctuel, utilisez plutôt le tableau plugins inline. Chart.unregister le retire. Les plugins enregistrés lisent leur config dans 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 insteadMise à jour et destruction
chart.update()
Après modification de chart.data ou chart.options, appelez chart.update() pour re-rendre. Par défaut, le changement s'anime depuis l'état précédent. Passez 'none' comme mode pour sauter l'animation (utile pour les mises à jour à haute fréquence). Modifier puis mettre à jour coûte bien moins que détruire et recréer le graphique.
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 animationModes de mise à jour
update(mode) accepte une chaîne de mode contrôlant le comportement. 'none' désactive l'animation pour un rafraîchissement silencieux. 'reset' rembobine aux valeurs d'avant animation puis ré-anime (bien pour rejouer l'entrée). 'active' ne met à jour que les éléments survolés pour des re-rendus de survol peu coûteux. Le défaut (sans argument) anime normalement.
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) elementsMettre à jour données et labels
Vous pouvez remplacer data/labels en bloc ou les muter en place (push/shift). Pour des graphiques en flux continu (ex. une fenêtre de 60 secondes), ajoutez la nouvelle valeur et retirez la plus ancienne, puis update('none') pour un rafraîchissement fluide sans animation — appeler la mise à jour animée par défaut à chaque tick provoque un décalage saccadé.
// 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() démonte le graphique : il retire les écouteurs d'événements, annule les animations, efface le canvas et libère la mémoire. Appelez toujours destroy quand le conteneur d'un graphique est retiré (cleanup de React useEffect, changement de route). Ne pas détruire fuit la mémoire et peut lever des erreurs 'Canvas is already in use' en réutilisant un canvas.
const chart = new Chart(ctx, config);
// when done (route change, component unmount, etc.):
chart.destroy();
// after destroy the canvas is free; a new Chart can reuse it:
const fresh = new Chart(ctx, newConfig);
// destroy also removes event listeners and frees memorychart.resize() et clear()
chart.resize() recalcule la taille du graphique — avec responsive:true cela se fait automatiquement au redimensionnement de la fenêtre, les appels manuels sont donc rares. chart.clear() efface le canvas sans détruire le graphique (la prochaine mise à jour re-dessine). chart.resize(width, height) force des dimensions en pixels précises, en l'emportant sur le sizing responsif.
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);Responsive et device pixel ratio
Conteneur responsif
Pour un graphique responsif, enveloppez le canvas dans un conteneur positionné avec width/height explicites et réglez responsive:true + maintainAspectRatio:false. Le canvas remplit le conteneur et re-rend au redimensionnement de la fenêtre. Sans maintainAspectRatio:false, le graphique garde un rapport fixe et ignore la hauteur du conteneur.
<!-- 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 (défaut) garde le canvas à un rapport largeur/hauteur fixe défini par aspectRatio (défaut 2 = 2:1). maintainAspectRatio:false libère la hauteur au conteneur. Camembert/doughnut ont un aspectRatio:1 (carré) par défaut, car les cercles rendent mal dans un rectangle large.
// 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 = largeur / hauteur. Avec maintainAspectRatio:true, les dimensions du canvas suivent ce rapport. Utilisez un rapport plus élevé (3-4) pour des tuiles de dashboard larges, plus bas (1-1,5) pour des panneaux hauts. Camembert/doughnut valent 1 par défaut car les cercles exigent un canvas carré pour ne pas ressembler à des ellipses.
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-likeMéthode chart.resize()
Chart.js écoute automatiquement les redimensionnements de fenêtre quand responsive:true, mais les changements de mise en page dus aux transitions CSS, à la bascule d'une barre latérale ou au changement d'onglet peuvent ne pas déclencher de resize de fenêtre. Dans ces cas, appelez chart.resize() manuellement une fois la taille du conteneur stabilisée (ex. dans un setTimeout ou un handler 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 (rendu net)
devicePixelRatio met à l'échelle la mémoire tampon du canvas pour que les lignes restent nettes sur les écrans haute densité/retina (défaut : window.devicePixelRatio, généralement 2 ou 3). Plafonner à 2 garde le texte net tout en limitant la charge en pixels des téléphones 3x. Régler à 1 produit un rendu flou sur retina mais maximise la vitesse.
// 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 }Pattern ResizeObserver
Un ResizeObserver sur le conteneur du graphique attrape les changements de taille dus au flexbox/grid CSS, aux barres latérales repliables et aux changements d'onglets que le resize de fenêtre rate. Déconnectez l'observer et appelez chart.destroy() dans votre teardown pour éviter les fuites. C'est le pattern responsif le plus robuste pour les mises en page complexes.
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 Chart.js associés
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?