anywidget.dev

Build an anywidget by installing the package, subclassing anywidget.AnyWidget, supplying a front-end render function through the _esm attribute, and declaring synchronized state with traitlets. The official example on anywidget.dev does exactly this with a counter: a Python class holds count, and the browser-side render function reads and writes that value through the model. This approach fits you if you want a reusable widget that works across notebook and app frameworks without rewriting the front end for each one.

Install anywidget

pip install anywidget

The site shows this as the starting command. No configuration or build step appears in the example.

Define the widget class

Create a module (the example uses mywidget/__init__.py) that subclasses AnyWidget and declares synchronized traits:

import anywidget
import traitlets

class CounterWidget(anywidget.AnyWidget):
    _esm = """
    function render({ model, el }) {
      let count = () => model.get("count");
      let btn = document.createElement("button");
      btn.innerHTML = `count is ${count()}`;
      btn.addEventListener("click", () => {
        model.set("count", count() + 1);
        model.save_changes();
      });
      model.on("change:count", () => {
        btn.innerHTML = `count is ${count()}`;
      });
      el.appendChild(btn);
    }
    export default { render };
    """
    count = traitlets.Int(0).tag(sync=True)

Two pieces matter here:

• _esm holds the front-end JavaScript as an ES module string. It must export a default object with a render function.
• count = traitlets.Int(0).tag(sync=True) declares the state that stays in sync between Python and the browser. The sync=True tag is what makes the value travel across the boundary.

Understand the render contract

The render function receives an object with model and el:

In the counter, clicking the button increments the value, saves it, and the change:count listener updates the button label. This is the full round trip: browser action → model update → Python state → back to the browser.

Use it in a notebook

from mywidget import CounterWidget

counter = CounterWidget()
counter

Displaying the instance renders the widget. You can then inspect or set state from Python:

counter.count

Because the trait is synchronized, reading counter.count reflects clicks made in the browser, and setting it from Python updates the button.

Common sticking points

• Missing export default in _esm — the module must export { render } or the widget will not mount.
• Forgetting save_changes() — model.set alone stages a value; without saving, Python never sees it.
• No sync=True tag — an untagged trait stays on one side and will not update the other.
• Editing _esm after instantiation — the front end is defined at class level, so change the class and re-instantiate.

Why this pattern is portable

The site frames anywidget as "Beyond Frameworks, a Widget Standard," describing a talk from SciPy 2024 about setting a standard for portable widgets while keeping ecosystem compatibility. Practically, that means the same class and _esm you write here is intended to travel across environments rather than being tied to one framework's widget API. If portability across notebook and app contexts is your goal, this is the reason to choose anywidget over a framework-specific widget base class.

The fastest starting point is the official anywidget site itself: it shows the install command (pip install anywidget), a complete minimal widget file, and how that widget is used inside a notebook. If you want a conceptual companion to the code, the site also points to a SciPy 2024 talk titled "Beyond Frameworks, a Widget Standard," which explains how anywidget positions itself as a portable widget standard while staying compatible with the existing Jupyter ecosystem.

The official example, end to end

The site's example is a counter widget split across two places: a Python module and a notebook cell.

1. Install

pip install anywidget

2. Define the widget in mywidget/__init__.py

import anywidget
import traitlets

class CounterWidget(anywidget.AnyWidget):
    _esm = """
    function render({ model, el }) {
      let count = () => model.get("count");
      let btn = document.createElement("button");
      btn.innerHTML = `count is ${count()}`;
      btn.addEventListener("click", () => {
        model.set("count", count() + 1);
        model.save_changes();
      });
      model.on("change:count", () => {
        btn.innerHTML = `count is ${count()}`;
      });
      el.appendChild(btn);
    }
    export default { render };
    """
    count = traitlets.Int(0).tag(sync=True)

Three things are worth noticing in this structure:

• _esm holds the JavaScript as a string, so the widget ships as a single Python file rather than a separate front-end build.
• render({ model, el }) is the entry point anywidget calls; el is the DOM element you attach to.
• count = traitlets.Int(0).tag(sync=True) is what makes the Python attribute and the JavaScript model stay in step.

3. Use it in a notebook

from mywidget import CounterWidget

counter = CounterWidget()
counter

Then read or write the synced state directly:

counter.count

The site's example runs at a local notebook server (the page shows a localhost:8888/Demo.ipynb path), so the expected result is a rendered button in the output cell whose label updates as you click, with counter.count reflecting the same value in Python.

What each piece is doing

Where to go next

• The official site is the primary reference for the install command and the counter example above.
• The SciPy 2024 talk, "Beyond Frameworks, a Widget Standard," is the site's pointer for understanding how anywidget relates to existing widget frameworks and the wider Jupyter ecosystem — useful if you already know other widget libraries and want to know where anywidget fits.
• Your own notebook is the verification step: once the counter renders and counter.count tracks your clicks, you have a working baseline to swap in your own _esm and traits.

A practical next task: copy the counter into a module of your own, rename the trait, and confirm that changing it from Python updates the button label — that exercises the sync path in both directions before you build anything more complex.

