Matthew Conlen is a computer science researcher and information designer based in Seattle, Washington. He collaborates with journalists, scientists, and engineers to tell stories and unlock insights with data.
Using Apparatus with Idyll
Combining the two tools gets us one step closer to an authoring environment with interactivity at its core.
December, 2017

Apparatus, a project by Toby Schachman and Joshua Horowitz, is a hybrid graphics editor and programming environment for creating interactive diagrams. They offer an online editor that allows authors to use a direct-manipulation style interface to create paramaterized interactive widgets. This video offers a quick overview:

In this post I’ll show how Apparatus graphics can be embedded in Idyll documents, and how a two way binding between Idyll variables and Apparatus attributes can be created.


First, we need an Apparatus figure. I’ll use an existing example for the purposes of this walkthrough. It displays a visual technique for thinking about summations of consecutive odd numbers starting with one: they always add to a perfect square! Drag the handle in this graphic to see:

The graphic provides a geometric intuition for why this mathematical statement would hold true. The next odd number always completes the next outer “layer” of the square. Internally, this Apparatus figure keeps track of a single state variable, N, that determines how things are rendered on your screen. Currently N is 0.

I’ve created a new Apparatus component that makes it easy to embed these graphics in your Idyll documents. Here’s the code to embed that interactive graphic:

  _url: “path/to/sum-of-odds.json”
  _regionOfInterest: roi
  _width: 300
  _height: 300 /]

The _regionOfInterest parameter tells Apparatus where to focus, and can be passed in like { x: [-1, 1], y: [-1, 1] }. The parameters starting with an underscore are used to configure Apparatus; other parameters will configure the graphic itself (you’ll see more below).

Communicating with the document

The above code is nice in that it makes things easy to embed, but it doesn’t really do a whole lot. Idyll’s reactive variable system is a natural match for the architecture that Apparatus uses, and this new component makes it easy to create two way bindings between Idyll variables and Apparatus attributes.

For example, I can create an Idyll variable, and connect it to the N attribute:

Move slider to update Idyll variable.


Drag on the square below and notice the slider move.

Updating works in both directions! Here’s the code to make this work:

[var name:“IdyllN” value:0 /]

**Move slider to update Idyll variable:**
[Range value:IdyllN min:0 max:10 /]
[Display var:IdyllN /]

**Drag on the square below and notice the slider move.**
  _url: “path/to/sum-of-odds.json”
  _regionOfInterest: roi
  _width: 300
  _height: 300
  N:IdyllN /]

This code creates a variable in Idyll, called IdyllN and binds it to the N attribute from apparatus. If you interact with the Apparatus figure and change the size of the square, this change gets propagated back to Idyll. Similarly, taking an action that would modify the Idyll variable, for example moving a slider, will also cause the Apparatus figure to get updated.

For fun

Here’s another example, modified from Bret Victor’s figure on the Apparatus example gallery. It’s a fully interactive Apparatus figure; click and drag the sun to change the time of day and growth of the plant.

By parameterizing the figure with Idyll variables, we can quickly turn this into an animated graphic:

The component is open source and available at Thanks to Josh Horowitz for all of his help getting this to work!

Learn more about the two projects:

See the source for this post.