Skip to content

Chart.js 치트시트

간단하면서도 유연한 JavaScript 차트 라이브러리입니다.

01

시작하기

설정과 첫 차트

Chart.js는 canvas 요소에 렌더링됩니다. type 속성이 차트 타입을 정합니다. data는 레이블과 값·스타일을 가진 datasets을 포함합니다.

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>

npm 설치와 ES 모듈 임포트

가장 간단한 설정에는 'chart.js/auto'를 사용하세요 — Chart.js와 모든 컨트롤러/엘리먼트를 임포트하고 자동 등록합니다. 더 작은 프로덕션 번들을 원하면 tree-shaking을 선호하세요: 'chart.js'에서 임포트하고 사용하는 조각만 등록합니다.

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와 2D 컨텍스트

Chart.js는 <canvas> 요소나 2d 렌더링 컨텍스트 중 하나를 받을 수 있습니다. responsive가 true이면 canvas가 컨테이너를 채우도록 크기 조정되므로, width/height HTML 속성은 폴백일 뿐입니다. 각 canvas에는 정확히 하나의 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

사용 가능한 차트 타입

Chart.js는 8가지 차트 타입을 제공합니다. Bar, line, scatter, bubble은 데카르트 축을 쓰고, pie, doughnut, polarArea는 원형이며, radar는 자체 방사형 축을 갖습니다. 최상위 'type' 필드가 모든 dataset에 사용될 컨트롤러를 선택하며, dataset이 자체 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과 Register

'chart.js'(/auto 아님)에서 임포트하면 아무것도 등록되지 않으므로 컨트롤러, 엘리먼트, 스케일, 플러그인을 직접 등록해야 합니다. 이 tree-shakeable 방식은 번들 크기를 크게 줄일 수 있습니다. 컴포넌트 등록을 잊는 것이 가장 흔한 '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와 생명주기

각 Chart 인스턴스는 canvas와 연결된 이벤트 리스너를 소유합니다. destroy()를 호출하면 모두 해체되어 canvas를 재사용할 수 있습니다 — SPA와 React/Vue effect에서 필수입니다. 활성 canvas에 두 번째 차트를 만들면 메모리가 누출되고 그래픽이 이중으로 렌더링됩니다.

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

막대 차트(Bar)

기본 막대 차트

막대 차트는 각 레이블을 데이터 값과 같은 높이의 막대에 매핑합니다. backgroundColor가 막대 채움을, borderColor/borderWidth가 외곽선을 정합니다. 막대가 항상 0에서 시작하도록 y.beginAtZero를 설정하세요 — 없으면 Chart.js가 축 최솟값을 자동 조정해 차이를 시각적으로 왜곡할 수 있습니다.

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 } } }
});

가로 막대 (indexAxis)

Chart.js v3+에서 가로 막대는 'bar' 타입에 indexAxis: 'y'로 만듭니다 — 이전의 'horizontalBar' 타입은 제거되었습니다. x 스케일이 값 축이 됩니다. 가로 막대는 세로 차트에서 겹칠 긴 카테고리 레이블에 이상적입니다.

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 } }
  }
});

그룹 막대 (여러 dataset)

막대 차트의 여러 dataset은 기본적으로 나란히(그룹) 배치됩니다. backgroundColor를 생략해야 Chart.js가 색을 자동 배정하므로, 예측 가능한 출력을 위해 dataset마다 명시적 색을 설정하세요. 각 dataset은 x축에서 같은 labels 배열을 공유합니다.

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 } } }
});

누적 막대

누적 막대는 x와 y 스케일 둘 다에 stacked: true가 필요합니다. 각 dataset의 막대는 이전 막대 위에 그려져 합산됩니다. 누적은 구성 비율을 보여 주지만, 상위 시리즈는 그룹 막대보다 카테고리 간 비교가 어렵습니다.

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 }
    }
  }
});

막대 스타일링

borderRadius는 막대 모서리를 둥글게 합니다(단일 숫자는 모든 모서리에 적용; {topLeft:8} 같은 객체는 특정 모서리만). borderSkipped는 기본적으로 'start'로 한 변을 생략합니다 — 네 변을 모두 그리려면 false로. barPercentage와 categoryPercentage가 함께 막대 두께와 간격을 조절합니다.

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
    }]
  }
});

플로팅 막대 ([min, max])

데이터 값으로 [min, max] 쌍을 전달하면 0에서 시작하지 않는 플로팅 막대가 됩니다 — 일별 최저-최고 기온, 시가-종가, 신뢰 구간 같은 범위에 완벽합니다. 범위 막대에서는 y축이 0에서 시작하면 안 됩니다. 가로 막대에서도 동작합니다.

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

선 차트(Line)

기본 선 차트

선 차트는 데이터 포인트를 순서대로 연결합니다. borderColor가 선 색이고, backgroundColor는 채움(fill 활성화 시)에 사용됩니다. tension(0~1)이 곡선의 부드러움을 조절합니다 — 0은 직선, 약 0.3~0.4가 완만한 베지어 곡선입니다. 금융 가격 같은 정밀 데이터에는 0을 사용하세요.

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 } } }
});

여러 선

선 차트의 각 dataset은 자기 선이 되며 기본 팔레트에서 색이 자동 배정됩니다(borderColor로 재정의 가능). 선은 dataset 순서대로 그려지므로 마지막 dataset이 위에 렌더링됩니다. 범례가 식별할 수 있도록 각 dataset에 label을 전달하세요.

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과 보간

