manywidgets

A composable set of anywidget-based widgets for data analysis and geospatial work in notebooks. They're self-contained, link and compose, work well with lonboard, and render statically (no kernel) via the myst-anywidget-static-export MyST plugin.

Status: early but feature-complete for v1 — Chart, input controls (Slider, RangeSlider, Dropdown, Toggle, Button, NumberInput), value displays (Stat, NumberDisplay, Text), Table, GeoMap (a MapLibre map with GeoJSON, XYZ-tile and client-styled grid-raster layers), layout containers (Row, Column, Grid), the Binder linking primitive, and optional lonboard interop (LayerToggle, FilterBinder, LayerFilter).

Install

pip install manywidgets
# optional lonboard interop widgets:
pip install "manywidgets[lonboard]"

Quick start

from manywidgets import Chart, Slider, Binder
import numpy as np

chart = Chart(title="Demo", x_label="x", y_label="y", height=320)
chart.add_series(x=np.linspace(0, 10, 100), y=np.sin(np.linspace(0, 10, 100)), name="sin")
chart

Widgets

from manywidgets import (
    Chart,                                   # Chart.js charts
    Slider, RangeSlider, Dropdown, Toggle, Button, NumberInput,  # input controls
    Stat, NumberDisplay, Text, Legend,       # value displays
    Table,                                   # sortable, selectable table of records
    GeoMap, GridLayer,                       # MapLibre map: GeoJSON, XYZ tiles, quantized grid rasters
    Row, Column, Grid,                       # layout (arrange + keep children linked)
    Binder,                                  # linking with transforms / nested paths
)

# Optional lonboard interop (pip install "manywidgets[lonboard]")
from manywidgets.lonboard import LayerToggle, FilterBinder, LayerFilter

Linking widgets

Two complementary tools — see docs/guides/linking.md:

from ipywidgets import jsdlink

# 1. jslink / jsdlink — the canonical, kernel-free pass-through link.
slider = Slider(label="Amplitude", min=0, max=5, value=1)
jsdlink((slider, "value"), (chart, "title"))  # browser-side, works live + static

# 2. Binder — for transforms / nested paths jslink can't express.
Binder(source=slider, source_field="value",
       target=chart, target_field="height",
       multiplier=100, offset=200)

Agent skill

manywidgets ships an agent skill so coding agents can help you build widgets and dashboards. Install it into a location your agent discovers:

manywidgets install-skill            # ./.claude/skills/manywidgets/ (this project)
manywidgets install-skill --user     # ~/.claude/skills/manywidgets/ (all projects)
manywidgets install-skill --path DIR # anywhere else (other agents)

The skill (an entrypoint plus references/ on widget API, usage, and authoring) travels inside the wheel, so it always matches the installed version. The per-widget API reference is generated from widget traits — never hand-edited.

How it works / design

Every widget extends a thin BaseWidget (auto-assigns a stable widget_id) and follows the TypeScript "golden example" structure: src/index.ts bundled by esbuild into dist/widget.js, styling via the _css trait. Cross-widget resolution and the static-export safety rules live once in a shared @manywidgets/core TypeScript module that esbuild inlines into each widget.

This package has no code dependency on the static-export plugin — it just follows the rules the plugin needs (wrap save_changes, never inject <link> into the mount element, vanilla DOM, buffer-free core widgets, link via jslink/Binder). The docs site references the plugin by release URL only.

Development

npm install
npm run build          # esbuild every widget src/index.ts -> dist/widget.js
npm run typecheck      # tsc --noEmit
npm test               # vitest (JS unit tests)
pip install -e ".[dev]"
pytest

Docs

Each widget owns its docs in src/manywidgets/<name>/doc.md (prose + a {code-cell} example + an {api-table} placeholder). npm run docs:gen builds docs/widgets/<name>.ipynb from those — auto-generating the API table from trait introspection — so the per-widget pages are generated build artifacts (gitignored), not hand-maintained. The agent skill's API reference is generated the same way (npm run skill:gen → src/manywidgets/skill/references/widgets-api.md, which is committed and CI-checked for drift) — regenerate it after changing any widget's traits. Build and view:

# lonboard + geopandas + pyarrow are only needed for the lonboard interop example
pip install -e ".[numpy,lonboard]" ipykernel nbconvert nbformat geopandas pyarrow
python -m ipykernel install --user --name manywidgets-venv
npm run docs:gen       # generate docs/widgets/*.ipynb from each widget's doc.md
jupyter nbconvert --to notebook --execute --inplace docs/examples/*.ipynb docs/widgets/*.ipynb
cd docs && npx myst build --html && cd ..
npm run serve          # serve over HTTP at http://localhost:8000 (NOT file://)

Serve the built site over HTTP — opening the HTML via file:// breaks asset and widget loading (absolute paths + dynamic import()).

Releases are cut by publishing a GitHub Release (CI builds the wheel — with JS compiled by the build hook — and publishes to PyPI). The JS bundles are gitignored and rebuilt by the build; they ship inside the wheel.

License

MIT — see LICENSE.