Anywidget: Custom Jupyter Widgets Made Easy

Warnings

• breaking Since v0.9, the preferred way to define front-end widget code has shifted to using lifecycle hooks (`initialize`, `render`) exported as a default object from the `_esm` module, replacing the direct `export function render(view)` pattern.
  Fix: Refactor your `_esm` JavaScript to `export default { initialize({ model }), render({ model, el }) { ... } };`. The `render` function's argument `view` is now split into `{ model, el }`.
• breaking If you are using the Vite plugin for `anywidget`, the import path for it changed from `anywidget/vite` to `@anywidget/vite` to allow for independent versioning.
  Fix: Update your Vite configuration (e.g., `vite.config.mjs`) to `import anywidget from "@anywidget/vite";`.
• gotcha Hot Module Replacement (HMR) for live development requires opting in by either setting the `ANYWIDGET_HMR` environment variable to `1` or, preferably, referencing frontend code via `pathlib.Path` for `_esm` and `_css` attributes.
  Fix: For in-notebook prototyping, define `_esm` and `_css` as `pathlib.Path('index.js')` (or similar) to external files, and ensure the `ANYWIDGET_HMR` environment variable is set if you expect HMR without explicit file paths.
• gotcha The `__repr__` method for `AnyWidget` subclasses was overridden to provide a less verbose, `object.__repr__` like output, instead of the full serialization of all trait values inherited from `ipywidgets.Widget`.
  Fix: Be aware that inspecting `AnyWidget` instances directly might no longer show a full dump of all synchronized traits. For trait values, access them directly (e.g., `widget.count`).
• gotcha Custom messages sent from Python (`widget.send()`) will only be received by the frontend if the widget's view has already been rendered (i.e., the widget has been `display()`ed). Sending messages before the widget is displayed will result in them being lost.
  Fix: Ensure that the `AnyWidget` instance is displayed in the notebook or environment before sending any custom messages from the Python kernel.
• breaking For `anywidget` framework bridges like `@anywidget/react` and `@anywidget/svelte`, there have been breaking changes to align with newer versions of their respective frameworks (React 18's `useSyncExternalStore` and Svelte 5's runes reactivity). This primarily affects users building widgets with these specific frontend frameworks.
  Fix: Refer to the `anywidget` release notes and the specific framework bridge documentation for migration guides if you are using `@anywidget/react` or `@anywidget/svelte`.

Install

• pip install "anywidget[dev]" For development with HMR
• pip install anywidget Minimal installation
• conda install -c conda-forge anywidget Conda installation

Imports

• AnyWidget

  from anywidget import AnyWidget

• Int

  import traitlets
  class MyWidget(AnyWidget):
      value = traitlets.Int(0).tag(sync=True)

  Used for defining synchronized state between Python and JavaScript.
• Unicode

  import traitlets
  class MyWidget(AnyWidget):
      text = traitlets.Unicode('Hello').tag(sync=True)

  Used for defining synchronized string state.

Quickstart

This example defines a simple counter widget using `anywidget.AnyWidget`. It includes both Python (`traitlets.Int`) and JavaScript (`_esm`) components. The JavaScript code defines how the widget renders and interacts with the Python backend, including handling button clicks and updating a synchronized `count` traitlet. The `initialize` and `render` lifecycle hooks are the preferred way to define the frontend logic since v0.9.

import anywidget
import traitlets
from IPython.display import display

class CounterWidget(anywidget.AnyWidget):
    _esm = """
    export default {
        initialize({ model }) {
            // Optional: run once per widget instance
            console.log('Widget initialized');
        },
        render({ model, el }) {
            let getCount = () => model.get('count');
            let button = document.createElement('button');
            button.innerHTML = `count is ${getCount()}`;

            button.addEventListener('click', () => {
                model.set('count', getCount() + 1);
                model.save_changes();
            });

            model.on('change:count', () => {
                button.innerHTML = `count is ${getCount()}`;
            });
            el.appendChild(button);

            return () => {
                // Optional: cleanup on view removal
                button.removeEventListener('click', () => {});
            };
        }
    };
    """
    _css = """ button { padding: 5px 10px; border-radius: 5px; background-color: #f0f0f0; } """
    count = traitlets.Int(0).tag(sync=True)

widget = CounterWidget()
display(widget)
# You can also interact with the widget from Python
# widget.count = 5 # This will update the frontend