Create new chart types

Updated at March 16th, 2022

Protobi is a lightweight library to visualize survey data in your browser. Protobi includes a number of standard chart types, but also allows you to create your own charts.

So if you're familiar with web programming, this tutorial is for you. Protobi's API is open, and the example below shows how you how to extend it.

And in any case we're happy to create custom widgets for your specific project and we have a growing library of general charts you can import and extend.

Libraries included

Protobi includes leading visualization libraries d3.js and Plotly.js as well as utility libs like lodash.js , Backbone.js and jQuery.

You can include additional libs and stylesheets, as shown below.


Here we'll create a new chart type that uses The Wall Street Journal's Squaire algorithm to displays state data geographically as a pseudo-map with neat squares:

The WSJ Squaire chart assumes an input variable with two-character state abbreviations. For this example we have a survey with a variable s3 with exactly this: 

Define a minimal chart

In the Admin tab of the project, create a new document called squaire.js. Then press "Edit/Run..." and paste the following code there and press "Save."

This is the custom code that defines our new chart. The code below is boilerplate that extends Protobi's BasicElement to define a new SquaireChart.

You don't really need to read it in great detail, just note that there are two methods that your code will override:

  • preRender: function(callback) {}
  • render: function() {}`

The method preRender is where you'll put background calculations or code should run asynchronously in the background before rendering.

The method render is where you'll actually draw the visualization. Specifically, you'll render a DOM element referenced by this.$content.


$(function() {
$("").on("protobi-loaded", function() {
var BasicElement = protobi.widgetFactory.getView('BasicElement')

  var SquaireChart = BasicElement.extend({
    alias: "Squaire",
    className: 'element resizable squaire',
    defaultOptions: {},
    moreEvents: {},
    resizable: true,
    showMargin: false,

    events: function () {
      var parentEvents =
      if (_.isFunction(parentEvents)) {
         parentEvents =;
      return _.extend({}, parentEvents, this.moreEvents);

    renderChildren: function () {
      return false

    postInitialize: function (args) {
      var self = this;
      SquaireChart.__super__.postInitialize.apply(this, arguments);
      this.listenTo(this.tabular, 'filter', self.update)
      this.listenTo(this.model, 'change', self.update)
      this.listenTo(this.viewModel, 'change:format', this.update)

    preRender: function (callback) { 

      // ... add your calculation code here ...

      return callback(null,

    renderBody: function () {
      // ... add your rendering code here...
      this.$content.html("Hello World!!);


  protobi.widgetFactory.registerView('SquaireChart', SquaireChart)

Protobi uses Backbone.js to define charts. The above code extends the basic chart type to create a new one called "SquaireChart":

Apply the new chart

You can now apply this new chart type to any element. Create a new element. Select "Edit JSON..." and set "chartType": "SquaireChart":

Voilá, you now have a new chart that uses this code to render the element.
This doesn't do anything special yet but it will...

Define data prep

Do any calculations in the method preRender. This method is called in the background before rendering any time the element or filters change.

Here we'll just calculate the distribution of this element given its key and field attributes. Replace the method preRender as shown below:

    preRender: function (callback) {
      "use strict";
      var self = this;

      this.table = this.tabular.getDistribution(this.model, ['current']);

      return callback(null,


Include external libraries your code requires

In the Admin tab of the project, create a new process called header. This will allow you to specify any additional resources your project requires. Then press "Edit/Run..." and paste the following code there and press "Save."

At the top include any external library calls your method requires. Here we'll call the WSJ Squaire library directly from GitHub using jsDelivr:

<script type="text/javascript" src=""></script>  
<script type="text/javascript" src=""></script>  

In the example above replace 5c1804033e40da00044ff56f with your project ID which can be found in the URL.

Render the chart

Replace the line // ... add your rendering code here... with code that draws the chart as you would like to see it. Add any content to a DOM element defined by the variable this.$content.

In this example we'll adds two new <div> elements that Squaire expects, and then calls the Squaire library to render them:


 renderBody: function () {
      "use strict";

      var self = this;
      if (!self.table) return;
      var chartOptions = self.getChartOptions();
      var showMissing = this.getShowMissing()

      var mapContainer = $("<div>")

      var tipContainer = $("<div>")

      var data = {}
      this.table.getRowKeys().map(function (rowKey) {
        var freq = self.table.getFreq(
        data[rowKey] = {
          "value": freq

      var map = new Squaire(data,
            colors: d3.scale
              .domain([1, 5])
              .range(['#c9e2f5', '#0098db']),
            el: mapContainer[0]



We now have an interactive chart that displays frequencies by state as a stylized US map, and this chart type can be applied to multiple elements.


If you want this specific chart in your project, you don't need to do all the steps above. You can include the following in your header code and include code we've already written. These will define two new chartType values, "Squaire" and "MapUSStates".

Protobi has a growing library of advanced charts, and we're working on better ways to share these across projects. But for now just paste these into your header.

<link rel="stylesheet" href=""/>
<script type="text/javascript" src=""></script>
<script type='text/javascript' src=""></script>
<script type='text/javascript' src=""></script>

<script src="//"></script>
<script type='text/javascript' src=""></script>

Closing note

If you're working your way through this tutorial, yay you! This is an advanced topic. You're welcome to contact us and we'll help you get up to speed.

Was this article helpful?