Chartkick: One Line of Ruby for JavaScript Charts

The problem Chartkick removes: charting code in a Rails view

Charting in a Rails app usually means two languages in one file. The query is Ruby, the chart configuration is JavaScript, and the two meet in a template where neither side reads cleanly. Chartkick collapses that into a single helper call. The README's first example is a line chart built from a Groupdate aggregate: a hash of dates to counts, passed straight to the helper. The gem's own description is "Create beautiful JavaScript charts with one line of Ruby", and the examples hold to that promise: line, pie, column, bar, area, scatter, geo and timeline charts each take one call in ERB.

The audience is narrow and specific. This is for Rails developers who already have their numbers as a hash, an array, or a query result, and who want a chart on the page without opening the charting library's documentation. The README points at Blazer for admin dashboards and Vega for advanced visualizations, which is a useful boundary: Chartkick is the middle of that range, not either end. If your chart needs a custom interaction model, this is the wrong layer.

How Chartkick splits work between Ruby and JavaScript

The gem does not draw anything itself. The helper generates a container element and the JavaScript that mounts a chart into it, and the actual rendering is done by a charting library loaded in the page. The README's default pairing is Chart.js; Google Charts and Highcharts are supported through separate instructions, and the option list marks which library each option applies to, for example geo charts and timelines are labelled Google Charts, while prefix, suffix, thousands, decimal, precision, round and zeros are labelled Chart.js and Highcharts, and bytes is labelled Chart.js only.

Data reaches the chart in one of three shapes, all documented: a hash of labels to values, an array of pairs, or a URL. The URL form is the architectural choice worth noticing. Instead of embedding data in the rendered page, you give the chart an endpoint and render JSON from a controller. The README frames this as making pages load fast and avoiding timeouts, and it is the right call for large series or slow aggregates. The hash and array forms are simpler, but they put the data in the HTML, which is fine for a small dashboard and less fine for a chart over a million rows.

Options are split into two layers, which is the part that trips people up. Chartkick-level options such as width, height, min, max, colors, stacked, discrete, label, xtitle, ytitle, curve, points, legend, donut, loading, empty and refresh are handled by the gem. Anything else goes through library: or dataset: and is passed to the underlying charting library untouched. The README says you can pass dataset options to individual series as well. The practical consequence is that when a chart misbehaves, you need to know which layer owns the setting.

Installing the Chartkick gem and rendering a first chart

Add the gem to your Gemfile. The README's Quick Start gives exactly this line.

gem "chartkick"

Then install it and follow the README's instructions for your JavaScript setup. Rails default is Importmap, so in config/importmap.rb you pin the two files the README names.

pin "chartkick", to: "chartkick.js"
pin "Chart.bundle", to: "Chart.bundle.js"

In app/javascript/application.js you import both. This is what wires the helper output to Chart.js in the browser.

import "chartkick"
import "Chart.bundle"

If you use Bun, esbuild, rollup.js or Webpack instead, the README says to add the packages with bun add chartkick chart.js or yarn add chartkick chart.js, and then import the Chart.js entry point in application.js.

import "chartkick/chart.js"

With that in place, a chart is one line in a view. The README's column chart example uses a Groupdate aggregate with a formatted hour label.

<%= column_chart Task.group_by_hour_of_day(:created_at, format: "%l %P").count %>

You should see a column chart rendered by Chart.js, with the hours on the x-axis and the task counts on the y-axis. If the chart area is blank, the usual cause is a missing import or pin, not the helper call. To set options across every chart in the app rather than per call, the README says to create config/initializers/chartkick.rb.

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

What Chartkick does not do, and when that matters

The gem is a thin layer, and thin layers inherit the limits of what they wrap. Geo charts and timelines require Google Charts, so if you are on Chart.js and need a map, you are changing library or going elsewhere. Several formatting options are marked as Chart.js and Highcharts only, which means the same helper call can behave differently depending on which library is loaded. Switching libraries later means changing your asset configuration.

The data source is the other real constraint. The URL form solves page weight and timeouts, but it moves the work to a JSON endpoint that you now own: caching, authorization and query cost all become your problem rather than the gem's. The hash and array forms avoid that endpoint but embed the data in the HTML. A chart over a big table is a design decision you make before you write the helper call, not after.

Finally, Chartkick has no opinion about your queries. Many examples in the README lean on Groupdate to produce the aggregate, and the README names Groupdate, Hightop and ActiveMedian as companions. If your data is not already shaped as labels and values, the one-line chart is one line plus whatever work it takes to get there.

Chartkick compared with calling Chart.js directly

The honest alternative is not another Ruby gem; it is writing the Chart.js configuration yourself, or using a JavaScript charting component in whatever frontend framework you have. The difference is where the abstraction sits. Chartkick keeps the chart definition in Ruby, next to the query, and emits JavaScript. Direct Chart.js keeps the chart definition in JavaScript, next to the rest of your frontend, and gives you the full option surface without a translation layer.

If your charts are server-rendered and driven by ActiveRecord aggregates, Chartkick's placement is the advantage: the query and the chart live in the same file and the same language. If your charts are part of a JavaScript application, with client-side state, custom tooltips, or interactions that Chart.js exposes but Chartkick does not forward, the translation layer is friction. The library: and dataset: escape hatches in the README mean you are never fully blocked, but once most of your options are passing through those, you have paid for the abstraction without using it.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-10-22. The README shows a GitHub Actions build badge, and a CHANGELOG.md sits at the repository root, which is where release history would be recorded; the repository has no published releases, so pin the gem version in your Gemfile and read the changelog before upgrading rather than assuming a smooth path.

Chartkick is MIT licensed. That is permissive and standard for a Ruby gem, but the licence covers Chartkick only. The charting library you load alongside it is a separate dependency with its own terms: Chart.js, Google Charts and Highcharts are each governed by their own licences, and Highcharts in particular is not the same kind of licence as Chart.js. Check each one against how you are using it. Nothing here is legal advice.

The upgrade cost is mostly in the JavaScript side. Because the gem delegates rendering to a library you load yourself, a major version bump in that library can change chart behaviour without any change to your Ruby. The README's library: and dataset: options are the escape hatch, but they also mean your views may contain configuration that depends on a specific library version.

Editorial conclusion

Adopt Chartkick if your charts come from ActiveRecord aggregates and you want them rendered inside ERB without writing chart configuration by hand. Do not adopt it if you need interactive or bespoke visualizations that go beyond what Chart.js, Google Charts or Highcharts expose through the library and dataset options. Before committing, check which charting library your asset pipeline already loads, confirm that the options you need are marked for that library in the README (several formatting options list only Chart.js and Highcharts), and verify the data path for your largest chart, because the URL data source moves the data into a separate JSON endpoint while the hash form embeds the data in the page.

Frequently asked questions

Official sources

1. ankane/chartkick on GitHub
2. Issues
3. License: MIT
4. Project website
5. README