Widgets and comms reference

The widget model that jupyter.widget(options) returns, and the comm API under jupyter.comm, with their arguments, return values and an example. Widgets and comms explains them with a full walk-through, including the view module. Examples that can run on their own show the output they produced; widgets run on the page.

This page is also a notebook. Its examples ran on the cdp-node kernel, and the output shown is what they produced.Download widgets-reference.ipynb · View on GitHub

Overview

A widget is an anywidget model: state that the kernel and its views share, and a view module that draws it. Use one for interactive output: controls, progress, a chart that updates.

A comm is the channel widgets are built on: messages both ways on a target name, with no shared state and no view. Use one to talk to a frontend extension that registered a target.

Widget model

Member	What it does
`widget.get(key)`	The current value of a state key.
`widget.set(key, value)`	Change one state key, or several at once, and sync the change to every view.
`widget.fullState()`	The full state, as the frontend sees it: anywidget's model keys (`_model_name`, `_view_name` and the rest) and the widget's own.
`widget.on(event, listener)`	Listen for state changes or custom messages from the views.
`widget.off(event, listener)`	Remove a listener added with `on`.
`widget.send(content, buffers?)`	Send a custom message to every view's `model.on("msg:custom", ...)`.
`widget.close()`	Close the model.

Comms

Member	What it does
`jupyter.comm.open(targetName, data?, options?)`	Open a comm to a target the frontend registered.
`jupyter.comm.registerTarget(targetName, handler)`	Accept comms the frontend opens on `targetName`.
`jupyter.comm.unregisterTarget(targetName)`	Stop accepting new comms on `targetName`.
`comm.send(data?, options?)`	Send a message to the frontend's end.
`comm.close(data?, options?)`	Close the comm and tell the frontend.
`comm.onMsg(handler)`	Handle messages from the frontend's end.
`comm.onClose(handler)`	Handle the comm closing, from either end.

An anywidget model, from jupyter.widget, synced with its frontend views. Display it to show a view; display it again for a second view of the same model.

jupyter.widget(options) returns it; see the jupyter reference.

State

The synced state, read and changed from the kernel.

`widget.get(key)`

get(key: string): unknown;

The current value of a state key.

Parameter	Type	Required	Description
`key`	`string`	yes	The state key.

Returns unknown: Its value, or undefined.

const w = jupyter.widget({ esm: "export default {}", state: { count: 0 } });
w.get("count"); // 0

`widget.set(key, value)`

set(key: string, value: unknown): void;
set(changes: WidgetState): void;

Change one state key, or several at once, and sync the change to every view. Fires this model's own change listeners too. After close it changes the local state only.

Parameter	Type	Required	Description
`key`	`string`	no	The state key.
`value`	`unknown`	no	Its new value.
`changes`	`WidgetState`	no	Several keys and their new values, instead of `key` and `value`.

const w = jupyter.widget({ esm: "export default {}", state: { count: 0, label: "" } });
w.set("count", 1);
w.set({ count: 2, label: "two" });

const progress = jupyter.widget({
  esm: `export default {
    render({ model, el }) {
      el.innerHTML =
        '<div class="progress-track"><div class="progress-fill"></div></div>' +
        '<div class="progress-label"></div>';
      const fill = el.querySelector(".progress-fill");
      const label = el.querySelector(".progress-label");
      const update = () => {
        const percent = Math.round(model.get("value") * 100);
        fill.style.width = percent + "%";
        label.textContent = model.get("message") + " (" + percent + "%)";
      };
      model.on("change:value", update);
      model.on("change:message", update);
      update();
    },
  };`,
  css: `
    .progress-track { width: 320px; height: 10px; border-radius: 5px; background: #e5e7eb; overflow: hidden; }
    .progress-fill { height: 100%; background: #2e6e64; transition: width 0.2s; }
    .progress-label { margin-top: 6px; font: 13px system-ui, sans-serif; color: #444; }
  `,
  state: { value: 0, message: "Starting" },
});
await jupyter.display(progress);

