ankaneChartkick.js
Create beautiful charts with one line of JavaScript
Supports Chart.js, Google Charts, and Highcharts
Also available for React, Vue.js, Ruby, Python, Elixir, and Clojure
Quick Start
Run
npm install chartkick chart.jsAnd add
import Chartkick from "chartkick"
import "chartkick/chart.js"This sets up Chartkick with Chart.js. For other charting libraries, see detailed instructions.
Charts
Create a div for the chart
<div id="chart" style="height: 300px;"></div>Line chart
new Chartkick.LineChart("chart", {"2021-01-01": 11, "2021-01-02": 6})Pie chart
new Chartkick.PieChart("chart", [["Blueberry", 44], ["Strawberry", 23]])Column chart
new Chartkick.ColumnChart("chart", [["Sun", 32], ["Mon", 46], ["Tue", 28]])Bar chart
new Chartkick.BarChart("chart", [["Work", 32], ["Play", 1492]])Area chart
new Chartkick.AreaChart("chart", {"2021-01-01": 11, "2021-01-02": 6})Scatter chart
new Chartkick.ScatterChart("chart", [[174.0, 80.0], [176.5, 82.3], [180.3, 73.6]])Geo chart - Google Charts
new Chartkick.GeoChart("chart", [["United States", 44], ["Germany", 23], ["Brazil", 22]])Timeline - Google Charts
new Chartkick.Timeline("chart", [["Washington", "1789-04-29", "1797-03-03"], ["Adams", "1797-03-03", "1801-03-03"]])Multiple series
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
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
new Chartkick.LineChart("chart", [["2021-01-01", 2], ["2021-01-02", 3]])Object
new Chartkick.LineChart("chart", {"2021-01-01": 2, "2021-01-02": 3})Callback
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.
new Chartkick.LineChart("chart", "/stocks")Options
Min and max for y-axis
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
new Chartkick.LineChart("chart", data, {xmin: "2021-01-01", xmax: "2022-01-01"})Colors
new Chartkick.LineChart("chart", data, {colors: ["#b00", "#666"]})Stacked columns or bars
new Chartkick.ColumnChart("chart", data, {stacked: true})You can also set
stackedtopercentorrelativefor Google Charts andpercentfor Highcharts
Discrete axis
new Chartkick.LineChart("chart", data, {discrete: true})Label (for single series)
new Chartkick.LineChart("chart", data, {label: "Value"})Axis titles
new Chartkick.LineChart("chart", data, {xtitle: "Time", ytitle: "Population"})Straight lines between points instead of a curve
new Chartkick.LineChart("chart", data, {curve: false})Hide points
new Chartkick.LineChart("chart", data, {points: false})Show or hide legend
new Chartkick.LineChart("chart", data, {legend: true})Specify legend position
new Chartkick.LineChart("chart", data, {legend: "bottom"})Donut chart
new Chartkick.PieChart("chart", data, {donut: true})Prefix, useful for currency - Chart.js, Highcharts
new Chartkick.LineChart("chart", data, {prefix: "$"})Suffix, useful for percentages - Chart.js, Highcharts
new Chartkick.LineChart("chart", data, {suffix: "%"})Set a thousands separator - Chart.js, Highcharts
new Chartkick.LineChart("chart", data, {thousands: ","})Set a decimal separator - Chart.js, Highcharts
new Chartkick.LineChart("chart", data, {decimal: ","})Set significant digits - Chart.js, Highcharts
new Chartkick.LineChart("chart", data, {precision: 3})Set rounding - Chart.js, Highcharts
new Chartkick.LineChart("chart", data, {round: 2})Show insignificant zeros, useful for currency - Chart.js, Highcharts
new Chartkick.LineChart("chart", data, {round: 2, zeros: true})Friendly byte sizes - Chart.js
new Chartkick.LineChart("chart", data, {bytes: true})Specify the message when the chart is loading
new Chartkick.LineChart("chart", data, {loading: "Loading..."})Specify the message when data is empty
new Chartkick.LineChart("chart", data, {empty: "No data"})Refresh data from a remote source every n seconds
new Chartkick.LineChart("chart", url, {refresh: 60})You can pass options directly to the charting library with:
new Chartkick.LineChart("chart", data, {library: {backgroundColor: "pink"}})See the documentation for Chart.js, Google Charts, and Highcharts for more info.
To customize datasets in Chart.js, use:
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:
Chartkick.options = {
colors: ["#b00", "#666"]
}Multiple Series
You can pass a few options with a series:
namedatacolordataset- Chart.js onlypoints- Chart.js onlycurve- Chart.js only
Code
If you want to use the charting library directly, get the code with:
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.
new Chartkick.LineChart("chart", data, {download: true})Set the filename
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
new Chartkick.LineChart("chart", data, {download: {background: "#fff"}})Installation
Chart.js
Run
npm install chartkick chart.jsAnd add
import Chartkick from "chartkick"
import "chartkick/chart.js"Google Charts
Run
npm install chartkickAnd add
import Chartkick from "chartkick"And include on the page
<script src="https://www.gstatic.com/charts/loader.js"></script>To specify a language or Google Maps API key, use:
Chartkick.configure({language: "de", mapsApiKey: "..."})before your charts.
Highcharts
Run
npm install chartkick highchartsAnd add
import Chartkick from "chartkick"
import "chartkick/highcharts"No Package Manager
Download chartkick.js directly.
For Chart.js (works with 4+), download it and the date-fns adapter bundle and use:
<script src="/path/to/chart.js"></script>
<script src="/path/to/chartjs-adapter-date-fns.bundle.js"></script>
<script src="chartkick.js"></script>For Google Charts, use:
<script src="https://www.gstatic.com/charts/loader.js"></script>
<script src="chartkick.js"></script>For Highcharts (works with 2.1+), download it and use:
<script src="/path/to/highcharts.js"></script>
<script src="chartkick.js"></script>Multiple Libraries
If more than one charting library is loaded, choose between them with:
new Chartkick.LineChart("chart", data, {adapter: "google"}) // or highcharts or chartjsAPI
Access a chart with:
var chart = Chartkick.charts["chart-id"]Get the underlying chart object with:
chart.getChartObject()You can also use:
chart.getElement()
chart.getData()
chart.getOptions()
chart.getAdapter()Update the data with:
chart.updateData(newData)You can also specify new options:
chart.setOptions(newOptions)
// or
chart.updateData(newData, newOptions)Refresh the data from a remote source:
chart.refreshData()Redraw the chart with:
chart.redraw()Loop over charts with:
Chartkick.eachChart(function (chart) {
// do something
})Custom Adapters
Note: This feature is experimental.
Add your own custom adapter with:
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:
npm install -g serve
serveand visit http://localhost:5000/examples/
Upgrading
4.0
Run:
npm install chartkick@latestFor Chart.js, also run:
npm install chart.js@latestAnd change:
import Chart from "chart.js"
Chartkick.use(Chart)to:
import "chartkick/chart.js"History
View the changelog
Contributing
Everyone is encouraged to help improve this project. Here are a few ways you can help:
- Report bugs
- Fix bugs and submit pull requests
- Write, clarify, or fix documentation
- Suggest or add new features
To get started with development:
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