tension은 베지어 스무딩을 더하지만 데이터 포인트를 넘어설 수 있습니다(최솟값 아래로 꺼짐). cubicInterpolationMode: 'monotone'은 넘어서지 않고 부드럽게 합니다 — 주가 같은 단조 데이터에 선호됩니다. borderDash는 파선/점선을 위한 [dash, gap] 패턴입니다.

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'
}]

채워진 선 (fill)

fill은 선 아래 영역을 제어합니다. true/'origin'은 x축까지 채웁니다. 숫자(1, -1, +1)는 인덱스로 다른 dataset 쪽을 채워 밴드 차트에 유용합니다. 음수는 이전 dataset 쪽으로 채웁니다. 채움을 통해 선이 보이도록 알파가 있는 backgroundColor를 설정하세요.

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

포인트 스타일링

포인트 속성은 단일 값이나 배열(포인트마다 하나)을 받습니다. pointStyle은 다양한 모양을 지원합니다('circle', 'rect', 'rectRot', 'triangle', 'star', 'cross', 'crossRot'). pointRadius: 0으로 포인트를 완전히 숨기고(촘촘한 선 차트에 유용), pointHoverRadius를 크게 하면 인터랙티브 팝 효과가 납니다.

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

Span Gaps와 결측 데이터

null, undefined, NaN은 결측 데이터를 나타내며 기본적으로 선을 끊습니다. spanGaps: true는 끊긴 양쪽 포인트를 하나의 세그먼트로 연결합니다. NaN(결측)과 0(실제 영점)을 구분하세요 — 이를 혼동하는 것이 오해를 부르는 차트의 흔한 원인입니다.

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

파이와 도넛 차트

기본 파이 차트

파이 차트는 전체 중 부분을 보여 줍니다: 각 값이 자기 비율에 비례하는 각도의 조각이 됩니다. 조각마다 backgroundColor를 하나씩(배열로) 제공하세요, 아니면 Chart.js가 기본 팔레트를 순환합니다. 파이 차트는 3~6개 카테고리에서 가장 잘 동작합니다 — 그 이상은 읽기 어렵습니다.

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

기본 도넛 차트

도넛은 가운데에 구멍이 있는 파이입니다. cutout 속성(백분율 문자열이나 픽셀 수)이 구멍 크기를 조절합니다 — '50%'가 클래식한 도넛 모양입니다. 가운데 구멍은 플러그인으로 요약 레이블을 담을 수 있고, 링 길이는 조각 각도보다 값을 약간 더 잘 인코딩합니다.

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, 회전, Circumference

rotation이 시작 각도를 도 단위로 정합니다(기본 0 = 오른쪽; -90 = 위). circumference는 원의 어느 만큼을 그릴지 조절합니다 — 180은 반 도넛이며 게이지 스타일 차트에 유용합니다. 둘 다 v3+에서 options(가 아니라 dataset 아님)에 위치하지만, cutout은 어느 쪽에도 둘 수 있습니다.

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
  }
});

테두리와 Offset

borderColor와 borderWidth가 조각을 시각적으로 분리합니다(흰 테두리가 깔끔한 분절 모양을 줍니다). hoverOffset은 사용자가 조각에 hover하면 밖으로 밀어 명확한 인터랙티브 피드백을 줍니다. offset은 배열(조각마다 하나)로 특정 조각을 영구적으로 '터져 보이게' 강조합니다.

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

반 도넛 (게이지)

반 도넛(rotation: -90, circumference: 180)은 게이지/진행 계기처럼 읽힙니다. 센터 텍스트 플러그인과 짝지어 백분율을 표시하고, 깔끔한 KPI 모양을 위해 범례를 끄세요. 중립 회색의 '나머지' 조각이 미완료 부분을 전달합니다.

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 } }
  }
});

툴팁 백분율 콜백

파이/도넛 툴팁은 기본적으로 원시 값을 보여 줍니다. tooltip의 callbacks.label로 백분율을 계산해 표시하세요 — ctx.parsed가 조각 값이고 ctx.dataset.data가 합계에 쓸 모든 값을 담습니다. 이 치트시트의 코드 문자열에 포함된 콜백의 템플릿 리터럴은 백틱과 ${}를 이스케이프해야 합니다.

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

레이더 차트

기본 레이더 차트

레이더 차트는 각 레이블을 다각형의 꼭짓점으로 놓고 닫힌 모양으로 연결합니다. fill: true는 내부를 음영 처리합니다. 방사형 스케일은 x/y가 아니라 scales.r 아래 설정합니다. 레이더는 다변량 프로필을 비교하지만 축이 너무 많거나 단위가 비교 불가하면 오해를 부를 수 있습니다.

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 } } }
});

레이더 스타일링

레이더 dataset은 선 차트와 같은 스타일링을 받습니다: borderColor, fill, 포인트 스타일, tension. 작은 tension(0.1)은 꼭짓점을 약간 둥글게 해 부드러운 느낌을 주고, 0은 곧은 뾰족함을 유지합니다. 겹치는 레이더 모양이 보이도록 반투명 backgroundColor를 사용하세요.

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

레이더 스케일 (r) 설정

방사형 스케일 r이 링과 레이블을 제어합니다. min/max가 모든 축에서 값 범위를 고정합니다(dataset 비교 시 필수). ticks.stepSize가 링 간격을 정하고, pointLabels가 둘레의 카테고리 이름을 스타일링합니다. 링 숫자가 그리드선을 가리지 않도록 ticks.backdropColor를 투명하게 하세요.

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