const files = ["january.csv", "february.csv", "march.csv", "april.csv", "may.csv"];
for (const [i, file] of files.entries()) {
  progress.set({ message: "Processing " + file, value: i / files.length });
  await new Promise((resolve) => setTimeout(resolve, 600)); // stand-in for real work
}
progress.set({ message: "Done", value: 1 });

Running from the saved notebook, with no kernel behind this page.

`widget.fullState()`

fullState(): WidgetState;

The full state, as the frontend sees it: anywidget's model keys (_model_name, _view_name and the rest) and the widget's own.

Returns WidgetState: Every state key and its value.

const w = jupyter.widget({ esm: "export default {}", state: { count: 0 } });
w.fullState(); // { _model_name: "AnyModel", _model_module: "anywidget", ..., count: 0 }

{
  _model_name: 'AnyModel',
  _model_module: 'anywidget',
  _model_module_version: '*',
  _view_name: 'AnyView',
  _view_module: 'anywidget',
  _view_module_version: '*',
  _view_count: null,
  _esm: 'export default {}',
  _anywidget_id: 'cdp-kernel.widget',
  count: 0
}

Events

State changes and custom messages from the views.

`widget.on(event, listener)`

on(event: `change:${string}`, listener: (value: unknown, previous: unknown) => void | Promise<void>): void;
on(event: "change", listener: (changes: WidgetState) => void | Promise<void>): void;
on(event: "msg:custom", listener: (content: unknown, buffers: Uint8Array[]) => void | Promise<void>): void;

Listen for state changes or custom messages from the views. change:key gets the new and previous value; change gets all the changed keys; msg:custom gets a view's model.send content.

Parameter	Type	Required	Description
`event`	depends on the overload: see the signatures	yes	`change:<key>`, `change` or `msg:custom`.
`listener`	depends on the overload: see the signatures	yes	Called for each event; may be async.

const w = jupyter.widget({ esm: "export default {}", state: { count: 0 } });
w.on("change:count", (value, previous) => console.log(previous, "->", value));
w.on("msg:custom", (content) => console.log("view sent", content));

const temperature = jupyter.widget({
  esm: `export default {
    render({ model, el }) {
      const slider = document.createElement("input");
      slider.type = "range";
      slider.min = "-20";
      slider.max = "40";
      const label = document.createElement("span");
      const update = () => {
        slider.value = String(model.get("celsius"));
        label.textContent = " " + model.get("celsius") + " °C is " + model.get("fahrenheit") + " °F";
      };
      slider.oninput = () => {
        model.set("celsius", slider.valueAsNumber);
        model.save_changes();
      };
      model.on("change:celsius", update);
      model.on("change:fahrenheit", update);
      update();
      el.append(slider, label);
    },
  };`,
  state: { celsius: 20, fahrenheit: 68 },
});

temperature.on("change:celsius", (celsius) => {
  temperature.set("fahrenheit", Math.round((Number(celsius) * 9) / 5 + 32));
});

temperature;

As the kernel left it after the docs build sent a slider move to 30 from the view. Running from the saved notebook, with no kernel behind this page.

`widget.off(event, listener)`

off(event: string, listener: (...args: never[]) => unknown): void;

Remove a listener added with on.

Parameter	Type	Required	Description
`event`	`string`	yes	The event it was added for.
`listener`	`(...args: never[]) => unknown`	yes	The same function.

const w = jupyter.widget({ esm: "export default {}", state: { count: 0 } });
const log = (value: unknown) => console.log(value);
w.on("change:count", log);
w.off("change:count", log);

Custom messages

Messages to the views that aren't state; on("msg:custom", ...) receives theirs.

`widget.send(content, buffers?)`

send(content: unknown, buffers?: Uint8Array[]): void;

Send a custom message to every view's model.on("msg:custom", ...).

Parameter	Type	Required	Description
`content`	`unknown`	yes	JSON content.
`buffers`	`Uint8Array[]`	no	Binary buffers. Default `[]`.

