Lazy loading

wybthon.lazy

lazy

Helpers for lazy-loading components with simple loading/error states.

Wybthon's lazy loaders use Python's importlib so they work with any module that is reachable at import time, including packages bundled into the Pyodide image and packages fetched via micropip. Pair them with preload_component to warm caches ahead of navigation.

Public surface:

• lazy: build a component from a loader callback returning (module_path, attr?).
• load_component: build a component directly from a known module path / attribute name.
• preload_component: eagerly import a component to populate the module cache.

See Also

• Suspense and lazy loading guide

Functions:

Name	Description
load_component	Dynamically import a module and return a component wrapping the export.
lazy	Create a lazily-loaded component from a loader callback.
preload_component	Eagerly import a component to warm caches before navigation.

load_component

load_component(module_path: str, attr: Optional[str] = None) -> Callable[[Any], VNode]

Dynamically import a module and return a component wrapping the export.

The returned function component renders a small loader until the module finishes importing. On success it renders the loaded component with the forwarded props; on error it renders a minimal error message.

Parameters:

Name	Type	Description	Default
module_path	str	Importable Python module path.	required
attr	Optional[str]	Optional attribute name on the loaded module. When omitted, the loader picks an export by convention (Page, Component, Default, or first PascalCase symbol).	None

Returns:

Type	Description
Callable[[Any], VNode]	A function component that proxies its props to the loaded
Callable[[Any], VNode]	component once it becomes available.

lazy

lazy(loader: Callable[[], Tuple[str, Optional[str]]]) -> Callable[[Any], VNode]

Create a lazily-loaded component from a loader callback.

Parameters:

Name	Type	Description	Default
loader	Callable[[], Tuple[str, Optional[str]]]	Callable returning (module_path, attr_name). The second item may be None to fall back to the standard export convention (Page, Component, Default, or first PascalCase symbol).	required

Returns:

Type	Description
Callable[[Any], VNode]	A function component that imports the target module on first
Callable[[Any], VNode]	render and forwards props to the resolved component.

Example

def UserPageLazy():
    return ("app.users.page", "Page")

Route(path="/users/:id", component=lazy(UserPageLazy))

preload_component

preload_component(module_path: str, attr: Optional[str] = None) -> None

Eagerly import a component to warm caches before navigation.

Errors are swallowed so this helper can be safely called as a "best effort" warmup (for example from a hover handler on a <Link>).

Parameters:

Name	Type	Description	Default
module_path	str	Importable Python module path.	required
attr	Optional[str]	Optional attribute name on the loaded module.	None

What's in this module

lazy defers loading a component module until the first time it mounts. Pair it with Suspense so users see a fallback while the chunk arrives.

Helper	Purpose
lazy	Wrap an async loader and return a placeholder component.
load_component	Manually load a component module (advanced).
preload_component	Warm the cache before a route is visited.

Quick example

from wybthon import Route, Router, Suspense, lazy
from wybthon.html import p


HeavyChart = lazy(load=lambda: import_module_async("app.heavy_chart"))


routes = [
    Route(path="/charts", component=HeavyChart),
]


@component
def App():
    return Suspense(
        fallback=lambda: p("Loading…"),
        children=lambda: Router(routes=routes),
    )

• load returns a coroutine that resolves to the component (or to a module from which an attribute is read, depending on the helper used).
• lazy caches the resolved component automatically.
• preload_component(loader) is handy for hover/focus warm-ups.

See also

• Concepts → Suspense and Lazy Loading
• Suspense
• Performance guide