Numerous Pancakes Munched

    chartkick

    4.2.0 • Public • Published

    Chartkick.js

    Create beautiful charts with one line of JavaScript

    See it in action

    Chartkick.js 4.0 was recently released - see how to upgrade

    Supports Chart.js, Google Charts, and Highcharts

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

    Build Status

    Quick Start

    Run

    npm install chartkick chart.js

    And 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-1" style="height: 300px;"></div>

    Line chart

    new Chartkick.LineChart("chart-1", {"2021-01-01": 11, "2021-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", {"2021-01-01": 11, "2021-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: {"2021-01-01": 3, "2021-01-02": 4}},
      {name: "Call parents", data: {"2021-01-01": 5, "2021-01-02": 3}}
    ]
    new Chartkick.LineChart("chart-1", 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-1", data, {stacked: true})

    Data

    Data can be an array, object, callback, or URL.

    Array

    new Chartkick.LineChart("chart-1", [["2021-01-01", 2], ["2021-01-02", 3]])

    Object

    new Chartkick.LineChart("chart-1", {"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-1", fetchData)

    URL

    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 for y-axis

    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.

    Min and max for x-axis - Chart.js

    new Chartkick.LineChart("chart-1", data, {xmin: "2021-01-01", xmax: "2022-01-01"})

    Colors

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

    Stacked columns or bars

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

    You can also set stacked to percent or relative for Google Charts and percent for Highcharts

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

    Prefix, useful for currency - Chart.js, Highcharts

    new Chartkick.LineChart("chart-1", data, {prefix: "$"})

    Suffix, useful for percentages - Chart.js, Highcharts

    new Chartkick.LineChart("chart-1", data, {suffix: "%"})

    Set a thousands separator - Chart.js, Highcharts

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

    Set a decimal separator - Chart.js, Highcharts

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

    Set significant digits - Chart.js, Highcharts

    new Chartkick.LineChart("chart-1", data, {precision: 3})

    Set rounding - Chart.js, Highcharts

    new Chartkick.LineChart("chart-1", data, {round: 2})

    Show insignificant zeros, useful for currency - Chart.js, Highcharts

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

    Friendly byte sizes - Chart.js

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

    Specify the message when the chart is loading

    new Chartkick.LineChart("chart-1", data, {loading: "Loading..."})

    Specify the message when data is empty

    new Chartkick.LineChart("chart-1", data, {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.

    To customize datasets in Chart.js, use:

    new Chartkick.LineChart("chart-1", 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:

    • 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:

    new Chartkick.LineChart("chart-1", 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-1", data, {download: true})

    Set the filename

    new Chartkick.LineChart("chart-1", 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-1", data, {download: {background: "#fff"}})

    Installation

    Chart.js

    Run

    npm install chartkick chart.js

    And add

    import Chartkick from "chartkick"
    import "chartkick/chart.js"

    Google Charts

    Run

    npm install chartkick

    And 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 highcharts

    And add

    import Chartkick from "chartkick"
    import "chartkick/highcharts"

    No Package Manager

    Download chartkick.js directly.

    For Chart.js (works with 3+), 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-1", data, {adapter: "google"}) // or highcharts or chartjs

    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)

    Examples

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

    npm install -g serve
    serve

    and visit http://localhost:5000/examples/

    Upgrading

    4.0

    Run:

    npm install chartkick@latest

    For Chart.js, also run:

    npm install chart.js@latest

    And 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:

    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

    Keywords

    Install

    npm i chartkick

    DownloadsWeekly Downloads

    67,105

    Version

    4.2.0

    License

    MIT

    Unpacked Size

    182 kB

    Total Files

    10

    Last publish

    Collaborators

    • ankane