Router

wybthon.router

router

Client-side router components and navigation helpers for Pyodide apps.

This module exposes the browser-facing router built on top of router_core:

• Route: declarative mapping of a path pattern to a component, optionally with nested children.
• Router: function component that renders the matched route's component and provides the BasePath context.
• Link: anchor element that navigates via the History API and toggles an active class.
• navigate: programmatic navigation helper.
• current_path: a Signal containing the current pathname plus query string.

See Also

• Routing guide

Classes:

Name	Description
Route	Declarative route definition mapping a path to a component.

Functions:

Name	Description
navigate	Programmatically change the current path and update current_path.
Router	Function component that renders the matched route's component.
Link	Anchor element component that navigates via the History API.

Attributes:

Name	Type	Description
current_path	Signal[str]	Signal containing the current pathname plus query string.

current_path module-attribute

current_path: Signal[str] = Signal(_current_url())

Signal containing the current pathname plus query string.

Updated by navigate and by the global popstate listener (back/forward navigation). Read it inside reactive scopes to re-render when the URL changes.

BasePath module-attribute

BasePath = create_context('')

Context used by the router to expose the active base path.

Link reads this context so that relative to paths are resolved against the same base path the surrounding Router is mounted under.

Route dataclass

Route(path: str, component: Union[Callable[[Dict[str, Any]], VNode], type], children: Optional[List['Route']] = None)

Declarative route definition mapping a path to a component.

Attributes:

Name	Type	Description
path	str	Route pattern (e.g. "/users/:id", "/docs/*").
component	Union[Callable[[Dict[str, Any]], VNode], type]	A function component or class to render when the path matches.
children	Optional[List['Route']]	Optional nested routes whose paths are joined with this route's path.

navigate

navigate(path: str, *, replace: bool = False) -> None

Programmatically change the current path and update current_path.

Parameters:

Name	Type	Description	Default
path	str	Target URL path, including any query string.	required
replace	bool	When True, use history.replaceState so the current history entry is overwritten instead of appended.	False

Router

Router(props: Any) -> Any

Function component that renders the matched route's component.

The render function is wrapped in a reactive hole so that updates to current_path automatically re-evaluate the matched route; no parent re-render is required.

Parameters:

Name	Type	Description	Default
props	Any	The component's props with the following keys: routes (List[Route]): Declared routes. base_path (str): Base path stripped before matching. not_found: Optional component rendered when no route matches. Falls back to a literal "Not Found" <div>.	required

Returns:

Type	Description
Any	A reactive VNode containing the matched
Any	component, wrapped in a Provider that
Any	publishes the active base_path via
Any	BasePath.

Link

Link(props: Any) -> Any

Anchor element component that navigates via the History API.

Wrapped in a reactive hole so the active class flips automatically when the route changes; no parent re-render is required. Modifier-key clicks (Cmd/Ctrl/Shift) and middle-clicks are passed through to the browser so users can open links in a new tab.

Parameters:

Name	Type	Description	Default
props	Any	The component's props with the following keys: to (str): Target path. Joined with the active base path unless it starts with http://, https://, or #. replace (bool): When True, replace the current history entry instead of pushing a new one. class_active (str): Class added when to matches the current path. Defaults to "active". base_path (str): Override for the base path. Defaults to the value provided by the surrounding Router. class / class_ / className: Recognized class spellings, merged with the active class when applicable. All other props are forwarded to the underlying <a> element.	required

Returns:

Type	Description
Any	A reactive VNode for the anchor element.

API

• class Route(path: str, component, children: Optional[List[Route]] = None)
• class Router(routes: List[Route], base_path: str = "", not_found: Optional[Callable[[Dict], VNode]] = None)
• function Link({to: str, children, base_path?: str, replace?: bool, class_active?: str})
• function navigate(path: str, replace: bool = False)
• signal current_path – reactive signal with current path + search

Notes:

• Wildcard path segment * captures the rest of the path into params["wildcard"].
• Trailing /* also matches the base segment; e.g. /docs/* matches /docs and /docs/guide.
• Nested routes use children and resolve to the most specific match.
• Link automatically adds an active CSS class (default: "active") when its href matches the current pathname. Customize with class_active. Use replace=True to avoid pushing a new history entry.