여러 dataset의 레이더

여러 dataset은 동심원 다각형으로 겹쳐지며, 전/후나 경쟁사 비교에 이상적입니다. 모양이 비교 가능하도록 항상 r에 같은 min/max를 설정하고, 겹치는 곳에서 두 프로필이 모두 보이도록 반투명 채움을 사용하세요.

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 }
    ]
  }
});

레이더 각도선과 그리드

angleLines는 중심에서 각 꼭짓점으로의 스포크이고, grid는 동심원 다각형 링입니다. ticks를 숨기면(display:false) 링은 유지하면서 숫자 링 레이블을 제거해 더 깔끔한 미학을 줍니다. pointLabels는 각 꼭짓점의 카테고리 텍스트만 제어합니다.

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

폴라 에어리어 차트

기본 폴라 에어리어 차트

폴라 에어리어 차트는 각 값을 같은 각도(각각 360/N)를 덮는 부채꼴로 그리며, 반지름이 값을 인코딩합니다. 파이(각도 = 값)와 달리 여기서는 반지름 = 값이므로 모든 조각의 각 폭은 같고 길이만 다릅니다.

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 } } }
});

폴라 에어리어 vs 파이

핵심 차이: 파이에서는 각 조각의 '각도'가 값에 비례하지만, 폴라 에어리어에서는 각 조각의 '반지름'이 값에 비례하고 각도는 같습니다. 모든 카테고리를 동등하게 보여 주되 크기로 구분하고 싶을 때 폴라 에어리어를 사용하세요.

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

폴라 스케일 (r)

폴라 에어리어는 모든 부채꼴이 공유하는 단일 방사형 스케일 r을 사용합니다 — 모든 값이 같은 최대 반지름 기준으로 측정됩니다. 명시적 max를 설정하면 차트가 스케일에 대해 정직해 집니다; 없으면 Chart.js가 가장 큰 값으로 자동 스케일해 작은 차이를 과장할 수 있습니다.

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)' }
    }
  }
}

폴라 테두리 스타일링

폴라 에어리어 부채꼴은 파이/도넛과 같은 테두리/채움 스타일링을 받습니다. 흰 테두리가 인접한 부채꼴을 명확히 분리합니다. hoverBackgroundColor는 hover 시 부채꼴의 채움을 바꿔 인터랙티브 피드백을 줍니다. 도넛과 달리 cutout이 없습니다 — 부채꼴이 중심에서 만납니다.

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

Hover Offset을 가진 폴라

폴라 에어리어는 hoverBackgroundColor와 hoverBorderColor를 지원하지만 도넛처럼 hoverOffset / offset을 같은 방식으로 지원하지 않습니다. 부채꼴이 방사형 스케일을 공유하기 때문입니다. 조각을 '밀어내는' 것이 필수라면 도넛을 선택하세요. 폴라의 인터랙티비티는 색과 툴팁 변경으로 구현합니다.

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

버블 차트

기본 버블 차트

버블 차트의 데이터 포인트는 {x, y, r} 객체이며 x, y는 좌표, r은 버블 '반지름'(픽셀)입니다. scatter와 달리 버블 크기가 세 번째 변수를 인코딩합니다. r은 반지름(면적 아님)이므로 값이 2배면 면적은 시각적으로 4배입니다 — 크기 데이터를 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 } } }
});

버블 크기 매핑

사람은 반지름보다 버블 '면적'을 지각하므로, r을 할당하기 전에 값을 Math.sqrt로 매핑하세요 — 값이 두 배면 보이는 면적도 두 배가 됩니다. 가장 큰 버블이 너무 많은 이웃과 겹치지 않게 하는 제수를 고르세요. 이렇게 하면 차트가 지각적으로 정직해 집니다.

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 }] } });

포인트별 버블 색상

다른 Chart.js dataset처럼 버블 스타일링 속성도 배열을 받아 버블마다 개별 스타일링이 가능합니다. 크기가 별도의 수치를 인코딩하는 동안 카테고리별로 버블에 색을 입히는 데 사용하세요 — 4차원 차트(x, y, 크기, 색)가 됩니다.

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

여러 버블 dataset

여러 dataset은 다른 색의 버블 그룹으로 렌더링되며 각각 범례에 표시됩니다. 그룹을 겹칠 때는 버블 반지름을 절제하세요 — 버블이 서로를 완전히 가리지 않도록. 알파 투명 채움(0.5~0.6)이 겹치는 버블의 가독성을 유지해 줍니다.

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)' }
    ]
  }
});

버블 Hover 스타일링

hover 속성(hoverBackgroundColor, hoverBorderColor, hoverBorderWidth, hoverRadius)은 포인터 아래 버블에만 적용됩니다. hoverRadius는 hover 시 반지름에 픽셀을 더해 대상 버블이 확실히 튀어 보이게 합니다. 툴팁과 결합하면 명확한 인터랙티브 포커스가 됩니다.

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

스캐터 차트

기본 스캐터 차트

스캐터 차트의 데이터 포인트는 {x, y} 객체입니다(반지름 불필요). x 스케일은 type: 'linear'(가 아님)여야 숫자 x 값이 실제 위치에 매핑됩니다. 스캐터는 두 연속 변수의 상관관계를 보여 주는 표준 차트입니다.

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' } } }
});

포인트가 많은 스캐터

