Allows for defining custom JavaScript powered widgets.

Example

Here's how we could define a minimal widget that embeds the given HTML directly into the page.

defmodule Kino.HTML do
  use Kino.JS

  def new(html) do
    Kino.JS.new(__MODULE__, html)
  end

  asset "main.js" do
    """
    export function init(ctx, html) {
      ctx.root.innerHTML = html;
    }
    """
  end
end

Let's break down the API.

To define a custom widget we need to create a new module, conventionally under the Kino. prefix, so that the end user can easily autocomplete all available widgets. In this case we go with Kino.HTML.

We start by adding use Kino.JS, which makes our module asset-aware. In particular, it allows us to use the asset/2 macro to define arbitrary files directly in the module source.

All widgets require a main.js file that defines a JavaScript module and becomes the entrypoint on the client side. The JavaScript module is expected to export the init(ctx, data) function, where ctx is a special object (discussed in detail later) and data is the widget data passed from the Elixir side. In our example the init function accesses the root element with ctx.root and overrides its content with the given HTML string.

Finally, we define the new(html) function that builds widgets with the given HTML. Underneath we call Kino.JS.new/2 specifying our module as the widget type and passing the data (available in the JavaScript init function later). Again, it's a convention for each widget module to define a new function to provide uniform experience for the end user.

Assets

We already saw how to define a JavaScript (or any other) file using the asset/2 macro, however in most cases it's preferable to put assets in a dedicated directory to benefit from syntax highlighting and other editor features. To do that, we just need to specify where the corresponding directory is located:

use Kino.JS, assets_path: "lib/assets/html"

URLs

When using multiple asset files, make sure to use relative URLs. For example, when adding an image to the page, instead of:

<img src="/images/cat.jpeg" />

Do:

<img src="./images/cat.jpeg" />

This will correctly point to the images/cat.jpeg file in your assets.

Security

Note that all assets are assumed public and Livebook doesn't enforce authentication when loading them. Therefore, never include any sensitive credentials in the assets source, instead pass them as arguments from your Elixir code.

JavaScript API

In the example we briefly introduced the ctx (context) object that is made available in the init(ctx, data) function. This object encapsulates all of the Livebook-specific API that we can call on the JavaScript side.

Properties

• ctx.root - the root element controlled by the widget

Functions

• ctx.importCSS(url) - loads CSS from the given URL into the page. Returns a Promise that resolves once the CSS is loaded

• ctx.handleEvent(event, callback) - registers an event handler. Once event is broadcasted, callback is executed with the event payload. This applies to Kino.JS.Live widgets

• ctx.pushEvent(event, payload) - sends an event to the widget server, where it is handled with Kino.JS.Live.handle_event/3. This applies to Kino.JS.Live widgets

CDN

It is possible to use a regular JavaScript bundler for generating the assets, however in many cases a simpler and preferred approach is to import the necessary dependencies directly from a CDN.

To give a concrete example, here's how we could use the mermaid JavaScript package for rendering diagrams:

defmodule Kino.Mermaid do
  use Kino.JS

  def new(graph) do
    Kino.JS.new(__MODULE__, graph)
  end

  asset "main.js" do
    """
    import "https://cdn.jsdelivr.net/npm/mermaid@8.13.3/dist/mermaid.min.js";

    mermaid.initialize({ startOnLoad: false });

    export function init(ctx, graph) {
      mermaid.render("graph1", graph, (svgSource, bindListeners) => {
        ctx.root.innerHTML = svgSource;
        bindListeners && bindListeners(ctx.root);
      });
    }
    """
  end
end

And we would use it like so:

Kino.Mermaid.new("""
graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
""")

Live widgets

So far we covered the API for defining static widgets, where the JavaScript side only receives the initial data and there is no further interaction with the Elixir side. To introduce such interaction, see Kino.JS.Live as a next step in our discussion.