mirror of
https://github.com/hunvreus/basecoat.git
synced 2026-11-12 13:18:22 +00:00
269 lines
6.7 KiB
Plaintext
269 lines
6.7 KiB
Plaintext
import basecoatRuntimeSource from "../../../src/js/basecoat.js?raw"
|
|
import chartRuntimeSource from "../../../src/js/chart.js?raw"
|
|
import chartExamplesSource from "../site/chart-examples.js?raw"
|
|
|
|
# Chart
|
|
|
|
<Callout type="warning" title="Beta API" icon="triangle-alert">
|
|
Chart support is beta. The JavaScript API, generated markup, and option names may change before the stable 1.0 release.
|
|
</Callout>
|
|
|
|
Use Chart.js with Basecoat defaults for themed colors, external tooltips, and optional generated legends.
|
|
|
|
<Preview class="w-full">
|
|
<canvas id="chart-example-overview" aria-label="Visitors by device"></canvas>
|
|
</Preview>
|
|
|
|
## Usage
|
|
|
|
<Steps>
|
|
<Step title="Include CSS">
|
|
|
|
Import Tailwind and one full Basecoat style bundle.
|
|
|
|
```css
|
|
@import "tailwindcss";
|
|
@import "basecoat-css/vega.css";
|
|
```
|
|
|
|
Or import only the base CSS, Chart component CSS, and one style pack.
|
|
|
|
```css
|
|
@import "tailwindcss";
|
|
@import "basecoat-css/base.css";
|
|
@import "basecoat-css/components/chart.css";
|
|
@import "basecoat-css/styles/vega.css";
|
|
```
|
|
|
|
Using CDN or bundler imports? See the [Installation page](/installation).
|
|
|
|
</Step>
|
|
<Step title="Include JavaScript">
|
|
|
|
Copy or serve Chart.js, the Basecoat runtime, and Chart script.
|
|
|
|
```html
|
|
<script src="/assets/js/chart.umd.min.js"></script>
|
|
<script src="/assets/js/basecoat.min.js" defer></script>
|
|
<script src="/assets/js/chart.min.js" defer></script>
|
|
```
|
|
|
|
Chart is not included in the full Basecoat JavaScript bundle.
|
|
|
|
Using CDN or bundler imports? See the [Installation page](/installation).
|
|
|
|
</Step>
|
|
<Step title="Add your chart HTML">
|
|
|
|
```html
|
|
<canvas id="visitors-chart" aria-label="Monthly visitors"></canvas>
|
|
<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>
|
|
```
|
|
|
|
</Step>
|
|
</Steps>
|
|
|
|
`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.
|
|
|
|
```js
|
|
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.
|
|
|
|
```js
|
|
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`.
|
|
|
|
```js
|
|
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.
|
|
|
|
```js
|
|
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
|
|
|
|
<Preview class="w-full">
|
|
<canvas id="chart-example-visitors" aria-label="Monthly visitors by device"></canvas>
|
|
</Preview>
|
|
|
|
### Line chart - linear
|
|
|
|
<Preview class="w-full">
|
|
<canvas id="chart-example-line" aria-label="Revenue line chart"></canvas>
|
|
</Preview>
|
|
|
|
### Line chart - step
|
|
|
|
<Preview class="w-full">
|
|
<canvas id="chart-example-step" aria-label="Support queue step chart"></canvas>
|
|
</Preview>
|
|
|
|
### Bar chart - stacked
|
|
|
|
<Preview class="w-full">
|
|
<canvas id="chart-example-stacked" aria-label="Stacked pipeline bar chart"></canvas>
|
|
</Preview>
|
|
|
|
### Pie chart - donut
|
|
|
|
<Preview class="w-full">
|
|
<canvas id="chart-example-donut" aria-label="Traffic source donut chart"></canvas>
|
|
</Preview>
|
|
|
|
### Radar chart
|
|
|
|
<Preview class="w-full">
|
|
<canvas id="chart-example-radar" aria-label="Channel performance radar chart"></canvas>
|
|
</Preview>
|
|
|
|
<script is:inline src="https://cdn.jsdelivr.net/npm/chart.js/dist/chart.umd.min.js"></script>
|
|
<script is:inline>{`
|
|
(() => {
|
|
const initChartPage = () => {
|
|
if (!window.Chart) {
|
|
requestAnimationFrame(initChartPage)
|
|
return
|
|
}
|
|
|
|
if (!window.basecoat) {
|
|
${basecoatRuntimeSource}
|
|
}
|
|
|
|
if (!window.basecoat.chart) {
|
|
${chartRuntimeSource}
|
|
}
|
|
|
|
${chartExamplesSource}
|
|
}
|
|
|
|
initChartPage()
|
|
})()
|
|
`}</script>
|
|
|
|
## API
|
|
|
|
| Option | Default | Description |
|
|
| --- | --- | --- |
|
|
| `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. |
|
|
| `legend` | `false` | Generates a Basecoat legend after the canvas. |
|
|
| `tooltip` | `true` | Uses the Basecoat external tooltip. |
|
|
| `options` | `{}` | Raw Chart.js options. |
|
|
| `plugins` | `[]` | Raw Chart.js plugins. |
|
|
| `chartData` | `undefined` | Complete Chart.js data object. Overrides the data mapper. |
|
|
|
|
### Series options
|
|
|
|
| Option | Description |
|
|
| --- | --- |
|
|
| `label` | Display label for legends and tooltips. |
|
|
| `color` | Base color for the series stroke, fill, legend marker, and tooltip marker. |
|
|
| `surface` | Derives a fill from `color`. Use `true` for a translucent fill, `"gradient"` for an upstream-style vertical fade, or `{ from, to }` for custom opacity stops. |
|
|
| `dataset` | Raw Chart.js dataset options. |
|