수천 개의 포인트는 pointRadius를 줄이고(1~2px) 반투명 backgroundColor(알파 0.2~0.4)를 사용하세요 — 겹치는 포인트가 어두운 영역으로 밀도를 드러냅니다. 매우 큰 dataset에서는 인터랙션이 반응적이도록 포인트 hover를 비활성화하세요(pointHitRadius: 0).

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)' }] }
});

스캐터 포인트 스타일링

pointStyle은 기본 원 외에 다양한 모양을 지원합니다: 'rect', 'rectRot', 'triangle', 'star', 'cross', 'crossRot', 'dash'. pointRotation이 원형이 아닌 모양을 회전시킵니다. 모든 point* 속성은 포인트별 스타일링을 위한 배열을 받습니다 — 특정 관측치 강조에 유용합니다.

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)
}]

추세선이 있는 스캐터

Chart.js에는 내장 추세선이 없으므로 회귀(여기서는 최소제곱)를 계산하고 두 끝점과 pointRadius:0을 가진 'line' dataset을 추가하세요. line dataset의 type이 chart 단위 타입을 dataset별로 재정의합니다 — 혼합 차트가 동작하는 방식이기도 합니다. fill:false는 순수한 선으로 유지합니다.

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 }
  ]}
});

스캐터에서 선으로 (showLine)

스캐터 dataset에 showLine: true를 주면 포인트를 선으로 연결해 숫자 x 좌표를 쓰는 선 차트가 됩니다. x 값이 실수(카테고리 레이블이 아님)인데 연결 세그먼트가 필요할 때 올바른 선택입니다 — 예: 간격이 불규칙한 시계열.

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

데이터 — Datasets

Dataset 구조

data는 labels(모든 dataset이 공유)와 datasets(시리즈의 배열)을 담습니다. 각 dataset은 label(범례/툴팁에 표시), labels와 정렬된 data 배열, 스타일링 속성을 갖습니다. dataset에 설정된 속성은 배열로 재정의되지 않는 한 모든 포인트에 적용됩니다.

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

labels와 data 정렬

각 dataset의 data 배열은 공유 labels 배열과 위치로 정렬됩니다 — data[i]가 labels[i]의 값입니다. 더 짧은 data 배열은 누락된 꼬리에 undefined를 만들고, 선 차트는 이를 끊김으로 처리합니다. 의외의 끊김을 피하려면 labels와 data 길이를 항상 같게 유지하세요.

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)

여러 dataset

여러 dataset은 병렬 시리즈로 렌더링됩니다(그룹 막대, 다중 선, 겹친 레이더). 하나의 labels 배열을 공유합니다. dataset마다 구별되는 색을 설정하세요 — Chart.js는 backgroundColor가 생략될 때만 자동으로 색을 입히며, 그때조차 명시적 색이 버전 간 더 예측 가능합니다.

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)' }
  ]
}

Dataset 수준 스타일링

dataset 수준 스타일은 그 dataset의 모든 포인트에 적용됩니다. hover* 변형은 hover 시 활성화됩니다. hidden:true로 시작하면 dataset이 숨겨진 상태로 시작합니다(범례 토글로 다시 볼 수 있음). order는 z-순서를 제어합니다 — 낮은 숫자가 나중에(위에) 그려짐 — 혼합/겹침 차트에 유용합니다.

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

객체 데이터 파싱

데이터가 객체 배열일 때 parsing: {xAxisKey, yAxisKey}로 어느 필드가 축 값을 담는지 Chart.js에 알려 주세요. {x, y} 쌍으로 수동 매핑하는 것을 피합니다. 키는 기본 'x'와 'y'이므로 {x, y} 객체는 parsing 설정 없이 동작합니다.

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

포인트별 스타일링 배열

모든 스타일링 속성은 단일 값(모든 포인트에 적용)이거나 배열(포인트마다 하나)이 될 수 있습니다. 특정 포인트 강조를 가능하게 합니다 — 예: 대부분의 backgroundColor를 회색으로, 하나는 빨강으로 하여 주목을 끕니다. 배열 길이는 데이터 길이와 일치해야 하고; 짧은 배열은 순환합니다.

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는 최상위 설정 객체입니다. 관심사를 그룹화합니다: plugins(legend/title/tooltip), scales(x/y/r), layout(패딩), animation, interaction(hover 모드), events. 거의 모든 Chart.js 동작이 개별 dataset이 아니라 여기서 조정됩니다.

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와 maintainAspectRatio

responsive:true는 차트가 컨테이너 폭을 채우고 resize 시 다시 렌더링하게 합니다. maintainAspectRatio:false는 높이를 놓아 주어 컨테이너의 CSS 높이가 존중됩니다 — 둘 다 설정하고 canvas를 크기가 지정된 <div>로 감싸세요. maintainAspectRatio:true(기본)는 고정된 폭/높이 비율을 유지합니다.

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>

스케일 개요

scales는 각 축을 설정합니다. id(x, y, r)가 스케일 키이고, type이 스케일 클래스를 선택합니다. 흔한 타입: 'category'(텍스트 레이블), 'linear'(숫자), 'logarithmic', 'time'(date 어댑터 필요), 'radialLinear'(레이더/폴라). title.display + text가 축 레이블을 추가합니다.

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

플러그인 개요

plugins는 내장 title, legend, tooltip 플러그인과 등록된 커스텀 플러그인의 옵션을 각자의 id로 묶습니다. title은 canvas 위에 차트 제목을 추가합니다. legend가 dataset 키를 제어합니다. tooltip이 hover 팝업을 제어합니다. 커스텀 플러그인도 같은 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 (패딩)