anywidget syncs state through a traitlets model on the Python side and a model object on the JavaScript side. You declare a trait with .tag(sync=True), and anywidget wires it to the front end: JavaScript reads it with model.get("name"), writes it with model.set("name", value) followed by model.save_changes(), and reacts to changes with model.on("change:name", callback). The render({ model, el }) function in _esm receives that model plus a DOM element to mount into.

This matters if you want a widget whose Python state and browser UI stay consistent without hand-writing a comm protocol or depending on a specific notebook framework. The example below is the CounterWidget from the anywidget site.

The two halves of the sync

Python side: declare a synced trait

import anywidget
import traitlets

class CounterWidget(anywidget.AnyWidget):
    _esm = """
    function render({ model, el }) {
      let count = () => model.get("count");
      let btn = document.createElement("button");
      btn.innerHTML = `count is ${count()}`;
      btn.addEventListener("click", () => {
        model.set("count", count() + 1);
        model.save_changes();
      });
      model.on("change:count", () => {
        btn.innerHTML = `count is ${count()}`;
      });
      el.appendChild(btn);
    }
    export default { render };
    """
    count = traitlets.Int(0).tag(sync=True)

count = traitlets.Int(0).tag(sync=True) is the whole Python-side contract. The trait's default is 0, its type is Int, and sync=True marks it as shared with the front end. anywidget handles serialization and transport; you don't write comm code.

JavaScript side: read, write, and listen

Inside render, the model argument is your handle to that shared state:

The set / save_changes split is the key detail. model.set alone updates the JS-side model but does not push to Python; model.save_changes() is what commits it. In the counter, the click handler does both, so a button click increments the Python trait.

How a click flows through the system

1. The user clicks the button. The listener calls model.set("count", count() + 1).
2. model.save_changes() commits the new value, which propagates to the Python count trait.
3. The model.on("change:count", ...) listener fires and rewrites btn.innerHTML to count is N.

The listener is what keeps the DOM in step with the model. Without it, the button label would go stale on changes that originate outside the click handler — for instance, if Python code sets counter.count = 5 directly. Because the listener re-renders from model.get("count") rather than from a local variable, both directions stay consistent.

Mounting: what render receives and returns

render({ model, el }) is called with two things:

• model — the synced state object described above.
• el — a DOM element anywidget provides as the widget's container.

You attach your UI to el (el.appendChild(btn)). The function returns nothing; the export default { render } at the end of _esm is how anywidget discovers the entry point. _esm holds the ES module source as a string, so the widget ships its own front-end code with no separate build step shown here.

What this design buys you

The site frames anywidget as "Beyond Frameworks, a Widget Standard" — a talk from SciPy 2024 about setting a standard for portable widgets while keeping ecosystem compatibility. The sync mechanism is the reason that portability works: the Python/JS contract is just synced traits plus a render function, so the same widget definition isn't tied to one front-end framework's state system.

Practical checks before you build

• Every shared value needs sync=True. A trait without it stays Python-only and model.get won't see it.
• Call save_changes() after set. Forgetting it is the most common reason a JS-side change never reaches Python.
• Drive the DOM from listeners, not local copies. Re-read via model.get inside change: handlers so external updates render correctly.
• Start from the documented install path. The site's Get Started flow is pip install anywidget, then a mywidget/__init__.py module, then use it in a notebook (the example runs at localhost:8888/Demo.ipynb).

If your widget only needs Python to push values into a view, you can skip the write path and use model.on alone. If it needs two-way interaction — a counter, a form, a canvas editor — the full get / set / save_changes / on loop is what keeps both sides in agreement.

anywidget is a lightweight standard for building reusable interactive widgets in notebook environments. You define a widget as a Python class (using traitlets) plus a JavaScript render function, and anywidget handles the wiring between them. It's aimed at people who want portable widgets that stay compatible with the existing ecosystem rather than being locked to one framework. If you work in Jupyter-style notebooks and want a small, reusable interactive component, it's relevant to you.

The core idea

The project describes itself as "reusable widgets made easy" and frames its goal as going "beyond frameworks" to offer a widget standard — a portable way to define widgets while maintaining ecosystem compatibility.

In practice, a widget is two pieces:

• A Python class that holds state as traitlets and declares which traits sync to the front end.
• A JavaScript render function (embedded as an ESM string) that builds the DOM and reacts to model changes.

anywidget connects the two: trait changes propagate to JavaScript, and JavaScript can push changes back to Python.

A minimal example

The site's example is a counter widget. The Python side:

import anywidget
import traitlets

class CounterWidget(anywidget.AnyWidget):
    _esm = """
    function render({ model, el }) {
      let count = () => model.get("count");
      let btn = document.createElement("button");
      btn.innerHTML = `count is ${count()}`;
      btn.addEventListener("click", () => {
        model.set("count", count() + 1);
        model.save_changes();
      });
      model.on("change:count", () => {
        btn.innerHTML = `count is ${count()}`;
      });
      el.appendChild(btn);
    }
    export default { render };
    """
    count = traitlets.Int(0).tag(sync=True)

What each part does:

