### 01 Intro

---
title: Introduction
---



Chart.xkcd is a chart library plots "sketchy", "cartoony" or "hand-drawn" styled charts.

[](https://github.com/timqian/chart.xkcd)
[](https://www.npmjs.com/package/chart.xkcd)
[](https://www.jsdelivr.com/package/npm/chart.xkcd)  
[**Live examples →**](https://timqian.com/chart.xkcd/example.html)

---

### 02 Getting Started

---
title: Getting started
---

It's easy to get started with chart.xkcd. All that's required is the script included in your page along with a single `<svg>` node to render the chart.

In the following example we create a line chart.

<p class="codepen" data-height="424" data-theme-id="light" data-default-tab="result" data-user="timqian" data-slug-hash="GRKqLaL" style="height: 424px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;" data-pen-title="chart.xkcd example">
  <span>See the Pen <a href="https://codepen.io/timqian/pen/GRKqLaL/">
  chart.xkcd example</a> by timqian (<a href="https://codepen.io/timqian">@timqian</a>)
  on <a href="https://codepen.io">CodePen</a>.</span>
</p>
<script async src="https://static.codepen.io/assets/embed/ei.js"></script>

**JS part of the example**

```javascript
  const svg = document.querySelector('.line-chart')
  new chartXkcd.Line(svg, {
    title: '',
    xLabel: '',
    yLabel: '',
    data: {...},
    options: {},
  });
```

## Parameters description

- `title`: optional title of the chart
- `xLabel`: optional x label of the chart
- `yLabel`: optional y label of the chart
- `data`: the data you want to visulize
- `options`: optional configurations to customize how the chart looks

---

### 03 Install

---
title: Installation
---

You can install chart.xkcd via script tag in HTML or via npm

## Via Script Tag

```js
<script src="https://cdn.jsdelivr.net/npm/chart.xkcd@2/dist/chart.xkcd.min.js" integrity="sha256-NkH6G4XRcQ5Bsfs7O6yh9mw1SJLEOJWCtWqko6VjF34=" crossorigin="anonymous"></script>
<script>
    const myChart = new chartXkcd.Line(svg, {...});
</script>
```

## Via npm

**Install**

```bash
npm i chart.xkcd
```

**Usage**

```js
import chartXkcd from 'chart.xkcd';
const myChart = new chartXkcd.Line(svg, {...});
```

**Other ways**

- React wrapper: [chart.xkcd-react](https://github.com/obiwankenoobi/chart.xkcd-react) <br/>
- Vue wrapper:
    - [chart.xkcd-vue](https://github.com/shiyiya/chart.xkcd-vue)
    - [chart.xkcd-vue-wrapper](https://github.com/wistcc/chart.xkcd-vue-wrapper)

---

### 04 Line

---
title: Line chart
---

Line chart displays series of data points in the form of lines. It can be used to show trend data, or comparison of different data sets.

<p class="codepen" data-height="424" data-theme-id="light" data-default-tab="result" data-user="timqian" data-slug-hash="GRKqLaL" style="height: 424px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;" data-pen-title="chart.xkcd example">
  <span>See the Pen <a href="https://codepen.io/timqian/pen/GRKqLaL/">
  chart.xkcd example</a> by timqian (<a href="https://codepen.io/timqian">@timqian</a>)
  on <a href="https://codepen.io">CodePen</a>.</span>
</p>
<script async src="https://static.codepen.io/assets/embed/ei.js"></script>

## JS part

```js
const lineChart = new chartXkcd.Line(svg, {
  title: 'Monthly income of an indie developer', // optional
  xLabel: 'Month', // optional
  yLabel: '$ Dollars', // optional
  data: {
    labels: ['1', '2', '3', '4', '5', '6', '7', '8', '9', '10'],
    datasets: [{
      label: 'Plan',
      data: [30, 70, 200, 300, 500, 800, 1500, 2900, 5000, 8000],
    }, {
      label: 'Reality',
      data: [0, 1, 30, 70, 80, 100, 50, 80, 40, 150],
    }],
  },
  options: { // optional
    yTickCount: 3,
    legendPosition: chartXkcd.config.positionType.upLeft
  }
})
```

## Customize chart by defining options

- `yTickCount`: customize tick numbers you want to see on the y axis (default `3`)
- `showLegend`: display legend near chart (default `true`)
- `legendPosition`: specify where you want to place the legend. (default `chartXkcd.config.positionType.upLeft`)
  Possible values:
    - up left: `chartXkcd.config.positionType.upLeft`
    - up right: `chartXkcd.config.positionType.upRight`
    - bottom left: `chartXkcd.config.positionType.downLeft`
    - bottom right: `chartXkcd.config.positionType.downRight`
- `dataColors`: array of colors for different datasets
- `fontFamily`: customize font family used in the chart
- `unxkcdify`: disable xkcd effect (default `false`)
- `strokeColor`: stroke colors (default `black`)
- `backgroundColor`: color for BG (default `white`)

---

### 05 XY

---
title: XY chart
---

XY chart is used to plot points by specifying their XY coordinates.

You can also plot XY line chart by connecting the points.

<p class="codepen" data-height="445" data-theme-id="light" data-default-tab="result" data-user="timqian" data-slug-hash="ExYZvZY" style="height: 445px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;" data-pen-title="chart.xkcd XY">
  <span>See the Pen <a href="https://codepen.io/timqian/pen/ExYZvZY/">
  chart.xkcd XY</a> by timqian (<a href="https://codepen.io/timqian">@timqian</a>)
  on <a href="https://codepen.io">CodePen</a>.</span>
</p>
<script async src="https://static.codepen.io/assets/embed/ei.js"></script>

## JS part

```js
  const svg = document.querySelector('.xy-chart');

  new chartXkcd.XY(svg, {
    title: 'Pokemon farms', //optional
    xLabel: 'Coordinate', //optional
    yLabel: 'Count', //optional
    data: {
      datasets: [{
        label: 'Pikachu',
        data: [{ x: 3, y: 10 }, { x: 4, y: 122 }, { x: 10, y: 100 }, { x: 1, y: 2 }, { x: 2, y: 4 }],
      }, {
        label: 'Squirtle',
        data: [{ x: 3, y: 122 }, { x: 4, y: 212 }, { x: -3, y: 100 }, { x: 1, y: 1 }, { x: 1.5, y: 12 }],
      }],
    },
    options: { //optional
      xTickCount: 5,
      yTickCount: 5,
      legendPosition: chartXkcd.config.positionType.upRight,
      showLine: false,
      timeFormat: undefined,
      dotSize: 1,
    },
  });
```

## Customize XY chart by defining options

- `xTickCount`: customize tick numbers you want to see on the x axis (default `3`)
- `yTickCount`: customize tick numbers you want to see on the y axis (default `3`)
- `showLegend`: display legend near chart (default `true`)
- `legendPosition`: specify where you want to place the legend (default `chartXkcd.config.positionType.upLeft`)
  Possible values:
    - up left: `chartXkcd.config.positionType.upLeft`
    - up right: `chartXkcd.config.positionType.upLeft`
    - bottom left: `chartXkcd.config.positionType.downLeft`
    - bottom right: `chartXkcd.config.positionType.downRight`
- `showLine`: connect the points with lines (default: `false`)
- `timeFormat`: specify the time format if the x values are time (default `undefined`)
  chart.xkcd use [dayjs](https://github.com/iamkun/dayjs) to format time, you can find the all the available formats [here](https://github.com/iamkun/dayjs/blob/dev/docs/en/API-reference.md#list-of-all-available-formats)
- `dotSize`: you can change size of the dots if you want (default `1`)
- `dataColors`: array of colors for different datasets
- `fontFamily`: customize font family used in the chart
- `unxkcdify`: disable xkcd effect (default `false`)
- `strokeColor`: stroke colors (default `black`)
- `backgroundColor`: color for BG (default `white`)

**Another example of XY chart: XY line chart with `timeFormat`**

<p class="codepen" data-height="472" data-theme-id="light" data-default-tab="result" data-user="timqian" data-slug-hash="ZEzLJaN" style="height: 472px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;" data-pen-title="chart.xkcd XY line">
  <span>See the Pen <a href="https://codepen.io/timqian/pen/ZEzLJaN/">
  chart.xkcd XY line</a> by timqian (<a href="https://codepen.io/timqian">@timqian</a>)
  on <a href="https://codepen.io">CodePen</a>.</span>
</p>
<script async src="https://static.codepen.io/assets/embed/ei.js"></script>

---

### 06 Bar

---
title: Bar chart
---

A bar chart provides a way of showing data values represented as vertical bars

<p class="codepen" data-height="509" data-theme-id="light" data-default-tab="result" data-user="timqian" data-slug-hash="QWLERdG" style="height: 509px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;" data-pen-title="chart.xkcd bar">
  <span>See the Pen <a href="https://codepen.io/timqian/pen/QWLERdG/">
  chart.xkcd bar</a> by timqian (<a href="https://codepen.io/timqian">@timqian</a>)
  on <a href="https://codepen.io">CodePen</a>.</span>
</p>
<script async src="https://static.codepen.io/assets/embed/ei.js"></script>

## JS part

```js
const barChart = new chartXkcd.Bar(svg, {
  title: 'github stars VS patron number', // optional
  // xLabel: '', // optional
  // yLabel: '', // optional
  data: {
    labels: ['github stars', 'patrons'],
    datasets: [{
      data: [100, 2],
    }],
  },
  options: { // optional
    yTickCount: 2,
  },
});
```

## Customize chart by defining options

- `yTickCount`: customize tick numbers you want to see on the y axis
- `dataColors`: array of colors for different datasets
- `fontFamily`: customize font family used in the chart
- `unxkcdify`: disable xkcd effect (default `false`)
- `strokeColor`: stroke colors (default `black`)
- `backgroundColor`: color for BG (default `white`)

---

### 07 Stacked Bar

---
title: Stacked bar chart
---

A stacked bar chart provides a way of showing data values represented as vertical bars

<p class="codepen" data-height="429" data-theme-id="light" data-default-tab="result" data-user="timqian" data-slug-hash="KKwPrEm" style="height: 429px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;" data-pen-title="chart.xkcd stacked bar">
  <span>See the Pen <a href="https://codepen.io/timqian/pen/KKwPrEm">
  chart.xkcd stacked bar</a> by timqian (<a href="https://codepen.io/timqian">@timqian</a>)
  on <a href="https://codepen.io">CodePen</a>.</span>
</p>
<script async src="https://static.codepen.io/assets/embed/ei.js"></script>

## JS part

```js
new chartXkcd.StackedBar(svg, {
  title: 'Issues and PR Submissions',
  xLabel: 'Month',
  yLabel: 'Count',
  data: {
    labels: ['Jan', 'Feb', 'Mar', 'April', 'May'],
    datasets: [{
      label: 'Issues',
      data: [12, 19, 11, 29, 17],
    }, {
      label: 'PRs',
      data: [3, 5, 2, 4, 1],
    }, {
      label: 'Merges',
      data: [2, 3, 0, 1, 1],
    }],
  },
});
```

## Customize chart by defining options

- `yTickCount`: customize tick numbers you want to see on the y axis
- `dataColors`: array of colors for different datasets
- `fontFamily`: customize font family used in the chart
- `unxkcdify`: disable xkcd effect (default `false`)
- `strokeColor`: stroke colors (default `black`)
- `backgroundColor`: color for BG (default `white`)
- `showLegend`: display legend near chart (default `true`)
- `legendPosition`: specify where you want to place the legend (default `chartXkcd.config.positionType.upLeft`)
  Possible values:
    - up left: `chartXkcd.config.positionType.upLeft`
    - up right: `chartXkcd.config.positionType.upLeft`
    - bottom left: `chartXkcd.config.positionType.downLeft`
    - bottom right: `chartXkcd.config.positionType.downRight`

---

### 08 Pie

---
title: Pie/Doughnut chart
---

<p class="codepen" data-height="470" data-theme-id="light" data-default-tab="result" data-user="timqian" data-slug-hash="VwZjOPR" style="height: 470px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;" data-pen-title="chart.xkcd pie">
  <span>See the Pen <a href="https://codepen.io/timqian/pen/VwZjOPR/">
  chart.xkcd pie</a> by timqian (<a href="https://codepen.io/timqian">@timqian</a>)
  on <a href="https://codepen.io">CodePen</a>.</span>
</p>
<script async src="https://static.codepen.io/assets/embed/ei.js"></script>

## JS part

```js
const pieChart = new chartXkcd.Pie(svg, {
  title: 'What Tim is made of', // optional
  data: {
    labels: ['a', 'b', 'e', 'f', 'g'],
    datasets: [{
      data: [500, 200, 80, 90, 100],
    }],
  },
  options: { // optional
    innerRadius: 0.5,
    legendPosition: chartXkcd.config.positionType.upRight,
  },
});
```

## Customize chart by defining options

- `innerRadius`: specify empty pie chart radius (default: `0.5`)
  - Want a pie chart? set `innerRadius` to `0`
- `showLegend`: display legend near chart (default `true`)
- `legendPosition`: specify where you want to place the legend. (default `chartXkcd.config.positionType.upLeft`)
  Possible values:
    - up left: `chartXkcd.config.positionType.upLeft`
    - up right: `chartXkcd.config.positionType.upLeft`
    - bottom left: `chartXkcd.config.positionType.downLeft`
    - bottom right: `chartXkcd.config.positionType.downRight`
- `dataColors`: array of colors for different datasets
- `fontFamily`: customize font family used in the chart
- `unxkcdify`: disable xkcd effect (default `false`)
- `strokeColor`: stroke colors (default `black`)
- `backgroundColor`: color for BG (default `white`)

---

### 09 Radar

---
title: Radar chart
---

<p class="codepen" data-height="434" data-theme-id="light" data-default-tab="result" data-user="timqian" data-slug-hash="VwZQBoj" style="height: 434px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;" data-pen-title="chart.xkcd radar">
  <span>See the Pen <a href="https://codepen.io/timqian/pen/VwZQBoj/">
  chart.xkcd radar</a> by timqian (<a href="https://codepen.io/timqian">@timqian</a>)
  on <a href="https://codepen.io">CodePen</a>.</span>
</p>
<script async src="https://static.codepen.io/assets/embed/ei.js"></script>

## JS part

```js
const radar = new chartXkcd.Radar(svg, {
  title: 'Letters in random words', // optional
  data: {
    labels: ['c', 'h', 'a', 'r', 't'],
    datasets: [{
      label: 'ccharrrt', // optional
      data: [2, 1, 1, 3, 1],
    }, {
      label: 'chhaart', // optional
      data: [1, 2, 2, 1, 1],
    }],
  },
  options: { // optional
    showLegend: true,
    dotSize: .8,
    showLabels: true,
    legendPosition: chartXkcd.config.positionType.upRight,
  },
});
```

## Customize chart by defining options

- `showLabels`: display labels near every line (default `false`)
- `ticksCount`: customize tick numbers you want to see on the main line (default `3`)
- `dotSize`: you can change size of the dots if you want (default `1`)
- `showLegend`: display legend near chart (default `false`)
- `legendPosition`: specify where you want to place the legend. (default `chartXkcd.config.positionType.upLeft`)
  Possible values:
    - up left: `chartXkcd.config.positionType.upLeft`
    - up right: `chartXkcd.config.positionType.upRight`
    - bottom left: `chartXkcd.config.positionType.downLeft`
    - bottom right: `chartXkcd.config.positionType.downRight`
- `dataColors`: array of colors for different datasets
- `fontFamily`: customize font family used in the chart
- `unxkcdify`: disable xkcd effect (default `false`)
- `strokeColor`: stroke colors (default `black`)
- `backgroundColor`: color for BG (default `white`)

---

### 10 Combined

---
title: Combined chart
---

A combined chart displays bar datasets and line datasets in the same chart. It is useful when related series share the same labels and y axis but need different visual treatments.

<p class="codepen" data-height="445" data-theme-id="light" data-default-tab="result" data-user="timqian" data-slug-hash="LExbRQb" style="height: 445px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;" data-pen-title="chart.xkcd XY">
  <span>See the Pen <a href="https://codepen.io/timqian/pen/LExbRQb">
  chart.xkcd combined</a> by timqian (<a href="https://codepen.io/timqian">@timqian</a>)
  on <a href="https://codepen.io">CodePen</a>.</span>
</p>
<script async src="https://static.codepen.io/assets/embed/ei.js"></script>

## JS part

```js
const combinedChart = new chartXkcd.Combined(svg, {
  title: 'Monthly visitors and signups', // optional
  xLabel: 'Month', // optional
  yLabel: 'Count', // optional
  data: {
    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
    datasets: [{
      label: 'Visitors',
      type: 'bar',
      data: [120, 180, 150, 220, 260, 310],
    }, {
      label: 'Signups',
      type: 'line',
      data: [15, 20, 18, 32, 44, 56],
    }],
  },
  options: { // optional
    yTickCount: 3,
    legendPosition: chartXkcd.config.positionType.upLeft
  }
});
```

Datasets with `type: 'bar'` render as bars. Datasets with `type: 'line'` render as lines.

## Customize chart by defining options

- `yTickCount`: customize tick numbers you want to see on the y axis (default `3`)
- `showLegend`: display legend near chart (default `true`)
- `legendPosition`: specify where you want to place the legend. (default `chartXkcd.config.positionType.upLeft`)
  Possible values:
    - up left: `chartXkcd.config.positionType.upLeft`
    - up right: `chartXkcd.config.positionType.upRight`
    - bottom left: `chartXkcd.config.positionType.downLeft`
    - bottom right: `chartXkcd.config.positionType.downRight`
- `dataColors`: array of colors for different datasets
- `fontFamily`: customize font family used in the chart
- `unxkcdify`: disable xkcd effect (default `false`)
- `strokeColor`: stroke colors (default `black`)
- `backgroundColor`: color for BG (default `white`)

---

### Contributing

> drafting

# Contributing

Before contributing to chart.xkcd you'll need a few things:

- install npm

## Setup

```bash
# install dependencies
npm i
```

```bash
# start examples
npm start
```

Then you can open `localhost:1234` to see the examples, and you can start to edit the code. Thanks to [parcel](), the website will be auto updated when you make changes.

## Layout

- [docs](./docs): Documentation used to generate timqian.com/chart.xkcd
  - preview docs: `npm run genDoc` and `npx serve`
- [examples](./examples): Examples showing how to use chart.xkcd. The npm example is also used for developing and debug features for now.
- [src](./src): where the meat locates

## Releases

To release a new version, just update the version number in package.json. New version will be released by github actions.

---

### Readme

[](https://timqian.com/chart.xkcd/)

## About

Chart.xkcd is a chart library that plots “sketchy”, “cartoony” or “hand-drawn” styled charts.

Check out the [documentation](https://timqian.com/chart.xkcd/) for more instructions and links, or try out the [examples](https://timqian.com/chart.xkcd/example.html)

## Quick start

It’s easy to get started with chart.xkcd. All that’s required is the script included in your page along with a single `<svg>` node to render the chart.

In the following example we create a line chart.

> **[Preview and edit on codepen](https://codepen.io/timqian/pen/GRKqLaL)**

```html
<svg class="line-chart"></svg>
<script src="https://cdn.jsdelivr.net/npm/chart.xkcd@2/dist/chart.xkcd.min.js"></script>
<script>
  const svg = document.querySelector('.line-chart')

  new chartXkcd.Line(svg, {
    title: 'Monthly income of an indie developer',
    xLabel: 'Month',
    yLabel: '$ Dollars',
    data: {
      labels:['1', '2', '3', '4', '5', '6','7', '8', '9', '10'],
      datasets: [{
        label: 'Plan',
        data: [30, 70, 200, 300, 500 ,800, 1500, 2900, 5000, 8000],
      }, {
        label: 'Reality',
        data: [0, 1, 30, 70, 80, 100, 50, 80, 40, 150],
      }]
    },
    options: {}
  });
</script>
```

## Contributing

- Code: read the [contributing.md](./contributing.md) file
- Financial:
  - [Become a patron](https://www.patreon.com/timqian) - chart.xkcd is an MIT-licensed open source project with its ongoing development made possible entirely by the support of my patrons. If you like this tool, please consider supporting my work by becoming a patron.
  - [Fund issues on issuehunt](https://issuehunt.io/r/timqian/chart.xkcd?tab=idle) - Issues on chart.xkcd can be funded by anyone and the money will be distributed to contributors.

## Star History

[](https://star-history.com/#timqian/chart.xkcd&Date)

---