layout.padding은 차트 영역과 canvas 가장자리 사이에 canvas 내부 공간을 추가합니다 — 제목, 축 레이블, 큰 툴팁이 잘리지 않게 하는 데 유용합니다. 단일 숫자는 모든 면에 균등하게 패딩을 주고, 객체 형태는 면별 값을 허용합니다.

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

전역 기본값 (Chart.defaults)

Chart.defaults는 전역 기본 설정을 담습니다 — 앱 시작 시 한 번 설정하면 모든 차트가 상속합니다. 브랜딩(폰트 패밀리, 기본 색, 기본 애니메이션)의 올바른 위치입니다. 차트별 옵션이 항상 기본값을 재정의하므로 개별 차트는 여전히 커스터마이즈할 수 있습니다.

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

축 — X와 Y

선형 축

선형 축은 숫자를 비례적으로 매핑합니다. beginAtZero는 축이 0에서 시작하도록 강제합니다(막대 차트에 권장). min/max는 하드 한계이고; suggestedMin/suggestedMax는 Chart.js가 틱에 맞게 확장할 수 있는 소프트 힌트입니다. ticks.callback이 레이블 텍스트를 커스터마이즈합니다(예: 단위 추가).

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

카테고리 축

카테고리 축은 고정 위치에 텍스트 레이블을 표시합니다. 막대/선 차트의 기본 x축입니다. ticks.autoSkip:false는 모든 레이블이 표시되도록 강제합니다(그렇지 않으면 Chart.js가 겹치는 것을 버립니다). maxRotation은 카테고리가 많을 때 겹침을 막으려고 레이블을 기울입니다.

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

시간 축

시간 축은 Date 객체나 ISO 문자열을 시간에 비례하게 배치하며, 데이터가 없는 곳에는 빈틈이 생깁니다. date 어댑터 패키지(chartjs-adapter-date-fns, -luxon, -dayjs)가 필요합니다. time.unit이 틱 세분성을 고정합니다('day','month','year'); 없으면 Chart.js가 단위를 자동으로 고릅니다.

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' } } } }
});

로그 축

로그 축은 10의 거듭제곱 간격으로 틱을 배치하며, 여러 자릿수에 걸친 데이터(인구, 가격, 주파수)에 필수입니다. 0이나 음수는 표시할 수 없습니다. ticks.callback으로 10의 거듭제곱 레이블을 간결하게 포맷할 수 있습니다(예: 과학적 표기법).

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 } }
    }
  }
});

축 제목과 틱 콜백

title.display + title.text가 축 레이블을 추가합니다(기본은 항상 꺼져 있음 — display:true 설정). ticks.callback은 각 틱 값을 받아 표시 문자열을 반환하므로, 기저 데이터를 바꾸지 않고 숫자를 통화, 백분율, k/M 약어, 임의 텍스트로 포맷할 수 있습니다.

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는 하드 한계입니다: 데이터가 범위를 넘어도 축이 그 안에 머릅니다(데이터가 잘림). suggestedMin/suggestedMax는 소프트 힌트입니다: Chart.js가 기준선으로 쓰지만 예쁜 반올림 틱을 위해 확장할 수 있습니다. 예쁜 정수를 원하면 suggested*를 선호하고; 백분율 같은 고정 스케일에는 하드 min/max를 사용하세요.

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

범례(Legend)

범례 기본

범례는 각 dataset의 label을 색 견본과 함께 나열합니다. display:true는 표시(기본), display:false는 숨김입니다. position은 'top', 'bottom', 'left', 'right' 또는 'center'(chartArea)를 받습니다. 범례 항목 클릭은 기본적으로 그 dataset의 가시성을 토글합니다 — 내장 필터링 인터랙션입니다.

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

범례 위치와 정렬

position이 범례의 쪽을 정하고, align이 그 쪽을 따라 배치를 조절합니다('start'/'center'/'end'). labels가 견본(boxWidth/boxHeight)과 텍스트 스타일을 설정합니다. maxWidth가 범례 영역을 한정해 아주 긴 범례가 차트를 밀어내는 대신 줄바꿈되게 합니다.

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 (커스텀 토글)

legend.onClick을 재정의해 클릭 동작을 커스터마이즈합니다. 기본은 dataset 가시성 토글입니다. 시그니처는 (event, legendItem, legend)입니다. 상태 변경 후 chart.update()를 호출하면 다시 렌더링됩니다. 숨기기 전 확인, 외부 UI와 동기화, 단일 선택(라디오) 동작 구현에 사용하세요.

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();
    }
  }
}

범례 레이블 콜백

generateLabels는 범례에 표시될 내용을 완전히 제어하는 레이블 객체 배열을 반환합니다. 각 항목의 text, 견본 색, hidden 상태를 커스터마이즈할 수 있습니다 — 개수나 단위 추가, dataset이 아닌 데이터로 범례를 만드는 데 유용합니다. hidden 플래그와 datasetIndex가 클릭을 올바른 dataset에 연결합니다.

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
        }));
      }
    }
  }
}

범례 숨기기와 외부 범례

완전한 스타일 제어를 위해 내장 범례를 끄고(display:false) 자체 HTML 범례를 렌더링하세요. chart.data.datasets를 순회해 버튼/견본을 렌더링하고, 클릭 시 dataset.hidden을 토글 + chart.update()를 호출합니다. 기본 canvas 범례가 맞지 않는 디자인 시스템에 흔한 방법입니다.

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

툴팁(Tooltip)

툴팁 기본