const w = jupyter.widget({ esm: "export default {}" });
w.send({ type: "reset" });

const dice = jupyter.widget({
  esm: `export default {
    render({ model, el }) {
      const button = document.createElement("button");
      button.textContent = "Roll 3 dice";
      button.onclick = () => model.send({ count: 3 });
      const result = document.createElement("span");
      result.style.marginLeft = "12px";
      result.style.fontSize = "24px";
      model.on("msg:custom", (message) => {
        result.textContent = message.faces + "  (total " + message.total + ")";
      });
      el.append(button, result);
    },
  };`,
});

dice.on("msg:custom", (content) => {
  const { count } = content as { count: number };
  const rolls = Array.from({ length: count }, () => 1 + Math.floor(Math.random() * 6));
  dice.send({
    faces: rolls.map((n) => "⚀⚁⚂⚃⚄⚅"[n - 1]).join(" "),
    total: rolls.reduce((a, b) => a + b, 0),
  });
});

dice;

As the kernel left it after the docs build sent a click from the view. Running from the saved notebook, with no kernel behind this page.

Closing

`widget.close()`

close(): void;

Close the model. Its views stop syncing.

const w = jupyter.widget({ esm: "export default {}" });
w.close();

Properties

Property	Type	Description
`id`	`string`	The model id (the comm id).
`closed`	`boolean`	Whether the model has been closed.

Comms

jupyter.comm opens comms and accepts the ones the frontend opens; each is a Comm object.

`jupyter.comm`

jupyter.comm: open comms, and accept comms the frontend opens.

`jupyter.comm.open(targetName, data?, options?)`

open(targetName: string, data?: { [key: string]: unknown }, options?: CommSendOptions): Comm;

Open a comm to a target the frontend registered.

Parameter	Type	Required	Description
`targetName`	`string`	yes	The frontend's target name.
`data`	`{ [key: string]: unknown }`	no	Data sent with the open message. Default `{}`.
`options`	`CommSendOptions`	no	Metadata and binary buffers.

Returns Comm: The kernel's end of the comm.

const comm = jupyter.comm.open("my.target", { hello: 1 });
comm.onMsg((m) => console.log(m.data));

`jupyter.comm.registerTarget(targetName, handler)`

registerTarget(targetName: string, handler: (comm: Comm, msg: CommMessage) => void | Promise<void>): void;

Accept comms the frontend opens on targetName. Registering the same name again replaces the handler.

Parameter	Type	Required	Description
`targetName`	`string`	yes	The target name the frontend opens comms on.
`handler`	`(comm: Comm, msg: CommMessage) => void \| Promise<void>`	yes	Called with the new comm and its open message.

jupyter.comm.registerTarget("echo", (comm) => comm.onMsg((m) => comm.send(m.data)));

`jupyter.comm.unregisterTarget(targetName)`

unregisterTarget(targetName: string): void;

Stop accepting new comms on targetName. Comms already open stay open.

Parameter	Type	Required	Description
`targetName`	`string`	yes	The target to remove.

jupyter.comm.unregisterTarget("echo");

`Comm` object

One end of a Jupyter comm channel, from jupyter.comm.open or a target handler.

`comm.send(data?, options?)`

send(data?: { [key: string]: unknown }, options?: CommSendOptions): void;

Send a message to the frontend's end. Does nothing once closed.

Parameter	Type	Required	Description
`data`	`{ [key: string]: unknown }`	no	The message's JSON data. Default `{}`.
`options`	`CommSendOptions`	no	Metadata and binary buffers.

const comm = jupyter.comm.open("my.target");
comm.send({ ping: true }, { buffers: [new Uint8Array([1, 2, 3])] });

`comm.close(data?, options?)`

close(data?: { [key: string]: unknown }, options?: CommSendOptions): void;

Close the comm and tell the frontend. Its onClose handlers start right away, without being awaited. Does nothing once closed.

