Simple, responsive charts, drawn in SVG and styled with CSS. Tiny, typed, and happy without a build step.
**[chartist.dev](https://chartist.dev)** · [Getting started](https://chartist.dev/docs/getting-started/) · [API](https://chartist.dev/api/) · [Examples](https://chartist.dev/examples/) · [Plugins](https://chartist.dev/plugins/) · [Changelog](https://github.com/chartist-js/chartist/blob/main/CHANGELOG.md)
> **Coming from Chartist 1?** Your code keeps working. [Coming from 1.x](https://chartist.dev/docs/coming-from-1x/) shows what's new, and the 1.x docs are at [chartist.dev/v1/](https://chartist.dev/v1/).
## Install
```sh
npm install chartist
```
```ts
import { lineChart } from 'chartist';
import 'chartist/styles.css';
lineChart('#chart', {
labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
series: [
[12, 9, 7, 8, 5],
[2, 1, 3.5, 7, 3]
]
});
```
```html
```
No bundler? Chartist is a native ES module:
```html
```
## Why Chartist
- **Style it with CSS.** Plain SVG with predictable classes and custom properties for colors, lines and labels. No theme engine.
- **Responsive, two ways.** Options that change with media queries, or with the chart's own container.
- **Composed charts.** Bars and lines in one chart, on as many axes as you need.
- **Renders anywhere SVG does.** Render on a server, with real SVG text labels, for PDFs, email and images.
- **Extend everything.** Every element passes through an open pipeline you can hook into, and the community's plugins keep working.
- **Tiny and typed.** Written in TypeScript, no dependencies, and you ship only what you import.
## Coming from 1.x
Your 1.x code keeps working: the chart classes draw what they drew before. 1.x events and plugins work with `chartist/compat`. The classes are deprecated, and 3.0 removes them from `chartist`. [Coming from 1.x](https://chartist.dev/docs/coming-from-1x/) explains what changed and how to move to the functions.
## Community wrappers
Chartist needs no wrapper: a chart is a container and a function call, and [Charts in frameworks](https://chartist.dev/docs/frameworks/) has recipes for React, Vue, Angular and Svelte, with server rendering. If you'd rather use a component, the community wraps Chartist for these stacks. Thank you to everyone who built them!
| Stack | Wrapper | Built for |
| ------------- | ----------------------------------------------------------------------------------------------- | ------------ |
| React | [react-chartist](https://github.com/fraserxu/react-chartist) | Chartist 1.x |
| Angular | [ng-chartist](https://github.com/willsoto/ng-chartist) | Chartist 1.x |
| Vue | [vue-chartist](https://github.com/Yopadd/vue-chartist) | Chartist 0.x |
| Node.js | [node-chartist](https://github.com/panosoft/node-chartist) | Chartist 0.x |
| Ember | [ember-cli-chartist](https://github.com/jherdman/ember-cli-chartist) | Chartist 0.x |
| Java (JSF) | [ChartistJSF](https://github.com/hatemalimam/ChartistJSF) | Chartist 0.x |
| Vue 2 | [v-chartist](https://github.com/lakb248/vue-chartist) | Chartist 0.x |
| R | [chartist](https://github.com/yutannihilation/chartist) (htmlwidget) | Chartist 0.x |
| Meteor | [mfpierre:chartist-js](https://github.com/mfpierre/meteor-chartist-js) | Chartist 0.x |
| WordPress | [TablePress Extension: Chartist](https://wordpress.org/plugins/charts-for-tablepress-chartist/) | Chartist 0.x |
| Blazor | [UnlockedData.Chartist.Blazor](https://github.com/unlockeddataltd/UnlockedData.Chartist.Blazor) | Chartist 0.x |
| Angular | [ngx-chartist](https://github.com/affilnost/ngx-chartist) | Chartist 0.x |
| Ruby on Rails | [chartist-rails](https://github.com/AnthonyBobsin/chartist-rails) | Chartist 0.x |
Wrappers built for 1.x run on v2: see [Community wrappers](https://chartist.dev/docs/frameworks/#community-wrappers) for the npm `overrides` entry they need until they allow `chartist@2`. Maintain a wrapper that's missing here? Send a pull request.
## Supported by
[Cube](https://cube.dev) sponsors Chartist's maintenance. Thank you!
## Contributing
This repository holds the library (`packages/chartist`), its docs site at chartist.dev (`apps/docs`), the examples and the playground, in an Nx and pnpm monorepo. Clone it, run `pnpm install`, and run tasks through Nx, for example `pnpm nx test chartist` or `pnpm nx dev docs`. [CONTRIBUTING.md](CONTRIBUTING.md) has the setup, the tests and the submission guidelines.
## License
Dual-licensed under [MIT](LICENSE-MIT) or [WTFPL](LICENSE-WTFPL), at your choice.
---
### Overview (`docs/visual-design/README.md`)
# Visual design
Chartist's brand and the docs site's design were made in Claude Design. This folder is a snapshot of that canvas, kept as the design reference for the site.
- Canvas: https://claude.ai/artifact/CFCX75HRhyT28hXYSNdgbU (snapshot of version `1791919724-153a`)
- Implemented in `apps/docs`: the tokens in `src/styles/tokens.css`, the mascot in `src/components/Mascot.astro`, the logomark in `src/components/Logomark.astro`. Styling rules: `apps/docs/STYLING.md`.
To change the design, change the site; the canvas is the reference for new pages and components, not a source the site is generated from. When the design itself changes in the canvas, download a new snapshot here and say what changed in the commit.
## Contents
- `project/canvas.json`: the canvas index (artboard titles, positions, grouping).
- `project/chartist.css`: the design system. It holds the palette (`--p-*`), the semantic tokens for light (`.cx`) and dark (`.cx.dark`), the mascot colors (`--m-*`), the chart series palette (`--ct-series-*`, including the accessible theme), and component styles.
- `project/*.dc.html`: one file per artboard.
- `project/paper.png`, `project/paper-dark.png`: the design's paper texture, "Cream Paper" from Subtle Patterns (CC BY-SA 3.0). The site uses it as the page ground texture (`apps/docs/src/assets/`).
- `assets/reference-*-0x.svg`: the original 2014 mascot and icon, uploaded as a reference for the redesign.
The `.dc.html` files are Claude Design component pages. They need the Design runtime (`support.js`, not included) to render, so read them as source (markup, tokens, copy, data), and open the canvas link to see them rendered.
| Group | Artboards |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Brand | `Main` (overview and rationale), `MascotPoses`, `Logo` |
| Brand system | `Color`, `Typography`, `VoiceMotion`, `Tokens` (tokens → chart theme), `OgCard` |
| Components (Astro islands) | `Mascot`, `Logomark`, `Chart`, `LiveExample`, `SiteHeader`, `SiteFooter`, `ComparisonTable`, `ScrollStage` |
| Docs pages (desktop) | `Landing` (scroll story), `LandingStory` (storyboard), `GettingStarted`, `Examples`, `Playground`, `Api`, `Plugins`, `NotFound` |
| Dark mode and mobile | `LandingDark`, `MobileLanding`, `MobileDocs`, `MobilePlayground`, `MobileNotFound` |
## The design's key choices
- **Mascot:** the 0.x gentleman (top hat, moustache, red waistcoat, easel, hay fork), redrawn. All his colors are custom properties.
- **Palette:** cream became Paper, red became Waistcoat (`#C8102E`), yellow became Mustard (logo tile), warm gray became Ink.
- **Chart series colors:** unchanged from 1.5 (`--ct-series-a` … `-o`), plus an opt-in color-blind-safe theme.
- **Typography:** Zilla Slab (display) and Atkinson Hyperlegible Next (body).
## Where the site differs from the snapshot
- **Code font:** JetBrains Mono instead of Atkinson Hyperlegible Mono. All fonts are self-hosted.
- **Code samples** use the functional API and the real export paths; the design's samples use the 1.x classes and old paths.
- **Charts** are drawn by Chartist. The design's `Chart` component draws them with its own simplified math, as a mockup.
- **Numbers and comparisons** on the landing page come from a dated facts snapshot (`pnpm nx run docs:facts`) and measurements, where the design has placeholders. The design's "Trusted by" logo row became a curated "Used by" list that links to the evidence.
---
### Overview (`packages/chartist/README.md`)
# Chartist
[![npm (next)][npm]][npm-url]
[![Downloads][downloads]][downloads-url]
[![Build status][build]][build-url]
[npm]: https://img.shields.io/npm/v/chartist/next.svg
[npm-url]: https://www.npmjs.com/package/chartist
[downloads]: https://img.shields.io/npm/dm/chartist.svg
[downloads-url]: https://www.npmjs.com/package/chartist
[build]: https://img.shields.io/github/actions/workflow/status/chartist-js/chartist/ci.yml?branch=main
[build-url]: https://github.com/chartist-js/chartist/actions
Simple, responsive charts, drawn in SVG and styled with CSS. Tiny, typed, and happy without a build step.
**[chartist.dev](https://chartist.dev)** · [Getting started](https://chartist.dev/docs/getting-started/) · [API](https://chartist.dev/api/) · [Examples](https://chartist.dev/examples/) · [Plugins](https://chartist.dev/plugins/) · [Changelog](https://github.com/chartist-js/chartist/blob/main/CHANGELOG.md)
> **Coming from Chartist 1?** Your code keeps working. [Coming from 1.x](https://chartist.dev/docs/coming-from-1x/) shows what's new, and the 1.x docs are at [chartist.dev/v1/](https://chartist.dev/v1/).
## Install
```sh
npm install chartist
```
```ts
import { lineChart } from 'chartist';
import 'chartist/styles.css';
lineChart('#chart', {
labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
series: [
[12, 9, 7, 8, 5],
[2, 1, 3.5, 7, 3]
]
});
```
```html
```
No bundler? Chartist is a native ES module:
```html
```
## Why Chartist
- **Style it with CSS.** Plain SVG with predictable classes and custom properties for colors, lines and labels. No theme engine.
- **Responsive, two ways.** Options that change with media queries, or with the chart's own container.
- **Composed charts.** Bars and lines in one chart, on as many axes as you need.
- **Renders anywhere SVG does.** Render on a server, with real SVG text labels, for PDFs, email and images.
- **Extend everything.** Every element passes through an open pipeline you can hook into, and the community's plugins keep working.
- **Tiny and typed.** Written in TypeScript, no dependencies, and you ship only what you import.
## Coming from 1.x
Your 1.x code keeps working: the chart classes draw what they drew before. 1.x events and plugins work with `chartist/compat`. The classes are deprecated, and 3.0 removes them from `chartist`. [Coming from 1.x](https://chartist.dev/docs/coming-from-1x/) explains what changed and how to move to the functions.
## Community wrappers
Chartist needs no wrapper: a chart is a container and a function call, and [Charts in frameworks](https://chartist.dev/docs/frameworks/) has recipes for React, Vue, Angular and Svelte, with server rendering. If you'd rather use a component, the community wraps Chartist for these stacks. Thank you to everyone who built them!
| Stack | Wrapper | Built for |
| ------------- | ----------------------------------------------------------------------------------------------- | ------------ |
| React | [react-chartist](https://github.com/fraserxu/react-chartist) | Chartist 1.x |
| Angular | [ng-chartist](https://github.com/willsoto/ng-chartist) | Chartist 1.x |
| Vue | [vue-chartist](https://github.com/Yopadd/vue-chartist) | Chartist 0.x |
| Node.js | [node-chartist](https://github.com/panosoft/node-chartist) | Chartist 0.x |
| Ember | [ember-cli-chartist](https://github.com/jherdman/ember-cli-chartist) | Chartist 0.x |
| Java (JSF) | [ChartistJSF](https://github.com/hatemalimam/ChartistJSF) | Chartist 0.x |
| Vue 2 | [v-chartist](https://github.com/lakb248/vue-chartist) | Chartist 0.x |
| R | [chartist](https://github.com/yutannihilation/chartist) (htmlwidget) | Chartist 0.x |
| Meteor | [mfpierre:chartist-js](https://github.com/mfpierre/meteor-chartist-js) | Chartist 0.x |
| WordPress | [TablePress Extension: Chartist](https://wordpress.org/plugins/charts-for-tablepress-chartist/) | Chartist 0.x |
| Blazor | [UnlockedData.Chartist.Blazor](https://github.com/unlockeddataltd/UnlockedData.Chartist.Blazor) | Chartist 0.x |
| Angular | [ngx-chartist](https://github.com/affilnost/ngx-chartist) | Chartist 0.x |
| Ruby on Rails | [chartist-rails](https://github.com/AnthonyBobsin/chartist-rails) | Chartist 0.x |
Wrappers built for 1.x run on v2: see [Community wrappers](https://chartist.dev/docs/frameworks/#community-wrappers) for the npm `overrides` entry they need until they allow `chartist@2`. Maintain a wrapper that's missing here? Send a pull request.
## Supported by
[Cube](https://cube.dev) sponsors Chartist's maintenance. Thank you!
## License
Dual-licensed under [MIT](https://github.com/chartist-js/chartist/blob/main/LICENSE-MIT) or [WTFPL](https://github.com/chartist-js/chartist/blob/main/LICENSE-WTFPL), at your choice.
---
### Overview (`packages/essentials/README.md`)
# @chartist-js/essentials
The Chartist additions people ask for most, as layers you add to a chart. They're kept out of the core, so charts that don't use them stay small, and they're made and released together with Chartist.
It holds `axisTitle()`, `targetLine()`, `trendLine()`, `valueLabels()` and `logAxis()` today. More layers and axes follow.
## Install
```sh
npm install @chartist-js/essentials
```
It depends on `chartist`, which npm installs with it. Load its stylesheet after Chartist's:
```ts
import 'chartist/styles.css';
import '@chartist-js/essentials/styles.css';
```
### Without a bundler
Map both packages in an import map, so the package and your page share one copy of Chartist:
```html
```
## Axis titles
`axisTitle()` names an axis. It reserves the room the title needs next to the axis labels, so you don't have to guess a padding, and the title never overlaps the labels:
```ts
import { lineChart } from 'chartist';
import { axisTitle } from '@chartist-js/essentials';
lineChart(
'#chart',
{ labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'], series: [[12, 9, 7, 8, 5]] },
{
layers: {
above: [
axisTitle({ axis: 'x', text: 'Day' }),
axisTitle({ axis: 'y', text: 'Visits' })
]
}
}
);
```
One layer draws one title. On the presets the axes are `x` and `y`; in a composed chart, use the ids you gave the axes:
```ts
import {
autoScaleAxis,
axisGrid,
axisLabels,
cartesianAxes,
chart,
line,
stepAxis
} from 'chartist';
import { axisTitle } from '@chartist-js/essentials';
chart('#chart', {
data: {
labels: ['Jan', 'Feb', 'Mar', 'Apr'],
series: [
[120, 150, 170, 210],
[135, 160, 190, 230]
]
},
axes: cartesianAxes([
{ id: 'month', side: 'bottom', type: stepAxis() },
{ id: 'eur', side: 'left', type: autoScaleAxis() },
{ id: 'usd', side: 'right', type: autoScaleAxis() }
]),
layers: [
axisGrid({ axes: ['month', 'eur'] }),
line({ series: [0], x: 'month', y: 'eur' }),
line({ series: [1], x: 'month', y: 'usd' }),
axisLabels(),
axisTitle({ axis: 'month', text: 'Month', align: 'end' }),
axisTitle({ axis: 'eur', text: 'EUR' }),
axisTitle({ axis: 'usd', text: 'USD', flip: true })
]
});
```
| Option | What it does |
| ------------ | ---------------------------------------------------------------------------------------- |
| `axis` | The id of the axis to name |
| `text` | The title; an empty text draws nothing |
| `align` | `start`, `middle` (default) or `end` along the axis; the start of a Y axis is its bottom |
| `flip` | Left and right titles read from top to bottom instead of from bottom to top |
| `gap` | Space between the title and the axis labels, in px (default 4) |
| `className` | Extra classes for the title |
| `classNames` | `{ title }` replaces the class `ct-axis-title` |
Titles on the same side stack outward in the order of `layers`.
### Styling
The title is an SVG `text` with the classes `ct-axis-title`, `ct-horizontal` or `ct-vertical`, and `ct-start` or `ct-end`. It looks like the axis labels until you say otherwise:
```css
.ct-axis-title {
--ct-axis-title-color: #555;
--ct-axis-title-size: 0.875rem;
font-weight: 600;
}
```
## Target and trend lines
`targetLine()` draws a line across the chart at a value, such as a goal or a limit, with an optional label. `trendLine()` fits a straight line through each series' values (least squares) and draws it in the series' color:
```ts
import { lineChart } from 'chartist';
import { targetLine, trendLine } from '@chartist-js/essentials';
lineChart(
'#chart',
{
labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
series: [[620, 810, 740, 930, 880, 1020]]
},
{
low: 0,
layers: {
above: [targetLine({ value: 1000, label: 'Goal' }), trendLine()]
}
}
);
```
A target line takes `value`, `label`, `className`, the `axis` it's on (a Y axis draws it across, an X axis up and down) and where its label sits. A trend line's node knows its `slope`, `intercept` and `correlation`. On a log axis it's fitted to the logarithms, so it's straight there. Style them with `--ct-target-line-color`, `--ct-target-line-width`, `--ct-target-line-dasharray`, `--ct-trend-line-width` and `--ct-trend-line-dasharray`.
## Value labels
`valueLabels()` writes each value next to its point or bar: above points, past the ends of bars, and in the middle of stacked segments. Labels that don't fit their bar or would leave the chart move to where they fit:
```ts
import { barChart } from 'chartist';
import { valueLabels } from '@chartist-js/essentials';
barChart(
'#chart',
{ labels: ['Q1', 'Q2', 'Q3'], series: [[1250, 1830, 1470]] },
{
layers: {
above: [
valueLabels({
locale: 'en-US',
numberFormat: { style: 'currency', currency: 'USD' }
})
]
}
}
);
```
`format(item)` gets the same item as the `format` of `@chartist-js/tooltips`: `undefined` keeps the default text, `null` draws no label, and `\n` starts a new line. `pointPosition`, `barPosition` and `offset` place the labels, `roles` and `series` pick what gets one. Style them with `--ct-value-label-color`, `--ct-value-label-inside-color` and `--ct-value-label-size`.
## Log axis
`logAxis()` is an axis type for values that span several orders of magnitude. Each power of the base is the same distance from the next, so 100, 1,000 and 10,000 are evenly spaced:
```ts
import { lineChart } from 'chartist';
import { logAxis } from '@chartist-js/essentials';
lineChart(
'#chart',
{
labels: ['2019', '2020', '2021', '2022', '2023', '2024'],
series: [[120, 980, 4100, 36000, 210000, 850000]]
},
{
axisY: {
type: logAxis({ minorTicks: true }),
labelTransform: value => value.toLocaleString('en-US')
}
}
);
```
| Option | What it does |
| ------------ | ------------------------------------------------------------------------------------------ |
| `base` | The base of the logarithm, any number above 1 (default 10) |
| `minorTicks` | Grid lines without labels between the ticks, styled with `--ct-grid-minor-*` (default off) |
The axis's own options work as on the core's axes: `low` and `high` set the range exactly, `ticks` sets the ticks by hand, and `labelTransform` formats the labels. Zero and negative values have no place on a log scale: they're drawn at the start of the axis. Use `null` for a gap. A `trendLine()` on a log axis is fitted to the logarithms, so it's straight on the chart.
## On the server
The layers and the log axis are part of the scene, so they render with `chartist/server` and hydrate like the rest of the chart:
```ts
import { lineChartConfig } from 'chartist';
import { renderToString, toScene } from 'chartist/server';
import { axisTitle } from '@chartist-js/essentials';
const config = lineChartConfig(
{ labels: ['Mon', 'Tue', 'Wed'], series: [[12, 9, 7]] },
{ layers: { above: [axisTitle({ axis: 'y', text: 'Visits' })] } }
);
console.log(renderToString(toScene(config, { width: 600, height: 300 })));
```
`@chartist-js/terminal` draws them too, vertical titles in a column.
## License
MIT or WTFPL, like Chartist. See [chartist.dev](https://chartist.dev/packages/essentials/) for the guides.
---
### Overview (`packages/examples/README.md`)
# @chartist/examples
The Chartist examples, shared by the docs site, the live playground and the visual regression tests (`packages/visual`). Private, never published.
## Example format
Each example is a folder laid out like an `npm create vite` vanilla TypeScript starter (minus `package.json`):
```
//
index.html the chart container and
```
## Your own text
`numberFormat` sets how the default text writes values, as `Intl.NumberFormat` options, and `format` replaces the text. Return `null` for no tooltip:
```ts
import { barChart } from 'chartist';
import { tooltips } from '@chartist-js/tooltips';
barChart(
'#chart',
{ labels: ['Q1', 'Q2', 'Q3'], series: [[1250, 1830, 1470]] },
{
plugins: [
tooltips({ numberFormat: { style: 'currency', currency: 'CHF' } })
]
}
);
barChart(
'#other',
{ labels: ['Q1', 'Q2', 'Q3'], series: [[12, 18, 0]] },
{
plugins: [
tooltips({
format: item =>
item.value === 0
? null
: `${item.label}\n${String(item.value)} orders`
})
]
}
);
```
Content is text, never HTML, so data can't put markup into the page. For markup or a framework's template, `render` fills the tooltip yourself:
```ts
import { lineChart } from 'chartist';
import { tooltips } from '@chartist-js/tooltips';
lineChart(
'#chart',
{ series: [[5, 9, 7]] },
{
plugins: [
tooltips({
render(content, item) {
const value = document.createElement('strong');
value.textContent = String(item.valueIndex);
content.append('Value ', value);
// Return a function to undo it, e.g. to unmount a component.
}
})
]
}
);
```
## Options
| Option | What it does |
| -------------- | ---------------------------------------------------------------------------------- |
| `roles` | The roles that get tooltips: `point`, `bar` and `slice` by default; any role works |
| `format` | The text of a tooltip; `null` for none |
| `render` | Fills the tooltip with your own content; may return a cleanup |
| `numberFormat` | `Intl.NumberFormat` options for the values |
| `position` | `element` (default) at the value, or `pointer` to follow the mouse |
| `keyboard` | One tab stop per chart and arrow keys between values; `false` to turn it off |
| `className` | Extra classes for the tooltip |
## Styling
The tooltip is `.ct-tooltip`, with `.ct-tooltip-title`, `.ct-tooltip-series` and `.ct-tooltip-value`. Change its look with custom properties, on the page or a chart's container:
```css
.my-chart {
--ct-tooltip-background: navy;
--ct-tooltip-color: white;
--ct-tooltip-hide-delay: 500ms;
}
```
It shows in the top layer, so `overflow: hidden` and `z-index` don't cut it off, and it's placed with the CSSOM, so it works under a strict Content Security Policy.
## License
MIT or WTFPL, like Chartist. See [chartist.dev](https://chartist.dev/packages/tooltips/) for the guides.
---
### Overview (`apps/docs/public/v0/README.md`)
# The 0.x docs
These files are the Chartist 0.11 documentation, formerly at
`https://gionkunz.github.io/chartist-js/`. Astro copies them to `/v0/` of the
site as they are. The old URLs redirect to chartist.dev: pages without a
`#hash` to their v2 counterpart, sections without one to the same place
here.
They are not edited by hand beyond the changes listed below. The 0.x
toolchain (Grunt, Assemble, Bower) isn't kept.
## Where they come from
The `gh-pages` branch of `gionkunz/chartist-js` at `c1e49e1` (August 2022),
the last build of the 0.x site. Copied: the six pages (`index.html`,
`getting-started.html`, `examples.html`, `api-documentation.html`,
`plugins.html`, `apidoc/index.html`) and the files they load
(`scripts/all.js`, `styles/`, `images/`, `favicon.ico`, `apidoc/scripts/`,
`apidoc/styles/`).
Not copied, because no page loads them: `bower_components/` (most of the
build's 19 MB), `test-chart.html`, `doc-clean-pull.sh`, `404.html` and
`robots.txt`.
## What changed
- **Removed** the "Get awesome Dashboard Templates by Creative Tim" section
of the home page, its `.affiliate-project*` CSS and its three images on
S3; the Google Analytics snippet on every page; the version notice pop-up
added in 2022 (its markup, CSS and script); and the html5shiv script for
IE 8 in `apidoc/index.html`, whose host is gone.
- **Fonts are served from `fonts/`** instead of Google Fonts and cdnjs: the
WebFont loader snippet on each page is replaced by a link to
`fonts/fonts.css`, which loads Oxygen 300/400/700 and Source Code Pro
400/700 (SIL OFL 1.1, latin subset from fontsource) and Font Awesome
4.1.0. Their licenses are next to them. With this, no page makes a request
to another host.
- **Added** a note at the top of each page: "This is the archived
documentation of Chartist 0.11. The current docs are at chartist.dev." Its
`${renderToString(scene)}`);
// The computed values of every element, in document order.
const values = await page.$$eval(
'svg, svg *',
(elements, names) =>
elements.map(element => {
const style = getComputedStyle(element);
return Object.fromEntries(
names.map(name => [name, style.getPropertyValue(name)])
);
}),
properties
);
// The scene's nodes are in the same order.
const nodes: SceneNode[] = [];
const visit = (node: SceneNode) => {
nodes.push(node);
node.children.forEach(visit);
};
visit(scene);
const byNode = new Map(nodes.map((node, index) => [node, values[index]]));
return node => byNode.get(node);
} finally {
await browser.close();
}
}
// const styled = applyStyles(scene, await browserStyles(scene, css));
```
It costs a browser on your server, and it's slower: use it when the small engine doesn't cover your CSS.
**Pass only your own CSS.** The values end up in the markup, `url()` included.
They're written as escaped attribute values, so CSS can't add elements, but
treat a stylesheet like code: pass only the ones your application controls,
never one from a user.
**Plugins run on the server too.** `toScene()` installs the config's plugins
and calls their listeners, up to the `scene` phase. Plugins that change the
scene work there unchanged; listeners of `render` and `mount` never run, and
calling `update()`, `detach()` or `destroy()` throws. 1.x plugins converted
with `fromLegacyPlugin` don't run there: their `draw` and `created` events
come from the `mount` phase. See [Events and plugins](../events-and-plugins/).
In the API reference: [rendering](../../api/rendering/) and [chartist/server](../../api/server/).
Next: keep a server-rendered chart running in the page with [SSR with hydration](../ssr-hydration/).
---
### Apps Docs Src Content Docs Sizing Charts (`apps/docs/src/content/docs/sizing-charts.mdx`)
---
title: Sizing charts
description: Give a chart a responsive aspect ratio with a class, a fixed size with options, or any size CSS can describe. Chartist fills the box and redraws when it changes.
group: Basics
order: 3
---
import Callout from '../../components/docs/Callout.astro';
import LiveExample from '../../components/LiveExample.astro';
export const data = {
labels: ['Q1', 'Q2', 'Q3', 'Q4'],
series: [
[5, 4, 3, 7],
[3, 2, 9, 5]
]
};
A chart fills its container. It measures the box, draws an SVG of that size, and draws again when the box changes. So sizing a chart means sizing its container, and you have three ways to do it: an aspect ratio class, fixed options, or your own CSS.
## Aspect ratios
Images and videos on a responsive page keep their proportions as they scale: they're 4:3 or 16:9, not 320 by 240 pixels. Charts should too. Add a ratio class to the container, and the chart is as wide as its parent and as tall as the ratio says:
```html
```
No `width` or `height` in the options. Press **Edit**, then try another class in `index.html`:
The classes come with `chartist/styles.css` and are named after musical intervals, from a square to four times as wide as tall:
| Class | Width : height |
| ------------------- | -------------- |
| `ct-square` | 1 : 1 |
| `ct-minor-second` | 16 : 15 |
| `ct-major-second` | 9 : 8 |
| `ct-minor-third` | 6 : 5 |
| `ct-major-third` | 5 : 4 |
| `ct-perfect-fourth` | 4 : 3 |
| `ct-perfect-fifth` | 3 : 2 |
| `ct-minor-sixth` | 8 : 5 |
| `ct-golden-section` | 1.618 : 1 |
| `ct-major-sixth` | 5 : 3 |
| `ct-minor-seventh` | 16 : 9 |
| `ct-major-seventh` | 15 : 8 |
| `ct-octave` | 2 : 1 |
| `ct-major-tenth` | 5 : 2 |
| `ct-major-eleventh` | 8 : 3 |
| `ct-major-twelfth` | 3 : 1 |
| `ct-double-octave` | 4 : 1 |
Need another ratio? With Sass, the `$ct-scales` and `$ct-scales-names` settings define the list (keep them the same length); see [Sass](../styling-with-css/#sass).
## Fixed sizes
Sometimes a chart has a fixed spot: a 300 by 200 pixel card, a print layout. Set `width` and `height` in the options:
```ts
import 'chartist/styles.css';
import { lineChart } from 'chartist';
lineChart(
'#chart',
{
labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
series: [[12, 9, 7, 8, 5]]
},
{ width: 300, height: 200 }
);
```
A number is pixels. A string can be any CSS length, `'20rem'` or `'50%'`: Chartist sets it on the SVG and measures what the browser makes of it. You can fix one side and leave the other to the container.
## Your own CSS
The ratio classes are one way to give the container a size; anything that does is fine. A height in CSS works:
```css
#chart {
height: 240px;
}
```
So does CSS `aspect-ratio`, with one line you must not forget:
```css
#chart {
aspect-ratio: 16 / 9;
min-height: 0;
}
```
**`aspect-ratio` needs `min-height: 0`.** To measure the container, Chartist
places a probe SVG of 100% width and height in it. An `aspect-ratio` box can
grow with its content, probe included, and then the chart comes out too tall.
`min-height: 0` stops that. The `ct-*` classes don't use `aspect-ratio` and
aren't affected.
A container with no height of its own, like an empty `div`, gets a chart 150 pixels tall: the browser's default height for an SVG. If a chart comes out that height whatever you do, the container's height is the place to look.
## More than one chart on a page
Every chart needs its own container. A selector string draws into the first element that matches it, so give each container an id:
```html
```
```ts
import 'chartist/styles.css';
import { barChart, lineChart } from 'chartist';
lineChart('#visits', {
labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
series: [[12, 9, 7, 8, 5]]
});
barChart('#revenue', {
labels: ['Q1', 'Q2', 'Q3', 'Q4'],
series: [[5, 4, 3, 7]]
});
```
Or pass the elements themselves, for example to draw one chart per card:
```ts
import 'chartist/styles.css';
import { lineChart } from 'chartist';
for (const element of document.querySelectorAll('.sparkline')) {
lineChart(element, {
series: [[3, 5, 2, 6, 4]]
});
}
```
## What happens on resize
Nothing you need to wire up. Chartist watches its container with a `ResizeObserver` and redraws when the size changes, whether the window was resized, a sidebar collapsed or the layout moved the chart. A chart with a fixed `width` and `height` keeps its size.
To change what the chart draws at a new size, not only how big it is, use [responsive options](../responsive/). To stop watching, call `detach()` on the chart; see [Live updates](../live-updates/#detach-and-destroy).
In the API reference: [`width`](../../api/charts/#LineChartPresetOptions.width), [`height`](../../api/charts/#LineChartPresetOptions.height) and [`chartPadding`](../../api/charts/#LineChartPresetOptions.chartPadding).
Next: [style your charts with CSS](../styling-with-css/).
---
### Apps Docs Src Content Docs Ssr Hydration (`apps/docs/src/content/docs/ssr-hydration.mdx`)
---
title: SSR with hydration
description: Render a chart into the server's HTML and let the browser take it over, keeping its elements, with live updates, plugins and animations from there on.
group: Advanced
order: 5
---
import Callout from '../../components/docs/Callout.astro';
import Diagram from '../../components/docs/Diagram.astro';
import LiveExample from '../../components/LiveExample.astro';
import flow from '../../diagrams/ssr-hydration/flow.mmd?raw';
export const data = {
labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
series: [
[12, 9, 7, 8, 5],
[2, 1, 3.5, 7, 3]
]
};
A chart in the server's HTML shows up with the page's first paint, before any script loads. With hydration, the browser then takes that chart over instead of drawing it again: the chart keeps the server's elements and gets updates, plugins and animations from there on.
The server renders the chart with `renderForHydration()`, and the browser creates the chart in the same container with `liveDomRenderer()`. For a static picture of a chart (files, PDFs, email), use the self-contained SVG image from [Server rendering](../server-rendering/) instead.
**Only `liveDomRenderer()` hydrates.** It comes from `chartist/live` and
keeps the server's elements. With the default renderer, the chart draws a
new svg over the server's: that works, but the elements are new, so a CSS
animation that started with the page starts again.
`liveDomRenderer({ adopt: false })` draws a new svg too. 1.x classes and
charts with plugins converted with `fromLegacyPlugin` always draw a new svg.
## On the server and in the browser
On the server, render the chart's markup into its container:
```ts
import { lineChartConfig } from 'chartist';
import { renderForHydration } from 'chartist/server';
const data = {
labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
series: [[12, 9, 7, 8, 5]]
};
// On the server, inside the chart's container:
…
export const markup = renderForHydration(lineChartConfig(data), {
width: 600,
height: 300
});
```
In the browser, create the chart in that container, with the same data and options:
```ts
import { lineChart } from 'chartist';
import { liveDomRenderer } from 'chartist/live';
const data = {
labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
series: [[12, 9, 7, 8, 5]]
};
// The chart keeps the server's svg and its elements.
const chart = lineChart('#chart', data, { renderer: liveDomRenderer() });
chart.update({ data: { ...data, series: [[3, 9, 7, 8, 11]] } });
```
The browser doesn't read the data from the markup: it builds the same scene again from its own config, at the size the server recorded, and binds it to the server's elements. From there on, it's a chart like any other.
The example's page holds the server markup in its `index.html`, so you see the server's chart first. **Hydrate** creates the chart, which a real page does right away. Below the chart, the example counts what each render did and how many of the server's elements are still there. **New values** updates the chart: values move, and when the axis needs other ticks, grid lines and labels are added and removed.
## The hydrate render
The takeover is the chart's first render: `render` and `mount` run with the cause `hydrate`, and `mount` gets the server's elements as added, so plugins work on them as on a first render. The events also carry `hydration.repaired`: how many attributes, classes and texts of the markup differed from what the browser built, and were set. It's 0 when the server and the browser drew the same data and options. Log it in development to catch the two drifting apart:
```ts
import { lineChart } from 'chartist';
import { liveDomRenderer } from 'chartist/live';
lineChart(
'#chart',
{ labels: ['Mon', 'Tue', 'Wed'], series: [[12, 9, 7]] },
{
renderer: liveDomRenderer(),
on: {
mount: ({ cause, hydration }) => {
if (cause === 'hydrate' && hydration?.repaired) {
console.warn(`The server drew ${hydration.repaired} differences`);
}
}
}
}
);
```
### What causes repairs
Anything that makes the server and the browser draw different values:
- **Data that changed in between.** The browser fetched it again, or the data has a timestamp or a random value.
- **Formatting that depends on the environment.** A `labelTransform` with `toLocaleString()` or `Intl` formats for the server's locale and time zone, the browser for the reader's: the label texts differ.
- **Options or plugins on one side only.** A class, a `low` or a plugin that changes the scene only in the browser. (Plugins that act in `mount` don't count: they run after the takeover.)
- **A custom `measureText` on the server**, with SVG labels: the browser replays with the built-in estimate, so label positions differ.
The chart shows the browser's values, so readers see the right chart either way. Styles don't count: the markup leaves them out on purpose (see [Styles and text](#styles-and-text)).
A different structure can't be repaired: another number of points or series, or an axis with other ticks because the values span another range. Then the chart warns, names the first element that differs and draws a new svg in place of the server's.
## Choosing the server's size
A server has no container to measure, so it lays the chart out at the size you give it and records that size. The markup's svg is `100%` wide and high (unless the config sets a size), with a `viewBox` of the server's size, so the drawing scales into its container until the chart runs. Then the chart lays itself out at the container's real size.
How close the two sizes are decides what readers see at the takeover:
- **The same size:** nothing is drawn again. The chart keeps the server's layout, and the takeover is invisible.
- **A narrower container:** before the chart runs, the whole drawing is scaled down, text and lines included: a 600 px wide layout in a 343 px phone column shows 12 px labels at about 7 px. At the takeover, the chart lays out again at 343 px, so the labels get their real size and the points, grid lines and labels move. An auto-scaled axis can also get fewer ticks, since it keeps them at least `scaleMinSpace` px apart.
- **A wider container:** the same, scaled up before the takeover.
The elements stay either way: the chart changes them instead of drawing new ones. That relayout isn't animated, even with `smilAnimations()`, since the drawing's scale changes in the same step. Responsive options apply only from the takeover on too, since the server draws without them.
### The server can't know the width
A request doesn't say how wide the reader's window is, so the server has to pick one size for everyone:
- **The width your layout gives the chart most often**, for example its column on a desktop, or a phone's width if most of your readers come on phones. A static site, built once for every reader, can only do this.
- **A size per device**, if your server renders per request. [Client hints](https://developer.mozilla.org/en-US/docs/Web/HTTP/Client_hints) like `Sec-CH-Viewport-Width` say it, but only Chromium browsers send them, and only after the server asked with `Accept-CH`, so not on a first visit. A cookie from an earlier visit works in every browser, from the second visit on. Either way, the page then varies per reader, so caches need to know (`Vary`).
HTML labels that move at the takeover count as a small layout shift (CLS), around 0.002 to 0.03 in our tests; SVG labels don't.
### Give the container a size
Give the container a height or an `aspect-ratio` that matches the server's size, and make the svg a block, as for every chart that fills its container:
```css
#chart {
aspect-ratio: 2 / 1;
}
#chart svg {
display: block;
}
```
With a matching `aspect-ratio`, the server's drawing fills the container exactly; with another one, it sits letterboxed inside it until the takeover. Without a height, the server markup looks right, but the chart collapses to 150 px once it runs, as it would without server rendering. See [Sizing charts](../sizing-charts/).
## Styles and text
Hydration markup has no `style` attributes. Chartist's stylesheet sizes the label boxes and the root's attributes size the svg; a donut's `donutWidth` becomes a `stroke-width` attribute. So the markup looks the same before and after the takeover, and it passes a policy of `style-src 'self'` (see [Security and CSP](../security-and-csp/)). Load Chartist's stylesheet in the page, as for every chart. Styles that your `scene` listeners add appear only once the chart runs: for what should show before, use classes and CSS.
Use the built-in text estimate on the server, without a `measureText`: the browser replays the server's layout with it.
## Render the markup once
The chart owns its svg after the takeover. Code that writes the server markup into the container again, as some frameworks' raw-HTML features do when a page updates, leaves the chart drawing into an svg that's no longer on the page. Chartist warns on its next render and draws a new svg, but the fix is to render the markup into the container only once. [Charts in frameworks](../frameworks/) shows how, in React, Vue, Angular and Svelte.
In the API reference: [rendering](../../api/rendering/).
Next: [charts in frameworks](../frameworks/).
---
### Apps Docs Src Content Docs Styling With Css (`apps/docs/src/content/docs/styling-with-css.mdx`)
---
title: Styling with CSS
description: Chartist draws plain SVG with predictable classes, so you style charts with the CSS you already write, from one custom property to a full theme.
group: Basics
order: 4
---
import Callout from '../../components/docs/Callout.astro';
import LiveExample from '../../components/LiveExample.astro';
export const data = {
labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
series: [
[12, 9, 7, 8, 5],
[2, 1, 3.5, 7, 3]
]
};
Chartist has no theme option, and no color settings in JavaScript. Charts are SVG elements with predictable class names, and their look lives in CSS, next to the rest of your styles. When the brand color changes, you change one line in a stylesheet, not every chart's options.
There are three ways in, from quick to complete: custom properties for the common things, plain selectors for everything else, and Sass if you want to build your own stylesheet.
## Custom properties
The default stylesheet, `chartist/styles.css`, reads its values from custom properties and falls back to the classic Chartist look. Set one, and every chart in its scope follows. Press **Edit** and try other values:
| Property | Default | What it sets |
| --------------------------------- | --------------------- | ------------------------------------ |
| `--ct-series-a` … `--ct-series-z` | the 15 classic colors | The color of each series, in order |
| `--ct-line-width` | `4px` | Line thickness |
| `--ct-line-dasharray` | `none` | Dashed lines |
| `--ct-point-size` | `10px` | Point size |
| `--ct-point-shape` | `round` | `round` or `square` points |
| `--ct-area-opacity` | `0.1` | Opacity of the area below a line |
| `--ct-bar-width` | `10px` | Bar thickness |
| `--ct-donut-width` | `60px` | Donut ring thickness |
| `--ct-grid-color` | `rgba(0, 0, 0, 0.2)` | Grid lines |
| `--ct-grid-width` | `1px` | Grid line thickness |
| `--ct-grid-dasharray` | `2px` | Grid dashes (`none` for solid lines) |
| `--ct-grid-background-fill` | `none` | Fill behind the grid |
| `--ct-grid-minor-color` | `rgba(0, 0, 0, 0.08)` | Minor grid lines, between the ticks |
| `--ct-grid-minor-width` | `1px` | Minor grid line thickness |
| `--ct-grid-minor-dasharray` | `none` | Minor grid dashes |
| `--ct-label-color` | `rgba(0, 0, 0, 0.4)` | Axis and slice labels |
| `--ct-label-size` | `0.75rem` | Label font size |
A donut's `donutWidth` option wins over `--ct-donut-width`. Without it, the chart lays the ring out for the width the stylesheet draws. A server render has no stylesheet to read and lays it out for 60 px, so set `donutWidth` there. More in [Pie and donut charts](../pie-and-donut-charts/#donuts).
They're regular custom properties, so they cascade. Set them where they should apply:
```css
/* The whole site */
:root {
--ct-series-a: #c8102e;
}
/* Every chart in the sidebar */
.sidebar {
--ct-line-width: 2px;
}
/* One chart */
#revenue {
--ct-grid-dasharray: none;
}
```
### Dark pages
Labels and grid lines follow the page's color scheme: where `color-scheme: dark` applies, they turn light. Declare it on the page or on the chart's container; the OS setting alone doesn't change anything, since a light page should keep its colors in dark mode:
```css
:root {
color-scheme: light dark;
}
```
`--ct-label-color` and `--ct-grid-color` still win. The series colors stay as they are; for colors that are clear on both, use the [accessible theme](#colors-for-everyone).
## One color per series
Each series is a group with a letter class: the first is `ct-series-a`, the second `ct-series-b`, up to `ct-series-z`, and the 27th starts again at `ct-series-a`. The letter class sets `--ct-color`, and the series' lines, points, bars, areas and slices use it as their stroke or fill. There are 15 colors, so from the 16th series they repeat: `ct-series-p` gets the first series' color and follows `--ct-series-a`, unless you set `--ct-series-p`. That gives you two levels to work at:
```css
/* Recolor the second series everywhere */
:root {
--ct-series-b: #f4c63d;
}
/* Or recolor one series in one chart */
#sales .ct-series-a {
--ct-color: #9a6a45;
}
```
Want a meaningful name instead of a letter? Give the series a `className`. It replaces the letter class, so the series has no default color and takes the one you give it:
```ts
import 'chartist/styles.css';
import { lineChart } from 'chartist';
lineChart('#chart', {
labels: ['Q1', 'Q2', 'Q3', 'Q4'],
series: [
{ className: 'revenue', data: [5, 7, 6, 9] },
{ className: 'costs', data: [3, 4, 4, 5] }
]
});
```
```css
.revenue {
--ct-color: #b07800;
}
.costs {
--ct-color: #d70206;
}
```
**Stroke or fill?** SVG colors lines with `stroke` and shapes with `fill`.
Setting `--ct-color` covers both, which is why it's the easiest way to recolor
a series.
## Plain selectors for the rest
Custom properties cover the common cases. For anything else, write CSS against the classes Chartist draws:
| Element | Classes |
| -------------------- | ----------------------------------------------------------------------------------------------------- |
| The chart's SVG | `ct-chart-line`, `ct-chart-bar` (plus `ct-horizontal-bars`), `ct-chart-pie`, `ct-chart-donut` |
| A series | `ct-series` and `ct-series-a` … (or its `className`) |
| Lines, points, areas | `ct-line`, `ct-point`, `ct-area` |
| Bars | `ct-bar` |
| Slices | `ct-slice-pie`, `ct-slice-donut` |
| Grid | `ct-grids` (the group), `ct-grid`, with `ct-horizontal` or `ct-vertical` |
| Labels | `ct-labels` (the group), `ct-label`, with `ct-horizontal` or `ct-vertical` and `ct-start` or `ct-end` |
Anything SVG and CSS can do works here: transitions, hover states, filters.
```css
/* Square bar ends and a hover highlight */
.ct-bar {
stroke-linecap: square;
transition: opacity 0.2s;
}
.ct-series:hover .ct-bar {
opacity: 0.6;
}
/* Only horizontal grid lines */
.ct-grid.ct-horizontal {
display: none;
}
```
## Colors for everyone
The classic colors are kept for compatibility, and some of their pairs are hard to tell apart for people with color vision deficiencies. Chartist ships an opt-in palette checked for that, with light and dark variants:
```ts
import 'chartist/styles.css';
import 'chartist/themes/accessible.css';
```
```html
…
```
Add the class to the page or to one chart's container. The palette follows the element's `color-scheme`, so it switches with your dark mode as long as your dark theme declares `color-scheme: dark`.
**Dark mode for labels and grid.** The default label and grid colors are
translucent black. In a dark theme, set `--ct-label-color` and
`--ct-grid-color` to light values alongside your other dark colors.
## Sass
If your build already uses Sass, configure the stylesheet at its source instead of overriding it. Every setting is a `!default` variable:
```scss
@use 'chartist/scss/index' with (
$ct-series-names: (
a,
b,
c
),
$ct-series-colors: (
#9a6a45,
#f4c63d,
#c8102e
),
$ct-line-width: 2px,
$ct-grid-dasharray: false
);
```
With fewer colors than names, the colors repeat in order, as in the default stylesheet. The custom properties still work on top of the compiled CSS. Set `$ct-include-classes: false` to emit nothing and use the `ct-chart-*` mixins in your own selectors.
In the API reference: [`classNames`](../../api/charts/#LineChartPresetOptions.classNames), to use class names of your own.
Next: [make charts respond to the screen and their container](../responsive/), or [animate them with CSS](../animations/).
---
### Apps Docs Src Content Docs Why Chartist (`apps/docs/src/content/docs/why-chartist.mdx`)
---
title: Why Chartist?
description: Chartist draws simple, responsive charts as SVG and leaves styling, interaction and the rest to the web platform. Here's what that means for you.
group: Start here
order: 2
---
import Callout from '../../components/docs/Callout.astro';
import LiveExample from '../../components/LiveExample.astro';
export const coffee = {
labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
series: [[3, 4, 2, 5, 6, 2, 1]]
};
Chartist has one job: turn your data into a clean, responsive SVG chart. Everything the browser already does well (styling, events, animation, layout) it leaves to the browser. That's a choice, and it shapes everything else on this site.
## SVG in the DOM
A Chartist chart is an inline `