툴팁은 hover 시 dataset 레이블과 값을 보여 줍니다. enabled:true가 기본입니다. 스타일링 속성(backgroundColor, titleColor, bodyColor, padding, cornerRadius)이 모양을 제어합니다. displayColors는 항목 옆의 작은 색 견본을 토글합니다 — 많은 dataset이 겹칠 때 유용합니다.

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
    }
  }
}

툴팁 label 콜백

callbacks.label이 각 툴팁 행의 텍스트를 반환합니다. ctx.dataset.label이 시리즈 이름이고, ctx.parsed.y가 값을 담습니다(파이/레이더는 ctx.parsed 사용). 여기서 통화 포맷, 단위 추가, 총계 계산을 합니다. 반환된 문자열(또는 문자열 배열)이 툴팁 본문이 됩니다.

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

툴팁 title 콜백

callbacks.title이 툴팁 헤더를 제어합니다(기본: x축 레이블). 함수는 툴팁 항목의 배열을 받습니다(mode:'index'가 여러 dataset을 묶을 때 유용). 빈 문자열 ''을 반환하면 제목이 완전히 사라집니다. 완전히 커스텀한 툴팁 콘텐츠를 위해 title과 label 콜백을 조합하세요.

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
    }
  }
}

외부 HTML 툴팁

external은 툴팁을 진짜 HTML로 렌더링하게 합니다 — canvas에서는 불가능한 풍부한 스타일, 이미지, 링크에. 기본 툴팁이 이중 렌더링하지 않도록 enabled:false로 하세요. 콜백은 caretX/caretY(위치)와 본문 줄을 담은 tooltip 객체가 있는 컨텍스트를 받습니다. 그 좌표에 HTML 요소를 배치하세요.

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;
    }
  }
}

툴팁 모드 (interaction)

interaction.mode가 툴팁 대상을 결정합니다. 'point'는 hover된 포인트만; 'index'는 같은 x의 모든 dataset을 보여 줍니다(그룹 막대/선에 좋음); 'nearest'는 가장 가까운 단일 포인트를 찾습니다. intersect:false는 포인터가 포인트 위가 아니라 열 안 어디든 툴팁을 트리거합니다 — 보통 사용자가 기대하는 동작입니다.

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 } }
}

툴팁 스타일링과 필터

filter는 조건에 맞지 않는 툴팁 행을 건너뜁니다(예: 0/빈 값 숨기기). callbacks.footer는 모든 항목 뒤에 요약 행을 추가합니다 — 총계 표시에 완벽합니다. bodyFont/titleFont가 텍스트를 스타일링하고, caretSize와 caretPadding이 작은 포인터 화살표를 제어합니다.

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

애니메이션

애니메이션 지속 시간

animation.duration은 전체 애니메이션 길이를 밀리초로 설정합니다(기본 1000). easing이 가속 곡선을 제어합니다 — 'easeOutQuart'(기본)는 빠르게 시작해 감속하며 반응성 있게 느껴집니다. 자주 갱신되는 데이터 대시보드는 지속 시간을 줄이세요(200~400ms).

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

애니메이션 비활성화

animation:false는 모든 애니메이션을 완전히 끕니다 — 성능이 중요한 대시보드나 빠른 업데이트에 최적입니다. animation:{duration:0}은 애니메이션 시스템을 활성 상태로 유지하지만 즉시 적용됩니다(hover는 여전히 동작). 복수형 animations 객체로 y 같은 특정 속성만 비활성화하고 다른 속성은 애니메이션할 수 있습니다.

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 }
  }
}

Easing 함수

Easing은 애니메이션의 시간 진행 방식을 바꿔 느낌에 큰 영향을 줍니다. 'easeOutQuart'(기본)는 전문적이고 반응성 있게 느껴집니다. 'easeOutBounce'나 'easeInOutBack'은 장난스럽지만 데이터 차트에서는 과할 수 있습니다. 앱의 전체 모션 언어에 맞는 easing을 고르세요.

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

onComplete는 애니메이션이 끝나면 실행됩니다 — 내보내기 버튼 활성화나 후속 렌더링 트리거 같은 체이닝 동작에 유용합니다. onProgress는 매 애니메이션 프레임에 단계 수와 함께 실행됩니다. 초당 60번 실행되므로 onProgress에 무거운 작업은 피하세요.

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
    }
  }
}

속성별 애니메이션 (animations)

복수형 animations 객체는 개별 속성을 독립적으로 설정합니다. 각 항목은 from/to(또는 파싱 컨텍스트의 함수), duration, easing, loop를 지정할 수 있습니다. tension을 1에서 0.3으로 애니메이션하면 '선이 가라앉는' 효과가, y를 축 기준선에서 애니메이션하면 '위로 자라는' 효과가 납니다.

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

이벤트와 클릭

onClick 핸들러

options.onClick은 차트의 어느 곳이든 클릭하면 실행됩니다. elements 인자는 클릭된 차트 요소(막대/포인트)의 배열로, 각각 .datasetIndex와 .index를 갖습니다. elements가 비었으면 클릭이 빈 canvas를 맞춘 것입니다. 차트를 인터랙티브하게 만드는(드릴다운, 선택) 표준 방법입니다.

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는 네이티브 마우스 이벤트 아래의 차트 요소를 찾으며, interaction과 같은 모드 옵션('nearest', 'index', 'x' 등)을 사용합니다. 네 번째 인자 useFinalPosition은 최종 렌더링 위치를 히트 테스트할 때 true여야 합니다. 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는 차트 위의 모든 마우스 이동에서 실행됩니다. 커서 변경(예시처럼)이나 관련 외부 요소 강조 같은 가벼운 UI 피드백에 사용하세요. 매우 자주 실행되므로 비싼 작업은 피합니다. 무거운 로직은 onClick을 쓰거나 핸들러를 디바운스하세요.

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와 활성 요소

