weaverlet 0.3.1

OOP for Plotly Dash — make your dashboards composable.

Vanilla Dash and Dash Pages give you primitives, not encapsulation: callbacks live globally, IDs are strings you manage by hand, and the same widget can't be dropped into two apps without surgery. Weaverlet packages layout + callbacks + state into reusable Python classes, with auto-unique IDs, typed inter-component signals, and a keep_mounted router that preserves WebGL state across navigation.

Weaverlet, developed by the Observatorio Metropolitano CentroGeo, turns a Plotly Dash app into a hierarchy of reusable Python classes. Each WeaverletComponent owns its own layout, callbacks, and identifiers; you compose them into a tree, hand the root to WeaverletApp, and ship.

It's aimed at:

• Data scientists whose dashboard has outgrown a single file and needs structure.
• Dash developers who want true component reuse instead of copy-paste between apps.
• React-style developers looking for the same class-based component paradigm, server-side, in pure Python.

What Weaverlet adds on top of vanilla Dash

• Class-based encapsulation — layout, callbacks, state, and IDs live together in one class. Instantiate it twice for two independent copies that don't step on each other.
• Auto-unique IDs — the Identifier() descriptor generates a Dash-unique ID per instance. No more managing string IDs by hand or hitting DuplicateIdError when reusing a widget.
• Signal-based events — SignalComponent + SignalInput/SignalOutput/SignalTrigger replace ad-hoc dcc.Store + manual callback wiring as the canonical inter-component event bus.
• State-preserving routing (new in 0.3) — SimpleRouterComponent(keep_mounted=True) keeps every route mounted and toggles CSS, so WebGL canvases (dash-leaflet maps, dash-sylvereye graphs, Plotly WebGL) and React state (n_clicks, selections, scroll position) survive navigation.
• Session-based auth routing — AuthRouterComponent gates routes via flask.session out of the box.
• Shared context — one dict propagates to every component in the DAG; no prop-drilling, no globals.

Weaverlet vs Dash Pages

Dash Pages (built into Dash 2.5+) and Weaverlet both solve "multi-page Dash" but at different levels of abstraction. Pages is a routing convention — drop a file in pages/, register it, get a route. Weaverlet is a component framework — write classes, compose them, navigate without losing state.

Reach for Dash Pages when your dashboard is content-heavy, each page is roughly independent, you want filesystem-driven routing, and you don't need to preserve state across navigation. It's the simpler tool and ships with Dash.

Reach for Weaverlet when you have shared widget logic across pages, when WebGL components (maps, network graphs, 3D plots) shouldn't reset on navigation, when you want typed inter-component events instead of dcc.Store plumbing, or when your dashboard has grown past the "one file per page" model and needs proper encapsulation.

The two aren't mutually exclusive — Weaverlet apps can coexist alongside a Pages-based site in the same Dash deployment if that fits your migration path.

Weaverlet vs Dash All-in-One Components

All-in-One Components (AIO, built into Dash 2+) and Weaverlet share a goal — bundle a Dash widget's layout and callbacks into one unit — but they operate at different scopes. AIO is a widget pattern: subclass html.Div, register pattern-matching callbacks once at module level, give each instance a UUID aio_id. Weaverlet is a whole-app framework: a tree of components with lifecycle hooks, routing, signals, and shared context.

Reach for AIO when you're building a single reusable widget — a fancy date picker, a search box, a chart-with-controls — to drop into existing Dash apps, especially when you want many instances and need to operate on all of them at once via pattern-matching. It's the lighter pattern for one widget.

Reach for Weaverlet when you're structuring a full application — multipage, auth, signal flows, shared context, state-preserving navigation. It's the framework for the whole dashboard.

They coexist nicely. Weaverlet components are regular Dash components under the hood, so you can use AIO widgets as leaves inside a WeaverletComponent.get_layout() without friction. The reverse (Weaverlet inside an AIO) is technically possible but usually awkward — Weaverlet wants to own the lifecycle of its own tree.

What's new in 0.3.0

Released April 2026 — full notes in CHANGELOG.md.

