KGJS is a JavaScript engine that takes a description of an interactive graph and renders that graph in a browser. Fundamentally, it uses a number of amazing open-source JavaScript technologies – D3 for drawing 2D diagrams, MathBox for drawing 3D diagrams, mathjs for easy math description, KaTeX for displaying math, as well as bits and pieces of underscore and js-yaml for parsing things – and it tries to create an author-friendly way of creating interactive graphs. All of these are bundled along with KGJS in a single JS file and CSS file.
The engine understands JSON as the language describing the graphs, but as an author you can use YAML, which is then translated into JSON. This is generally easier to read and edit.
Getting up and running with KGJS is quite simple: you just need a single Javascript file and a single CSS file. Each div with class kg-container that contains a graph definition will be rendered in place. You can start by downloading this Hello World HTML file and open it in a browser; you can edit it in a text editor to have an instant playground.
In all of these documentation pages, you’ll be able to also play with live code and see how it renders; you can take that code and paste it into a local HTML document if you’d like to experiment more offline. For example, the following live code editor has the same graph as in the Hello World HTML file. Try changing the coordinates or the colors of the points:
The key to an interactive graph, of course, is interactivity: that is, the ability of the user to change things. KGJS handles this by defining a set of parameters that the user can change, and then making it easy to adjust the parameters by dragging objects or using sliders:
Notice that the min, max, and round attributes of blueX aren’t set; KGJS will set sensible defaults (round to the nearest integer, don’t allow dragging off the graph) whenever possible. By contrast, these attributes are set for redY, so the dot snaps to every 0.25 instead of every integer.
Use the navigation links to the left to learn about drawing graph objects, defining user interactions, and creating complex layouts with multiple graphs.
My name is Chris Makler; I’m an economist by training, not a software developer, as you’ll quickly find out if you look at the source code on Github. I have developed this code to support my research project, econgraphs.org, which I use in my own teaching and consider a public good for other teaching economists who might find it useful.
I have drawn inspiration and guidance from the community Nicky Case has build up around Explorable Explanations, including but certainly not limited to Amit Patel, Chris Walker, Hamish Todd, Andy Matuschak, and Matthew Conlen. I’m also a huge fan of desmos.com, idyll, and slides.com, which I use for my own teaching because I can embed these diagrams within it. I also owe a debt of gratitude to a host of former colleagues who helped introduce me to the black art of coding, including David Murphy, Karl Lew, Wilson Cheung, Harrison Caudill, and Kyle Moore.
Finally, a huge thanks to my students Avery Rogers and Chris Hull for their help in creating this documentation.