hover 설정은 포인터 아래 요소를 차트가 강조하는 방식을 제어합니다. mode:'nearest' + intersect:true가 가장 가까운 단일 포인트를 강조합니다. animationDuration이 하이라이트 전환을 부드럽게 합니다. chart.setActiveElements는 프로그래밍 방식으로 hover 상태를 트리거합니다 — 차트 하이라이트를 외부 UI와 동기화하는 데 유용합니다.

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();

이벤트 목록

events는 차트가 감청할 DOM 이벤트를 한정합니다. 목록을 줄이면(예: 'click'만) hover 효과가 꺼져 정적인 느낌이 되고 대시보드 성능이 향상됩니다. 터치 전용 모바일 컨텍스트에는 touchstart/touchmove를 포함하세요. 빈 배열은 모든 인터랙션을 비활성화합니다.

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

드릴다운 예제

흔한 패턴: 막대 클릭 시 dataset을 더 상세한 뷰로 교체합니다(드릴다운). 클릭된 인덱스를 캡처하고, chart.data.labels와 chart.data.datasets[...].data를 교체한 뒤 chart.update()를 호출해 전환을 애니메이션합니다. 뒤로 가기 버튼을 원하면 뷰의 스택을 유지하세요.

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

혼합 차트

막대 + 선 혼합 차트

개별 dataset에 type을 설정해 차트 타입을 혼합합니다 — 그 시리즈에 대해 차트 수준 타입을 재정의합니다. 막대 + 선 조합이 가장 흔한 혼합입니다(예: 매출은 막대, 성장률은 선). 시리즈의 단위나 스케일이 다르면 두 번째 y축(y1)을 사용하세요.

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 } } } }
});

Dataset type 재정의

어떤 dataset이든 차트 수준의 type을 재정의해 하나의 차트에서 bar, line, scatter를 조합할 수 있습니다. 명시적 type이 없는 dataset은 차트의 타입을 상속합니다. z-순서에 유의하세요: dataset은 배열 순서대로 그려지므로 배경 시리즈(막대)를 전경 시리즈(선)보다 앞에 두세요.

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
    ]
  }
});

여러 Y축 (y, y1, y2)

커스텀 id(y, y1, y2)로 여러 y축을 정의하고 yAxisID로 dataset을 할당합니다. grid.drawOnChartArea:false가 두 번째 축이 첫 축 위에 그리드선을 그리는 것을 막습니다. position:'right'는 오른쪽에 쌓고, 세 번째 축에는 offset:true를 더해 두 번째와 겹치지 않게 합니다. 각 축을 자기 시리즈에 맞게 색칠하세요.

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'

다른 모양의 혼합 데이터

혼합 차트는 값 시리즈(막대)와 기준선(상수 목표, 추세)을 결합할 수 있습니다. 선 dataset에 pointRadius:0과 fill:false를 설정하면 마커나 채움 없는 순수한 선으로 렌더링됩니다. 이 패턴은 성능 대시보드(실적 vs 목표)에 흔합니다.

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 }
    ]
  }
});

혼합 스타일링 팁

혼합 차트에서 dataset.order를 설정하면 선이 막대 위에 그려집니다(낮은 order = 위에). 각 축의 틱과 제목을 자기 시리즈에 맞게 색코딩해 어떤 스케일이 어느 선에 속하는지 읽는 사람이 알게 하세요. 이중 그리드선을 피하려면 두 번째 축의 그리드를 끄세요(drawOnChartArea:false).

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

플러그인

내장 플러그인

Chart.js는 세 가지 내장 플러그인을 제공합니다: Title(canvas 위의 차트 제목), Legend(dataset 키), Tooltip(hover 팝업). options.plugins 아래에서 각자의 id로 설정되며 기본 활성화입니다(Title만 display:true가 필요합니다).

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 }
    }
  }
});

커스텀 인라인 플러그인

plugins 옵션으로 단일 차트에 플러그인 객체 배열을 전달합니다. 각 플러그인은 id와 훅 함수(beforeInit, afterInit, beforeDraw, afterDraw, beforeUpdate 등)를 갖습니다. 인라인 플러그인은 그 차트 인스턴스에만 적용됩니다. ctx.save()/restore()로 canvas 상태 변경을 감싸세요.

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();
    }
  }]
});

플러그인 훅 (생명주기)

플러그인 훅은 차트 생명주기의 모든 단계에서 실행됩니다: init, update, render, draw, resize, destroy. before* 훅은 false를 반환해 동작을 취소할 수 있습니다. 커스텀 그리기에는 afterDraw(차트 위에 그림)나 beforeDraw(데이터 뒤에 그림)가 가장 흔합니다. 각 훅은 차트 인스턴스를 받습니다.

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'); }
};

플러그인: 인덱스에 수직선

흔한 커스텀 플러그인은 툴팁 위치에 수직 가이드라인을 그립니다(기본 크로스헤어처럼). afterDraw가 활성 툴팁 요소의 x 좌표를 읽고 차트 영역 위에서 아래로 파선을 그립니다. 파선 스타일이 새지 않도록 canvas 상태를 save()/restore()로 감싸세요.

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();
    }
  }
};