• _esm holds the JavaScript that renders the widget. The render function receives { model, el } — el is the container to append to, model is the synced state.
• model.get("count") reads the current value; model.set(...) followed by model.save_changes() writes it back to Python.
• model.on("change:count", ...) re-runs your handler when the value changes, so the UI stays in sync.
• count = traitlets.Int(0).tag(sync=True) declares the trait and marks it for two-way sync.

Using it in a notebook:

from mywidget import CounterWidget

counter = CounterWidget()
counter

Then counter.count reads the current value from Python.

When to use it

anywidget fits when you want:

• A reusable widget packaged as a normal Python module, not a one-off notebook cell.
• Portability across notebook environments rather than a dependency on a specific widget framework.
• A small surface area — a Python class and a JS render function, with sync handled for you.

It's less about providing a large library of prebuilt widgets and more about giving you a standard to build your own on.

Getting started

The entry point shown on the site is:

pip install anywidget

From there, the pattern is: create a module (e.g. mywidget/__init__.py), define an AnyWidget subclass with an _esm string and synced traits, then import and instantiate it in a notebook. The site's demo runs in a notebook at localhost:8888/Demo.ipynb.

For background on the design goals, the site references a SciPy 2024 talk, "Beyond Frameworks, a Widget Standard," about how anywidget sets a standard for portable widgets while maintaining ecosystem compatibility.

anywidget positions itself as "Beyond Frameworks, a Widget Standard" — a portable widget standard rather than a competing framework. Based on the site's own framing, it does not ask you to replace your existing widget framework or leave the Jupyter ecosystem. Instead, it defines a reusable widget format that stays compatible with the ecosystem you already use, so a widget written once can be reused and distributed across environments. The site's tagline, "reusable widgets made easy," and its SciPy 2024 talk description both reinforce this: anywidget sets a standard for portable widgets while maintaining ecosystem compatibility.

What "Beyond Frameworks, a Widget Standard" means

The phrase signals a deliberate scope choice. Rather than being another framework that competes for adoption, anywidget aims to be the standard that widgets conform to. The site's own description of the SciPy 2024 talk states the goal directly: anywidget "sets a standard for portable widgets while maintaining ecosystem compatibility."

Two claims are packed into that:

• Portable — a widget built with anywidget is meant to move between environments rather than being locked to one framework's runtime.
• Ecosystem-compatible — it works alongside existing tooling instead of requiring a wholesale migration.

This is a positioning statement, not a feature list. The site does not enumerate which frameworks it interoperates with, so treat "compatibility" as the stated intent rather than a verified matrix of supported integrations.

How it stays compatible instead of replacing your framework

The compatibility comes from how a widget is defined. In the site's example, a widget is a Python class that subclasses anywidget.AnyWidget and declares its front-end behavior inline:

import anywidget
import traitlets

class CounterWidget(anywidget.AnyWidget):
    _esm = """
    function render({ model, el }) {
      let count = () => model.get("count");
      let btn = document.createElement("button");
      btn.innerHTML = `count is ${count()}`;
      btn.addEventListener("click", () => {
        model.set("count", count() + 1);
        model.save_changes();
      });
      model.on("change:count", () => {
        btn.innerHTML = `count is ${count()}`;
      });
      el.appendChild(btn);
    }
    export default { render };
    """
    count = traitlets.Int(0).tag(sync=True)

What this structure implies for ecosystem fit:

• It builds on traitlets, the same state/sync mechanism used across the Jupyter widget ecosystem. State like count is declared with traitlets.Int(0).tag(sync=True), so synchronization follows an established convention rather than a new one.
• The front end is plain JavaScript (_esm), not tied to a specific framework's component model. That is what makes the widget portable — the render logic is self-contained.
• The Python side stays a normal widget class, so it can be imported and used in a notebook the same way other widgets are.

The example shows the intended workflow: pip install anywidget, define the widget in mywidget/__init__.py, then in a notebook (localhost:8888/Demo.ipynb) import it and instantiate it:

from mywidget import CounterWidget
counter = CounterWidget()
counter
counter.count

Why a portable standard matters for reuse and distribution

If widgets are defined against a shared standard rather than a single framework, the payoff is in reuse and distribution:

• Write once, reuse broadly — the same widget definition can be shared without rewriting it for each environment.
• Lower distribution friction — a widget is a self-contained unit (Python class + inline front end), which is easier to package and hand to others than a framework-specific bundle.
• Ecosystem continuity — because it leans on traitlets and standard notebook usage, adopting anywidget does not mean abandoning the surrounding Jupyter tooling.

What the SciPy 2024 talk confirms about positioning

The site references "My talk from SciPy 2024 about how anywidget sets a standard for portable widgets while maintaining ecosystem compatibility." From that description, the confirmable positioning is:

How to decide

Choose anywidget if you want to author a widget once and reuse or distribute it while staying inside the Jupyter ecosystem and its traitlets-based state model. The site's own framing supports this: it is designed as a standard that coexists with existing frameworks rather than a replacement for them. If you need a confirmed list of specific framework integrations, that detail is not provided on the page — verify it against the project's documentation before committing.