Create beautiful charts with one line of JavaScript
JavaScript
Latest commit 23c5a02 Nov 28, 2017

README.md

Chartkick.js

Create beautiful charts with one line of JavaScript

See it in action

Supports Chart.js, Google Charts, and Highcharts

Also available for React, Vue.js, Ruby, Python, Elixir, and Clojure

Usage

Create a div for the chart

<div id="chart-1" style="height: 300px"></div>

Line chart

new Chartkick.LineChart("chart-1", {"2017-01-01": 11, "2017-01-02": 6})

Pie chart

new Chartkick.PieChart("chart-1", [["Blueberry", 44], ["Strawberry", 23]])

Column chart

new Chartkick.ColumnChart("chart-1", [["Sun", 32], ["Mon", 46], ["Tue", 28]])

Bar chart

new Chartkick.BarChart("chart-1", [["Work", 32], ["Play", 1492]])

Area chart

new Chartkick.AreaChart("chart-1", {"2017-01-01": 11, "2017-01-02": 6})

Scatter chart

new Chartkick.ScatterChart("chart-1", [[174.0, 80.0], [176.5, 82.3], [180.3, 73.6]])

Geo chart - Google Charts

new Chartkick.GeoChart("chart-1", [["United States", 44], ["Germany", 23], ["Brazil", 22]])

Timeline - Google Charts

new Chartkick.Timeline("chart-1", [["Washington", "1789-04-29", "1797-03-03"], ["Adams", "1797-03-03", "1801-03-03"]])

Multiple series

data = [
  {name: "Workout", data: {"2017-01-01": 3, "2017-01-02": 4}},
  {name: "Call parents", data: {"2017-01-01": 5, "2017-01-02": 3}}
]
new Chartkick.LineChart("chart-1", data)

Multiple series stacked and grouped - Chart.js 2.5+ 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-1", data, {stacked: true})

Say Goodbye To Timeouts

Make your pages load super fast and stop worrying about timeouts. Give each chart its own endpoint.

new Chartkick.LineChart("chart-1", "/stocks")

Options

Min and max values

new Chartkick.LineChart("chart-1", data, {min: 1000, max: 5000})

min defaults to 0 for charts with non-negative values. Use null to let the charting library decide.

Colors

new Chartkick.LineChart("chart-1", data, {colors: ["#b00", "#666"]})

Stacked columns or bars

new Chartkick.ColumnChart("chart-1", data, {stacked: true})

Discrete axis

new Chartkick.LineChart("chart-1", data, {discrete: true})

Label (for single series)

new Chartkick.LineChart("chart-1", data, {label: "Value"})

Axis titles

new Chartkick.LineChart("chart-1", data, {xtitle: "Time", ytitle: "Population"})

Straight lines between points instead of a curve

new Chartkick.LineChart("chart-1", data, {curve: false})

Hide points

new Chartkick.LineChart("chart-1", data, {points: false})

Show or hide legend

new Chartkick.LineChart("chart-1", data, {legend: true})

Specify legend position

new Chartkick.LineChart("chart-1", data, {legend: "bottom"})

Donut chart

new Chartkick.PieChart("chart-1", data, {donut: true})

Show a message when data is empty [master]

new Chartkick.LineChart("chart-1", data, {messages: {empty: "No data"}})

Refresh data from a remote source every n seconds

new Chartkick.LineChart("chart-1", url, {refresh: 60})

You can pass options directly to the charting library with:

new Chartkick.LineChart("chart-1", data, {library: {backgroundColor: "pink"}})

See the documentation for Chart.js, Google Charts, and Highcharts for more info.

Global Options

To set options for all of your charts, use:

Chartkick.options = {
  colors: ["#b00", "#666"]
}

Data

Pass data as an array or object

new Chartkick.PieChart("chart-1", {"Blueberry": 44, "Strawberry": 23})
new Chartkick.PieChart("chart-1", [["Blueberry", 44], ["Strawberry", 23]])

Times can be a Date, a timestamp, or a string (strings are parsed)

new Chartkick.LineChart("chart-1", [[new Date(), 5], [1368174456, 4], ["2017-01-01 00:00:00 UTC", 7]])

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-1", data, {download: true})

Set the filename

new Chartkick.LineChart("chart-1", data, {download: "boom"})

Note: Safari will open the image in a new window instead of downloading.

Installation

Download directly, or with npm or Bower:

npm install chartkick
# or
bower install chartkick

For Chart.js (works with 2.1+), download the bundle and use:

<script src="/path/to/Chart.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>

Localization

To specify a language for Google Charts, add:

Chartkick.configure({language: "de"})

after the JavaScript files and before your charts.

Adapter

If more than one charting library is loaded, choose between them with:

new Chartkick.LineChart("chart-1", data, {adapter: "google"}) // or highcharts

API

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);

Add a new chart type with:

var CustomAdapter = {
  name: "custom",
  renderCustomChart: function (chart) {
    chart.getElement().innerHTML = "Hi";
  }
};

Chartkick.CustomChart = function (element, dataSource, options) {
  Chartkick.createChart("CustomChart", this, element, dataSource, options);
};

Examples

To run the files in the examples directory, you'll need a web server. Run:

python -m SimpleHTTPServer

and visit http://localhost:8000/examples/

Upgrading

2.0

Breaking changes

  • Chart.js is now the default adapter if multiple are loaded - yay open source!
  • Axis types are automatically detected - no need for discrete: true
  • Better date support - dates are no longer treated as UTC

Credits

Chartkick uses iso8601.js to parse dates and times.

History

View the changelog

Chartkick.js follows Semantic Versioning

Contributing

Everyone is encouraged to help improve this project. Here are a few ways you can help:

If you’re looking for ideas, try here.

To get started with development and testing:

git clone https://github.com/ankane/chartkick.js.git
cd chartkick.js
python -m SimpleHTTPServer # starts a web server on port 8000

And visit http://localhost:8000/examples in your browser.