Chart

Use Chart.js with Basecoat defaults for themed colors, tooltips, and legends.

Required dependency: Chart.js

Load Chart.js on pages that render charts. Basecoat’s Chart API is in beta and may change.

Usage

Load the styles

Serve the compiled Basecoat stylesheet from your assets directory, or use the CDN installation.

<link rel="stylesheet" href="/assets/css/basecoat.cdn.min.css" />

For a custom Tailwind build, import basecoat-css/base.css, basecoat-css/components/chart.css, and your style pack.

Load Chart.js and the Basecoat Chart script

Add the browser build of Chart.js, then load Basecoat’s runtime and Chart script in order. The Chart script is distributed separately from all.js. You can also serve Chart.js locally.

<script src="https://cdn.jsdelivr.net/npm/chart.js@4.6.1/dist/chart.umd.min.js" defer></script>
<script src="/assets/js/basecoat.min.js" defer></script>
<script src="/assets/js/chart.min.js" defer></script>

Add the chart canvas

<canvas id="visitors-chart" aria-label="Monthly visitors"></canvas>

Draw the chart

Pass the canvas selector, data, and series to Basecoat after the scripts have loaded.

<script>
  document.addEventListener("DOMContentLoaded", () => {
    window.basecoat.chart("#visitors-chart", {
      type: "bar",
      labelKey: "month",
      data: [
        { month: "Jan", desktop: 186, mobile: 80 },
        { month: "Feb", desktop: 305, mobile: 200 },
        { month: "Mar", desktop: 237, mobile: 120 },
        { month: "Apr", desktop: 73, mobile: 190 },
        { month: "May", desktop: 209, mobile: 130 },
        { month: "Jun", desktop: 214, mobile: 140 },
      ],
      series: {
        desktop: { label: "Desktop", color: "var(--chart-1)" },
        mobile: { label: "Mobile", color: "var(--chart-2)" },
      },
    })
  })
</script>

basecoat.chart() targets the <canvas> directly and creates Basecoat’s internal .chart container for Chart.js sizing. You do not need to add a wrapper or class in your HTML.

Charts default to aspect-video. Use a height, min-h-*, or aspect-* utility on a parent element when you need a different measuring box.

Legend

Set legend: true to generate a Basecoat-styled legend after the canvas.

The generated legend is display-only by default, matching shadcn/ui. Use a Chart.js plugin or custom legend markup if you need click-to-toggle behavior.

window.basecoat.chart("#visitors-chart", {
  type: "bar",
  labelKey: "month",
  data,
  series,
  legend: true,
})

Series

series maps object keys from each data row to labels, colors, and optional Chart.js dataset settings.

window.basecoat.chart("#revenue-chart", {
  type: "line",
  labelKey: "month",
  data,
  series: {
    recurring: {
      label: "Recurring",
      color: "var(--chart-1)",
      surface: "gradient",
      dataset: {
        fill: true,
        tension: 0.35,
      },
    },
    new: {
      label: "New",
      color: "var(--chart-2)",
      dataset: {
        borderDash: [4, 4],
      },
    },
  },
})

Escape Hatches

Pass raw Chart.js options and plugins through options and plugins.

const chart = window.basecoat.chart("#visitors-chart", {
  type: "bar",
  labelKey: "month",
  data,
  series,
  options: {
    indexAxis: "x",
    scales: {
      y: {
        beginAtZero: true,
      },
    },
    plugins: {
      tooltip: {
        mode: "index",
      },
    },
  },
  plugins: [myChartJsPlugin],
})

Pass complete Chart.js data through chartData when the simplified data plus series mapper is not enough.

window.basecoat.chart("#custom-chart", {
  type: "scatter",
  chartData: {
    datasets: [
      {
        label: "Samples",
        data: [{ x: 1, y: 2 }, { x: 2, y: 5 }],
      },
    ],
  },
  options: {
    scales: {
      x: { type: "linear" },
    },
  },
})

basecoat.chart() returns the Chart.js instance for single targets and an array of instances for multi-target selectors.

Examples

Bar chart - multiple

Line chart - linear

Line chart - step

Bar chart - stacked

Pie chart - donut

Radar chart

API

OptionDefaultDescription
type"bar"Chart.js chart type.
labelKey"label"Row key used for labels.
data[]Array of row objects, or raw Chart.js data with datasets.
series{}Series config mapped from row keys.
legendfalseGenerates a Basecoat legend after the canvas.
tooltiptrueUses the Basecoat external tooltip.
options{}Raw Chart.js options.
plugins[]Raw Chart.js plugins.
chartDataundefinedComplete Chart.js data object. Overrides the data mapper.

Series options

OptionDescription
labelDisplay label for legends and tooltips.
colorBase color for the series stroke, fill, legend marker, and tooltip marker.
surfaceDerives a fill from color. Use true for a translucent fill, "gradient" for an upstream-style vertical fade, or { from, to } for custom opacity stops.
datasetRaw Chart.js dataset options.