Parameter	Type	Required	Description
`data`	`{ [key: string]: unknown }`	no	Data sent with the close message. Default `{}`.
`options`	`CommSendOptions`	no	Metadata and binary buffers.

const comm = jupyter.comm.open("my.target");
comm.close({ reason: "done" });

`comm.onMsg(handler)`

onMsg(handler: (msg: CommMessage) => void | Promise<void>): void;

Handle messages from the frontend's end. A handler runs like a cell: its output goes to the notebook, and an exception shows on stderr.

Parameter	Type	Required	Description
`handler`	`(msg: CommMessage) => void \| Promise<void>`	yes	Called with each message; may be async.

const comm = jupyter.comm.open("my.target");
comm.onMsg(({ data, buffers }) => console.log(data, buffers.length));

`comm.onClose(handler)`

onClose(handler: (msg: CommMessage) => void | Promise<void>): void;

Handle the comm closing, from either end.

Parameter	Type	Required	Description
`handler`	`(msg: CommMessage) => void \| Promise<void>`	yes	Called with the close message; may be async.

const comm = jupyter.comm.open("my.target");
comm.onClose(() => console.log("closed"));

Properties

Property	Type	Description
`id`	`string`	The comm id, shared with the frontend's end.
`targetName`	`string`	The target the comm was opened on.
`closed`	`boolean`	Whether either end has closed the comm.

Types

`WidgetOptions`

Options for jupyter.widget.

Property	Type	Required	Description
`esm`	`string`	yes	The anywidget view module, as source: `export default { render({ model, el }) { ... } }`. A `${...}` inside a template literal here is filled in by the kernel, not the browser: escape it as `\${...}`.
`css`	`string`	no	CSS for the view.
`state`	`WidgetState`	no	The initial synced state. `Uint8Array` and `ArrayBuffer` values travel as binary buffers. Default `{}`.

`CommMessage`

A comm message as a handler receives it.

Property	Type	Required	Description
`data`	`{ [key: string]: unknown }`	yes	The message's JSON data.
`metadata`	`{ [key: string]: unknown }`	yes	The message's metadata.
`buffers`	`Uint8Array[]`	yes	Binary buffers sent with the message.

`CommSendOptions`

Options for sending, opening or closing a comm.

Property	Type	Required	Description
`metadata`	`{ [key: string]: unknown }`	no	Metadata for the message. Default `{}`.
`buffers`	`Uint8Array[]`	no	Binary buffers sent with the message. Default `[]`.

Widgets and comms reference ​

Overview ​

Widget model ​

State ​

widget.get(key) ​

widget.set(key, value) ​

widget.fullState() ​

Events ​

widget.on(event, listener) ​

widget.off(event, listener) ​

Custom messages ​

widget.send(content, buffers?) ​

Closing ​

widget.close() ​

Properties ​

Comms ​

jupyter.comm ​

jupyter.comm.open(targetName, data?, options?) ​

jupyter.comm.registerTarget(targetName, handler) ​

jupyter.comm.unregisterTarget(targetName) ​

Comm object ​

comm.send(data?, options?) ​

comm.close(data?, options?) ​

comm.onMsg(handler) ​

comm.onClose(handler) ​

Properties ​

Types ​

WidgetOptions ​

CommMessage ​

CommSendOptions ​

Widgets and comms reference

Overview

Widget model

State

`widget.get(key)`

`widget.set(key, value)`

`widget.fullState()`

Events

`widget.on(event, listener)`

`widget.off(event, listener)`

Custom messages

`widget.send(content, buffers?)`

Closing

`widget.close()`

Properties

Comms

`jupyter.comm`

`jupyter.comm.open(targetName, data?, options?)`

`jupyter.comm.registerTarget(targetName, handler)`

`jupyter.comm.unregisterTarget(targetName)`

`Comm` object

`comm.send(data?, options?)`

`comm.close(data?, options?)`

`comm.onMsg(handler)`

`comm.onClose(handler)`

Properties

Types

`WidgetOptions`

`CommMessage`

`CommSendOptions`