• Dash 4.x support; Python ≥ 3.12; dependency pins relaxed (Flask / werkzeug now resolved transitively, no longer hard-pinned).
• SimpleRouterComponent(keep_mounted=True, preserve_path="/...") for state preservation across route changes.
• Top-level imports — from weaverlet import WeaverletComponent, ... works directly; no need to drill into weaverlet.base / weaverlet.components.
• Permissive get_layout signatures — components declare any subset of (pathname, hash, href, search, user, protected_route) and the router passes only what's declared.
• DashProxy under the hood so dash_extensions.javascript.assign(), Serverside(...) return wrappers, and group= multi-output callbacks all work without extra wiring.
• assets_folder auto-resolves to the user's main script directory — no manual asset path setup needed.
• 60-test pytest suite; build via pyproject.toml + hatchling.
• jupyter-dash moved to an optional extra (pip install weaverlet[jupyter]).

Install

pip install weaverlet

(or uv add weaverlet if you're on uv.)

Optional extras:

Jupyter: Dash 4 has built-in Jupyter support, no extra needed. Construct your WeaverletApp normally and pass jupyter_mode='inline' (or 'tab' / 'external') to .app.run():

wapp = WeaverletApp(root_component=...)
wapp.app.run(jupyter_mode='inline')

Quick start

A single-page app that echoes user input:

from weaverlet import WeaverletComponent, WeaverletApp, Identifier
from dash_extensions.enrich import Input, Output
from dash import html, dcc


class EchoComponent(WeaverletComponent):
    text_input_id = Identifier()
    echo_div_id = Identifier()

    def get_layout(self):
        return html.Div([
            dcc.Input(id=self.text_input_id, type="text"),
            html.Div(id=self.echo_div_id),
        ])

    def register_callbacks(self, app):
        @app.callback(Output(self.echo_div_id, "children"),
                      Input(self.text_input_id, "value"))
        def echo(text_value):
            return text_value or ""


WeaverletApp(root_component=EchoComponent()).app.run()

A multipage app with WebGL-safe state preservation:

from weaverlet import (
    WeaverletComponent, WeaverletApp, SimpleRouterComponent,
)
from dash import html


class HomePage(WeaverletComponent):
    def get_layout(self):
        return html.Div("Home — your dash-leaflet map goes here.")


class AboutPage(WeaverletComponent):
    def get_layout(self):
        return html.Div("About — switch back to Home; the map's zoom survives.")


class NotFound(WeaverletComponent):
    def get_layout(self):
        return html.Div("404")


router = SimpleRouterComponent(
    routes={"/": HomePage(), "/about": AboutPage()},
    not_found_page_component=NotFound(),
    keep_mounted=True,        # keep all routes mounted; toggle CSS only
    preserve_path="/",        # which route owns the document flow (default: first)
)
WeaverletApp(root_component=router).app.run()

Aliasing — multiple paths pointing at the same component instance — works in both modes. Under keep_mounted=True, aliased paths automatically share a single wrapper, so the same Identifier-bearing layout never mounts twice.

Examples

The examples/ folder has 14 self-contained scripts, ordered by complexity:

Compatibility

For LLM coding assistants

Weaverlet ships a ReadMe.LLM.md following the ReadMe.LLM methodology — rules, context, 14 worked examples, API signatures, and patterns specifically formatted for LLMs like Claude, GPT, and Codex. To use it from another project, drop one of these URLs into your prompt or have your assistant fetch it:

• Latest: https://cdn.jsdelivr.net/gh/observatoriogeo/weaverlet@main/ReadMe.LLM.md
• Pinned to v0.3.0: https://cdn.jsdelivr.net/gh/observatoriogeo/weaverlet@v0.3.0/ReadMe.LLM.md

There's also an llms.txt at the repo root following the llmstxt.org convention — a short index that tools like Cursor and Claude Code can auto-discover.

Contributing & support

• Bug reports and feature requests: GitHub issues.
• Tests: pip install -e ".[dev]" then pytest (60 tests, ~1 second).
• Migrating from 0.2.x? See CHANGELOG.md — most code keeps working unchanged; the main gotcha is app.run_server() → app.run() (Dash 4 removed the old name).

License

Weaverlet is open-source software licensed under the MIT license.