# Chartist

> Simple, responsive charts drawn in SVG and styled with CSS. Tiny, typed, and happy without a build step.

Chartist draws responsive SVG charts and leaves their look to CSS. This is Chartist v2, a TypeScript library with no dependencies, available from npm (`chartist`) or as ES modules from a CDN, without a build step.

When writing Chartist code:

- Create charts with the functions: `lineChart(target, data, options)`, `barChart(…)` and `pieChart(…)` for the classic chart types, and `chart({ data, axes, layers })` for composed charts (bars and lines together, several axes). Import them from `chartist`, and the default styles with `import 'chartist/styles.css'`.
- Don't write `new Chartist.Line(…)`, `new LineChart(…)` or `Chartist.Interpolation`: that's the 1.x and 0.x API. The 1.x classes are deprecated and leave `chartist` in 3.0; they still work, for compatibility only.
- Style charts with CSS and custom properties (`--ct-series-a`, `--ct-line-width`, …), not with options.
- Change what a chart draws with plugins: listeners on the pipeline's phase events (`compose` for scene nodes, `mount` for the DOM). 1.x `draw` events need the `compat` plugin from `chartist/compat`.
- Size charts with their container (CSS), and use responsive options for what changes with the size.
- For charts that update while people look at them, pass `renderer: liveDomRenderer()` from `chartist/live`: the chart keeps its SVG and changes it in place. Set up elements on the `add` changes in `mount`, not on every render.
- Packages under `@chartist-js` (listed below) take the same data and options: `@chartist-js/terminal` draws charts as terminal text or HTML text art, `@chartist-js/essentials` adds layers such as `axisTitle()`, and `@chartist-js/tooltips` adds tooltips for mouse, touch and keyboard.

## Docs