플러그인: 도넛 센터 텍스트

중앙에 요약 텍스트를 그리는 것은 도넛 플러그인의 클래식한 유스케이스입니다. afterDatasetsDraw는 조각 뒤에 실행되므로 텍스트가 위에 놓입니다. 총계(또는 임의 요약)를 계산해 chartArea의 기하 중심에 렌더링합니다. 도넛이 정보성 KPI 위젯이 됩니다.

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] });

플러그인 전역 등록

Chart.register(plugin)은 이후 생성되는 모든 차트에 플러그인을 적용합니다 — 워터마크, 브랜딩, 분석 같은 앱 전역 플러그인에 이상적입니다. 일회성 차트에는 인라인 plugins 배열을 사용하세요. Chart.unregister가 제거합니다. 등록된 플러그인은 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

업데이트와 Destroy

chart.update()

chart.data나 chart.options를 변경한 후 chart.update()를 호출해 다시 렌더링합니다. 기본적으로 이전 상태에서 애니메이션됩니다. 애니메이션을 건너뛰려면 모드로 'none'을 전달하세요(고빈도 업데이트에 유용). 변경 후 업데이트하는 것이 차트를 파괴하고 재생성하는 것보다 훨씬 저렴합니다.

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

업데이트 모드

update(mode)는 동작을 제어하는 모드 문자열을 받습니다. 'none'은 조용한 갱신을 위해 애니메이션을 끕니다. 'reset'은 애니메이션 전 값으로 되감았다가 다시 애니메이션합니다(등장 재생에 좋음). 'active'는 hover된 요소만 업데이트해 저렴한 hover 재렌더링을 합니다. 기본(인자 없음)은 정상 애니메이션입니다.

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

데이터와 레이블 업데이트

data/labels를 통째로 교체하거나 제자리에서 변형할 수 있습니다(push/shift). 라이브 스트리밍 차트(예: 60초 창)는 새 값을 추가하고 가장 오래된 것을 shift한 뒤 update('none')으로 부드러운 무애니메이션 갱신을 하세요 — 매 틱마다 기본 애니메이션 업데이트를 호출하면 버벅이는 지연이 생깁니다.

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()는 차트를 해체합니다: 이벤트 리스너를 제거하고, 애니메이션을 취소하며, canvas를 지우고, 메모리를 해제합니다. 차트의 컨테이너가 제거될 때(React useEffect cleanup, 라우트 변경) 항상 destroy를 호출하세요. 파괴하지 않으면 메모리가 누출되고 canvas를 재사용할 때 'Canvas is already in use' 오류가 날 수 있습니다.

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()와 clear()

chart.resize()는 차트 크기를 다시 계산합니다 — responsive:true면 window resize 시 자동이므로 수동 호출은 드뭅니다. chart.clear()는 차트를 파괴하지 않고 canvas를 비웁니다(다음 업데이트가 다시 그림). chart.resize(width, height)는 특정 픽셀 크기를 강제하며 반응형 크기 조정을 무시합니다.

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

반응형과 Device Pixel Ratio

반응형 컨테이너

반응형 차트를 위해 canvas를 명시적 width/height를 가진 positioned 컨테이너로 감싸고 responsive:true + maintainAspectRatio:false를 설정하세요. canvas가 컨테이너를 채우고 window resize 시 다시 렌더링합니다. maintainAspectRatio:false가 없으면 차트가 고정 종횡비를 유지하며 컨테이너의 높이를 무시합니다.

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(기본)는 canvas를 aspectRatio가 정한 고정 폭/높이 비율로 유지합니다(기본 2 = 2:1). maintainAspectRatio:false는 높이를 컨테이너에 맡깁니다. 파이/도넛은 원이 넓은 직사각형에서 어색해 보이므로 aspectRatio:1(정사각형)이 기본입니다.

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 = 폭 / 높이입니다. maintainAspectRatio:true이면 canvas 크기가 이 비율을 따릅니다. 넓은 대시보드 타일에는 더 높은 비율(3~4), 높은 패널에는 더 낮은 비율(1~1.5)을 사용하세요. 파이/도넛은 원이 타원처럼 보이지 않으려면 정사각형 canvas가 필요해 1이 기본입니다.

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

chart.resize() 메서드

Chart.js는 responsive:true일 때 window resize 이벤트를 자동 감청하지만, CSS 트랜지션, 사이드바 토글, 탭 전환으로 인한 레이아웃 변경은 window resize를 발생시키지 않을 수 있습니다. 그런 경우 컨테이너 크기가 안정된 후(setTimeout이나 transitionend 핸들러에서) chart.resize()를 수동 호출하세요.

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 (선명한 렌더링)

devicePixelRatio는 canvas 백킹 스토어를 스케일해 고DPI/레티나 화면에서 선이 선명하게 유지됩니다(기본은 window.devicePixelRatio 사용, 보통 2~3). 2로 제한하면 3x 폰의 픽셀 작업량을 한정하면서 텍스트를 또렷하게 유지합니다. 1로 설정하면 레티나에서 흐릿하지만 렌더 속도가 최대화됩니다.

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 }

ResizeObserver 패턴

차트 컨테이너의 ResizeObserver는 window resize가 놓치는 CSS flexbox/grid, 접히는 사이드바, 탭 전환의 크기 변경을 잡습니다. 누출을 막으려면 해체 시 observer를 연결 해제하고 chart.destroy()를 호출하세요. 복잡한 레이아웃에서 가장 견고한 반응형 패턴입니다.

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.