Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ankane/chartkick.js
Create beautiful charts with one line of JavaScript
https://github.com/ankane/chartkick.js
Last synced: 19 days ago
JSON representation
Create beautiful charts with one line of JavaScript
- Host: GitHub
- URL: https://github.com/ankane/chartkick.js
- Owner: ankane
- License: mit
- Created: 2013-05-15T04:03:53.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2023-12-29T02:54:14.000Z (10 months ago)
- Last Synced: 2024-05-15T13:14:37.184Z (6 months ago)
- Language: JavaScript
- Homepage:
- Size: 706 KB
- Stars: 1,229
- Watchers: 41
- Forks: 152
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
- my-awesome-list - chartkick.js
README
# Chartkick.js
Create beautiful charts with one line of JavaScript
[See it in action](https://ankane.github.io/chartkick.js/examples/)
Supports [Chart.js](https://www.chartjs.org/), [Google Charts](https://developers.google.com/chart/), and [Highcharts](https://www.highcharts.com/)
Also available for [React](https://github.com/ankane/react-chartkick), [Vue.js](https://github.com/ankane/vue-chartkick), [Ruby](https://github.com/ankane/chartkick), [Python](https://github.com/mher/chartkick.py), [Elixir](https://github.com/buren/chartkick-ex), and [Clojure](https://github.com/yfractal/chartkick)
For maps, check out [Mapkick.js](https://github.com/ankane/mapkick.js)
[](https://github.com/ankane/chartkick.js/actions)
## Quick Start
Run
```sh
npm install chartkick chart.js
```
And add
```javascript
import Chartkick from "chartkick"
import "chartkick/chart.js"
```
This sets up Chartkick with Chart.js. For other charting libraries, see [detailed instructions](#installation).
## Charts
Create a div for the chart
```html
```
Line chart
```javascript
new Chartkick.LineChart("chart", {"2021-01-01": 11, "2021-01-02": 6})
```
Pie chart
```javascript
new Chartkick.PieChart("chart", [["Blueberry", 44], ["Strawberry", 23]])
```
Column chart
```javascript
new Chartkick.ColumnChart("chart", [["Sun", 32], ["Mon", 46], ["Tue", 28]])
```
Bar chart
```javascript
new Chartkick.BarChart("chart", [["Work", 32], ["Play", 1492]])
```
Area chart
```javascript
new Chartkick.AreaChart("chart", {"2021-01-01": 11, "2021-01-02": 6})
```
Scatter chart
```javascript
new Chartkick.ScatterChart("chart", [[174.0, 80.0], [176.5, 82.3], [180.3, 73.6]])
```
Geo chart - *Google Charts*
```javascript
new Chartkick.GeoChart("chart", [["United States", 44], ["Germany", 23], ["Brazil", 22]])
```
Timeline - *Google Charts*
```javascript
new Chartkick.Timeline("chart", [["Washington", "1789-04-29", "1797-03-03"], ["Adams", "1797-03-03", "1801-03-03"]])
```
Multiple series
```javascript
data = [
{name: "Workout", data: {"2021-01-01": 3, "2021-01-02": 4}},
{name: "Call parents", data: {"2021-01-01": 5, "2021-01-02": 3}}
]
new Chartkick.LineChart("chart", data)
```
Multiple series stacked and grouped - *Chart.js or Highcharts*
```javascript
data = [
{name: "Apple", data: {"Tuesday": 3, "Friday": 4}, stack: "fruit"},
{name: "Pear", data: {"Tuesday": 1, "Friday": 8}, stack: "fruit"},
{name: "Carrot", data: {"Tuesday": 3, "Friday": 4}, stack: "vegetable"},
{name: "Beet", data: {"Tuesday": 1, "Friday": 8}, stack: "vegetable"}
]
new Chartkick.BarChart("chart", data, {stacked: true})
```
## Data
Data can be an array, object, callback, or URL.
#### Array
```javascript
new Chartkick.LineChart("chart", [["2021-01-01", 2], ["2021-01-02", 3]])
```
#### Object
```javascript
new Chartkick.LineChart("chart", {"2021-01-01": 2, "2021-01-02": 3})
```
#### Callback
```javascript
function fetchData(success, fail) {
success({"2021-01-01": 2, "2021-01-02": 3})
// or fail("Data not available")
}
new Chartkick.LineChart("chart", fetchData)
```
#### URL
Make your pages load super fast and stop worrying about timeouts. Give each chart its own endpoint.
```javascript
new Chartkick.LineChart("chart", "/stocks")
```
## Options
Min and max for y-axis
```javascript
new Chartkick.LineChart("chart", data, {min: 1000, max: 5000})
```
`min` defaults to 0 for charts with non-negative values. Use `null` to let the charting library decide.
Min and max for x-axis - *Chart.js*
```javascript
new Chartkick.LineChart("chart", data, {xmin: "2021-01-01", xmax: "2022-01-01"})
```
Colors
```javascript
new Chartkick.LineChart("chart", data, {colors: ["#b00", "#666"]})
```
Stacked columns or bars
```javascript
new Chartkick.ColumnChart("chart", data, {stacked: true})
```
> You can also set `stacked` to `percent` or `relative` for Google Charts and `percent` for Highcharts
Discrete axis
```javascript
new Chartkick.LineChart("chart", data, {discrete: true})
```
Label (for single series)
```javascript
new Chartkick.LineChart("chart", data, {label: "Value"})
```
Axis titles
```javascript
new Chartkick.LineChart("chart", data, {xtitle: "Time", ytitle: "Population"})
```
Straight lines between points instead of a curve
```javascript
new Chartkick.LineChart("chart", data, {curve: false})
```
Hide points
```javascript
new Chartkick.LineChart("chart", data, {points: false})
```
Show or hide legend
```javascript
new Chartkick.LineChart("chart", data, {legend: true})
```
Specify legend position
```javascript
new Chartkick.LineChart("chart", data, {legend: "bottom"})
```
Donut chart
```javascript
new Chartkick.PieChart("chart", data, {donut: true})
```
Prefix, useful for currency - *Chart.js, Highcharts*
```javascript
new Chartkick.LineChart("chart", data, {prefix: "$"})
```
Suffix, useful for percentages - *Chart.js, Highcharts*
```javascript
new Chartkick.LineChart("chart", data, {suffix: "%"})
```
Set a thousands separator - *Chart.js, Highcharts*
```javascript
new Chartkick.LineChart("chart", data, {thousands: ","})
```
Set a decimal separator - *Chart.js, Highcharts*
```javascript
new Chartkick.LineChart("chart", data, {decimal: ","})
```
Set significant digits - *Chart.js, Highcharts*
```javascript
new Chartkick.LineChart("chart", data, {precision: 3})
```
Set rounding - *Chart.js, Highcharts*
```javascript
new Chartkick.LineChart("chart", data, {round: 2})
```
Show insignificant zeros, useful for currency - *Chart.js, Highcharts*
```javascript
new Chartkick.LineChart("chart", data, {round: 2, zeros: true})
```
Friendly byte sizes - *Chart.js*
```javascript
new Chartkick.LineChart("chart", data, {bytes: true})
```
Specify the message when the chart is loading
```javascript
new Chartkick.LineChart("chart", data, {loading: "Loading..."})
```
Specify the message when data is empty
```javascript
new Chartkick.LineChart("chart", data, {empty: "No data"})
```
Refresh data from a remote source every `n` seconds
```javascript
new Chartkick.LineChart("chart", url, {refresh: 60})
```
You can pass options directly to the charting library with:
```javascript
new Chartkick.LineChart("chart", data, {library: {backgroundColor: "pink"}})
```
See the documentation for [Chart.js](https://www.chartjs.org/docs/), [Google Charts](https://developers.google.com/chart/interactive/docs/gallery), and [Highcharts](https://api.highcharts.com/highcharts) for more info.
To customize datasets in Chart.js, use:
```javascript
new Chartkick.LineChart("chart", data, {dataset: {borderWidth: 10}})
```
You can pass this option to individual series as well.
### Global Options
To set options for all of your charts, use:
```javascript
Chartkick.options = {
colors: ["#b00", "#666"]
}
```
### Multiple Series
You can pass a few options with a series:
- `name`
- `data`
- `color`
- `dataset` - *Chart.js only*
- `points` - *Chart.js only*
- `curve` - *Chart.js only*
### Code
If you want to use the charting library directly, get the code with:
```javascript
new Chartkick.LineChart("chart", data, {code: true})
```
The code will be logged to the JavaScript console.
**Note:** JavaScript functions cannot be logged, so it may not be identical.
### Download Charts
*Chart.js only*
Give users the ability to download charts. It all happens in the browser - no server-side code needed.
```javascript
new Chartkick.LineChart("chart", data, {download: true})
```
Set the filename
```javascript
new Chartkick.LineChart("chart", data, {download: {filename: "boom"}})
```
**Note:** Safari will open the image in a new window instead of downloading.
Set the background color
```javascript
new Chartkick.LineChart("chart", data, {download: {background: "#fff"}})
```
## Installation
### Chart.js
Run
```sh
npm install chartkick chart.js
```
And add
```javascript
import Chartkick from "chartkick"
import "chartkick/chart.js"
```
### Google Charts
Run
```sh
npm install chartkick
```
And add
```javascript
import Chartkick from "chartkick"
```
And include on the page
```html
```
To specify a language or Google Maps API key, use:
```js
Chartkick.configure({language: "de", mapsApiKey: "..."})
```
before your charts.
### Highcharts
Run
```sh
npm install chartkick highcharts
```
And add
```javascript
import Chartkick from "chartkick"
import "chartkick/highcharts"
```
### No Package Manager
Download [chartkick.js](https://unpkg.com/chartkick) directly.
For Chart.js (works with 4+), [download it](https://unpkg.com/[email protected]/dist/chart.umd.js) and the [date-fns adapter bundle](https://unpkg.com/chartjs-adapter-date-fns@3/dist/chartjs-adapter-date-fns.bundle.js) and use:
```html
```
For Google Charts, use:
```html
```
For Highcharts (works with 2.1+), [download it](https://www.highcharts.com/download) and use:
```html
```
### Multiple Libraries
If more than one charting library is loaded, choose between them with:
```javascript
new Chartkick.LineChart("chart", data, {adapter: "google"}) // or highcharts or chartjs
```
## API
Access a chart with:
```javascript
var chart = Chartkick.charts["chart-id"]
```
Get the underlying chart object with:
```javascript
chart.getChartObject()
```
You can also use:
```javascript
chart.getElement()
chart.getData()
chart.getOptions()
chart.getAdapter()
```
Update the data with:
```javascript
chart.updateData(newData)
```
You can also specify new options:
```javascript
chart.setOptions(newOptions)
// or
chart.updateData(newData, newOptions)
```
Refresh the data from a remote source:
```javascript
chart.refreshData()
```
Redraw the chart with:
```javascript
chart.redraw()
```
Loop over charts with:
```javascript
Chartkick.eachChart(function (chart) {
// do something
})
```
## Custom Adapters
**Note:** This feature is experimental.
Add your own custom adapter with:
```javascript
var CustomAdapter = {
name: "custom",
renderLineChart: function (chart) {
chart.getElement().innerHTML = "Hi"
}
}
Chartkick.adapters.unshift(CustomAdapter)
```
## Examples
To run the files in the `examples` directory, you’ll need a web server. Run:
```sh
npm install -g serve
serve
```
and visit [http://localhost:5000/examples/](http://localhost:5000/examples/)
## History
View the [changelog](https://github.com/ankane/chartkick.js/blob/master/CHANGELOG.md)
## Contributing
Everyone is encouraged to help improve this project. Here are a few ways you can help:
- [Report bugs](https://github.com/ankane/chartkick.js/issues)
- Fix bugs and [submit pull requests](https://github.com/ankane/chartkick.js/pulls)
- Write, clarify, or fix documentation
- Suggest or add new features
To get started with development:
```sh
git clone https://github.com/ankane/chartkick.js.git
cd chartkick.js
npm install
npm run build
# start web server
npm install -g serve
serve
```