- [Getting started](https://chartist.dev/docs/getting-started.md): Your first chart in about two minutes. No build step, no bundler, no framework. An HTML file and a browser.
- [Why Chartist?](https://chartist.dev/docs/why-chartist.md): 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.
- [Coming from 1.x](https://chartist.dev/docs/coming-from-1x.md): Your Chartist 1.x charts keep running on v2. Here's what stays the same, what's new, and how to move to the functions one chart at a time.
- [Line charts](https://chartist.dev/docs/line-charts.md): Lines, areas and points with lineChart(), from smoothing and gaps in your data to scatter plots and edge-to-edge lines.
- [Bar charts](https://chartist.dev/docs/bar-charts.md): Grouped, stacked, horizontal and distributed bars with barChart(), and how to space them.
- [Pie and donut charts](https://chartist.dev/docs/pie-and-donut-charts.md): Pies, donuts and gauges with pieChart(), from the data shape to label placement, slice colors and half-circle gauges.
- [Composed charts](https://chartist.dev/docs/composed-charts.md): Build charts from axes and layers with chart(), for bars and a line on two Y axes, axes on any side and anything the presets don't cover.
- [Data and options](https://chartist.dev/docs/data-and-options.md): What a chart's data looks like, from plain arrays to named series with metadata, and how options set defaults for every series or just one.
- [Axes and scales](https://chartist.dev/docs/axes-and-scales.md): Step axes, auto-scaled and fixed axes, XY plots with two-dimensional data, label formatting, and how the presets pick their axes.
- [Sizing charts](https://chartist.dev/docs/sizing-charts.md): 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.
- [Styling with CSS](https://chartist.dev/docs/styling-with-css.md): 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.
- [Responsive sugar topping](https://chartist.dev/docs/responsive.md): Change what a chart draws, not only its size, with media queries per chart, and experimentally with container queries.
- [Animations](https://chartist.dev/docs/animations.md): Draw lines in, grow bars and reveal charts on scroll with CSS, reach for SMIL where CSS can't go, animate updates, and respect people who prefer less motion.
- [Bands](https://chartist.dev/docs/bands.md): Shade ranges on line and bar charts with the band() layer, between two series, around a group or at fixed values, and mark the values in or out of them.
- [Live updates](https://chartist.dev/docs/live-updates.md): Give a chart new data through its handle, and let it keep its SVG with liveDomRenderer(), so elements stay, plugins keep what they added and updates can animate.
- [Events and plugins](https://chartist.dev/docs/events-and-plugins.md): Every chart is built in phases, and each phase is an event you can listen to and change. Plugins package those listeners so you can share them.
- [Custom layers](https://chartist.dev/docs/custom-layers.md): Write your own layers for chart() and the presets, from drawing to binding axes and series, widening axes and refining what other layers drew.
- [Server rendering](https://chartist.dev/docs/server-rendering.md): Build a chart's scene without a browser and turn it into SVG markup, for server-rendered pages, PDFs, email and images.
- [SSR with hydration](https://chartist.dev/docs/ssr-hydration.md): 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.
- [Charts in frameworks](https://chartist.dev/docs/frameworks.md): Use Chartist in React, Vue, Angular and Svelte, with the chart rendered on the server and taken over in the browser.
- [Security and CSP](https://chartist.dev/docs/security-and-csp.md): Run Chartist on pages with a strict Content Security Policy or Trusted Types, and keep the data in your charts from injecting markup.

## API reference

- [The whole reference and guides in one file](https://chartist.dev/llms-full.txt)
- [Charts](https://chartist.dev/api/charts.md): lineChart, barChart and pieChart: a chart from data and options, with the 1.x options and output.
- [chart()](https://chartist.dev/api/chart.md): The composable chart: data, axes and layers in one config, and the handle it returns.
- [Layers](https://chartist.dev/api/layers.md): What chart() draws: lines, bars, pies, grids and labels, each a layer over the same data.
- [Scales and axes](https://chartist.dev/api/scales.md): Axes that turn values into positions: step, auto-scaled and fixed, placed on any side.
- [Scene](https://chartist.dev/api/scene.md): The scene a chart composes before rendering: nodes, their roles and data, and how to find and change them.
- [Events and plugins](https://chartist.dev/api/events-and-plugins.md): The pipeline phases, their events and payloads, custom events, and the plugin shape.
- [Rendering](https://chartist.dev/api/rendering.md): From scene to output: renderers, text measuring, and rendering on the server.
- [Responsive](https://chartist.dev/api/responsive.md): Options that change with media queries or with the size of the chart’s container.
- [Data](https://chartist.dev/api/data.md): The shapes of chart data: series, values, labels and meta, as given and as normalized.
- [SVG and animation](https://chartist.dev/api/svg.md): The small SVG toolkit behind the charts: elements, paths, SMIL animations, easings and line interpolation.
- [chartist/compat](https://chartist.dev/api/compat.md): The 1.x events (data, draw, created, …) and 1.x plugins on the functional API.
- [chartist/live](https://chartist.dev/api/live.md): Live updates: the renderer that changes a chart’s SVG in place, the keyed diff, and SMIL update animations.
- [chartist/server](https://chartist.dev/api/server.md): Charts as markup without a DOM: SVG strings, markup the browser takes over, and stylesheets written into the SVG for images and PDFs.
- [1.x classes](https://chartist.dev/api/classes.md): LineChart, BarChart and PieChart as in 1.x, with their options, axis classes, events and drawing helpers. Deprecated, and removed from chartist in 3.0: new code uses the chart functions.
- [Helpers](https://chartist.dev/api/helpers.md): The data, math and utility functions the charts are built from, for plugins and custom layers.

## Packages

### @chartist-js/terminal

- [@chartist-js/terminal](https://chartist.dev/packages/terminal.md): Chartist charts in the terminal and as text art in HTML, from the ct-cli command or from your own CLI tool.

- [Terminal rendering](https://chartist.dev/packages/terminal/terminal-rendering.md): Draw charts from the ct-cli command or from your own CLI tool, and as text art in HTML, with the data and options of Chartist's presets.

- [Customizing charts](https://chartist.dev/packages/terminal/customizing-charts.md): Interpolation, axes, options per series, stacked bars and gauges. Chartist's options change the text art the way they change the SVG.

- [Plugins](https://chartist.dev/packages/terminal/plugins.md): Plugins and layers change the scene, and the terminal draws the scene. A plugin that adds lines, circles and text works in the terminal as it does in SVG.

- [@chartist-js/terminal API](https://chartist.dev/packages/terminal/api.md): Every function and type @chartist-js/terminal exports, generated from its TypeScript source.

### @chartist-js/essentials

- [@chartist-js/essentials](https://chartist.dev/packages/essentials.md): The additions people ask for most, as layers you add to a chart, kept out of the core so charts without them stay small.

- [Axis titles](https://chartist.dev/packages/essentials/axis-titles.md): Name an axis on any side of the chart. The title reserves its own room, so it never overlaps the labels.

- [Target lines](https://chartist.dev/packages/essentials/target-lines.md): Draw goals, limits and averages across a chart with targetLine(), on a preset or in a composed chart, horizontal or vertical.

- [Trend lines](https://chartist.dev/packages/essentials/trend-lines.md): Fit a straight line through each series with trendLine(), read how well it fits, and draw exponential trends on a log axis.

- [Value labels](https://chartist.dev/packages/essentials/value-labels.md): Write each value next to its point or bar with valueLabels(), format the text like a tooltip's, and let labels that don't fit move to where they do.

- [Log axis](https://chartist.dev/packages/essentials/log-axis.md): A logarithmic scale for values that span several orders of magnitude, with ticks at the powers of ten, minor grid lines and straight trend lines for exponential growth.

- [@chartist-js/essentials API](https://chartist.dev/packages/essentials/api.md): Every function and type @chartist-js/essentials exports, generated from its TypeScript source.

### @chartist-js/tooltips

- [@chartist-js/tooltips](https://chartist.dev/packages/tooltips.md): Tooltips for mouse, touch and keyboard that show a value's label, series and number, stay on their value while the chart updates, and take their looks from CSS.

- [Content and styling](https://chartist.dev/packages/tooltips/content-and-styling.md): Your own text with format, your own markup or a framework's template with render, numbers, roles, positions, live charts and the custom properties of the tooltip.

- [@chartist-js/tooltips API](https://chartist.dev/packages/tooltips/api.md): Every function and type @chartist-js/tooltips exports, generated from its TypeScript source.

## Plugins

- [Plugins](https://chartist.dev/plugins.md): Community plugins: legends, zoom, thresholds and more
- [Legend](https://chartist.dev/plugins/chartist-plugin-legend.md): Adds a legend from the series names. Click an entry to hide or show its series.
- [Hover](https://chartist.dev/plugins/chartist-hover.md): Calls your functions when the pointer enters or leaves a point, so you can show the value anywhere you like.
- [Zoom](https://chartist.dev/plugins/chartist-plugin-zoom.md): Drag a box over a line chart to zoom into it, and reset the zoom from your own button.
- [Fill donut](https://chartist.dev/plugins/chartist-plugin-fill-donut.md): Draws a copy of the donut behind it, so an animated donut looks filled from the start, and puts HTML labels in or around it. Together they make gauges.
- [Accessibility](https://chartist.dev/plugins/chartist-plugin-accessibility.md): Adds a visually hidden table with the data, a caption and a summary, so screen reader users get the numbers.
- [Threshold](https://chartist.dev/plugins/chartist-plugin-threshold.md): Splits lines and bars at a value and gives the parts above and below their own classes to style.

## Examples

### Line charts

- [Simple line chart](https://chartist.dev/examples/line/simple.md): Three series, Monday to Friday, stretched to the full width.

- [Line chart with area](https://chartist.dev/examples/line/area.md): One series drawn as a line with the area below it filled down to zero.

- [Auto scale axis](https://chartist.dev/examples/line/axis-auto.md): A halving series on an auto scale x axis that only uses whole numbers.

- [Fixed and auto scale axis](https://chartist.dev/examples/line/axis-fixed-and-auto.md): A step line on an auto scale x axis and a fixed y axis with hand-picked ticks.

- [Bi-polar Line chart with area only](https://chartist.dev/examples/line/bipolar-area.md): Four series swinging above and below zero, drawn as filled areas only.

- [Holes in data](https://chartist.dev/examples/line/data-holes.md): Series with missing values, where each line breaks at every hole.

- [Filled holes in data](https://chartist.dev/examples/line/data-fill-holes.md): Series with missing values, bridged by a cardinal spline that fills the holes.

- [Using events to replace graphics](https://chartist.dev/examples/line/modify-drawing.md): A plugin swaps every point for a triangle while the chart is composed.

- [Only whole numbers](https://chartist.dev/examples/line/only-integer.md): Four series between -3 and 3 on a y axis that only labels whole numbers.

- [SVG Path animation](https://chartist.dev/examples/line/path-animation.md): Lines and areas of three series grow from the bottom, one series after the other.

- [Line scatter diagram with responsive settings](https://chartist.dev/examples/line/scatter-random.md): Four series of random points over 52 weeks, with more week labels on wider screens.

- [Series Overrides](https://chartist.dev/examples/line/series-override.md): Three named series, each with its own interpolation, area or points.

- [Simple responsive options](https://chartist.dev/examples/line/simple-responsive.md): A growing series whose labels shorten and whose points or line hide as the screen narrows.

- [Line Interpolation / Smoothing](https://chartist.dev/examples/line/simple-smoothing.md): Two series with large jumps, drawn with simple smoothing instead of a cardinal spline.

- [Simple SMIL Animations](https://chartist.dev/examples/line/simple-svg-animation.md): Points of two series fade and slide in one after the other, replayed every eight seconds.

- [Advanced SMIL Animations](https://chartist.dev/examples/line/svg-animation.md): Grid lines, labels, points and lines of four series fly in one after the other.

- [Timeseries](https://chartist.dev/examples/line/timeseries.md): Two series of dated values on a fixed scale X axis with six month and day labels.

### Bar charts

- [Bi-polar bar chart](https://chartist.dev/examples/bar/bi-polar-interpolated.md): Ten weeks of positive and negative values around zero, with every other label shown.

- [Distributed series](https://chartist.dev/examples/bar/distributed-series.md): One series of clothing sizes, each value drawn as its own bar and color.

- [Extreme responsive configuration](https://chartist.dev/examples/bar/extreme-responsive.md): Five series per quarter that switch between stacked, horizontal and grouped bars as the screen grows.

- [Horizontal bar chart](https://chartist.dev/examples/bar/horizontal.md): Two series across the days of the week, drawn sideways.

- [Label placement](https://chartist.dev/examples/bar/label-position.md): Two weekly series with the x-axis labels on top and the y-axis labels on the right.

- [Multi-line labels](https://chartist.dev/examples/bar/multiline.md): Quarterly amounts in CHF with long labels that wrap onto several lines.

- [Overlapping bars on mobile](https://chartist.dev/examples/bar/overlapping-bars.md): Two series over twelve months whose bars move closer together and labels shorten on small screens.

- [Stacked bar chart](https://chartist.dev/examples/bar/stacked.md): Three series stacked per quarter, with a plugin that widens every bar.

- [Stacked bar chart with accumulate-relative stack mode](https://chartist.dev/examples/bar/stacked-accumulate-relative.md): Positive and negative values stacked separately, up and down from zero.

- [Add peak circles using the draw events](https://chartist.dev/examples/bar/with-circle-modify-drawing.md): A plugin adds a circle at the peak of every bar, sized by its value.

### Pie and donut charts

- [Simple pie chart](https://chartist.dev/examples/pie/simple.md): Three slices, each labelled with its share of the total.

- [Pie chart with custom labels](https://chartist.dev/examples/pie/custom-labels.md): Fruit slices labelled with an initial on small screens and the full name, pushed outside, on larger ones.

- [Donut chart](https://chartist.dev/examples/pie/donut-chart.md): Four labelled slices on a thick ring, starting at the left.

- [Animating a Donut with Svg.animate](https://chartist.dev/examples/pie/donut-animation.md): A plugin draws the donut slice by slice with SMIL, each one starting where the previous one ends.

- [Gauge chart](https://chartist.dev/examples/pie/simple-gauge.md): Four values on a half ring: a total of twice their sum leaves the lower half empty.

### Composed charts

- [Bars and a line with two Y axes](https://chartist.dev/examples/composed/bar-and-line.md): Quarterly revenue as bars on the left axis and the margin as a line on the right one.

- [Container queries (experimental)](https://chartist.dev/examples/composed/container-queries.md): One config in a narrow and a wide container: the narrow one drops the margin line, its axis and the grid.

- [SVG text labels](https://chartist.dev/examples/composed/svg-labels.md): Bars and a line with SVG text labels, which also work where foreignObject does not.

- [Band chart](https://chartist.dev/examples/composed/band-chart.md): The range of six stores as a band, with their average and one store drawn on top.

- [Grouped stacked bars](https://chartist.dev/examples/composed/grouped-stacks.md): New and returning customers per quarter, one stack per year, drawn by two bar layers side by side.

- [Two Y axes with different units](https://chartist.dev/examples/composed/two-y-axes.md): Temperature as a line and rainfall as an area, each on its own Y axis.

### Styling

- [Styling with custom properties](https://chartist.dev/examples/styling/custom-properties.md): The same area chart twice, the second one restyled only by setting --ct-* custom properties.

- [Accessible theme, light and dark](https://chartist.dev/examples/styling/accessible-theme.md): Four bar series in the color-blind-safe theme, on a light and on a dark background.

### Live data

- [Sensor with a sliding window](https://chartist.dev/examples/live/sensor.md): A new reading every second, and a line under the chart that says which elements each update kept, added and removed.

- [Dashboard with animated bars](https://chartist.dev/examples/live/dashboard.md): Two series by region get new numbers every two seconds, and the bars overshoot a little on their way.

- [Network speed](https://chartist.dev/examples/live/network-speed.md): Four samples a second as touching bars, with their running average as a line on top.

- [Seismograph](https://chartist.dev/examples/live/seismograph.md): A thin trace that scrolls every 80 ms, quiet until a quake comes through.

- [Votes by district](https://chartist.dev/examples/live/votes.md): The results of each district as it reports: the slices and their labels turn to the new shares.

- [Live gauge](https://chartist.dev/examples/live/gauge.md): A half ring that follows the CPU load, updated every 1.2 seconds.

- [Grouped and stacked](https://chartist.dev/examples/live/grouped-stacked.md): New numbers and a switch between grouped and stacked bars in one update, every bar moving to its new place.

### Essentials

- [Axis titles](https://chartist.dev/examples/essentials/axis-titles.md): A line chart of visits per day with a title for each axis, each in room of its own.

- [Axis titles on two Y axes](https://chartist.dev/examples/essentials/axis-titles-composed.md): Revenue in EUR and ad spend in USD on their own Y axes, each named, one title aligned to the end and one turned to face the chart.

- [Target lines on a bar chart](https://chartist.dev/examples/essentials/target-line.md): Monthly sales against a goal and a minimum, added to the bar chart preset as extra layers.

- [Bars with a trend line](https://chartist.dev/examples/essentials/trend-line.md): Monthly sign-ups as bars, with the least-squares trend through them added to the bar chart preset.

- [Scatter plot with a regression line](https://chartist.dev/examples/essentials/scatter-regression.md): Ice cream sales against the temperature as points, with the least-squares line through them.

- [Value labels on bars](https://chartist.dev/examples/essentials/value-labels-bars.md): Profit per quarter with each value past the end of its bar, and below it for a loss.

- [Labels on stacked segments](https://chartist.dev/examples/essentials/value-labels-stacked.md): Hours per work order on three machines as stacked horizontal bars, each segment labeled with its order and hours.

- [Labeled points with a unit](https://chartist.dev/examples/essentials/value-labels-line.md): Temperatures in two cities, each point labeled in degrees and in its series' color.

- [Log axis](https://chartist.dev/examples/essentials/log-axis.md): Users growing from 120 to 850,000 in six years on a log Y axis, where each tenfold step is the same height.

- [Moore's law, linear or log](https://chartist.dev/examples/essentials/moores-law.md): Transistors per processor from 1971 to 2022 on a log Y axis with minor grid lines, and a button that moves the points to a linear scale and back.

- [Log-log chart](https://chartist.dev/examples/essentials/log-log.md): Body mass and metabolic rate from a mouse to an elephant on two log axes with minor grid lines, and the straight trend line of their power law.

## Optional

- [v1.5 docs](https://chartist.dev/v1/): the documentation of an older major version
- [v0.11 archive](https://chartist.dev/v0/): the documentation of an older major version