API Reference

🔧 Router Lifecycle

create_router

create_router(routes: dict, outlet: RouterOutlet, transition_handler: Optional[Callable] = None) -> Router

Creates and registers the global singleton Router instance.

• routes: A dictionary mapping paths to view classes or route configs
• outlet: The RouterOutlet container where views render
• transition_handler: Optional fallback transition function

Example

create_router(ROUTES, outlet)

Initializes the global router with your route map and main outlet container.

---

get_router

get_router() -> Router

Returns the globally registered Router.
Raises RuntimeError if create_router() hasn’t been called.

Example

router = get_router()

Retrieves the global router instance. Useful for navigating or registering listeners.

---

📦 Router Methods

navigate

navigate(path: str, transition: Optional[Callable] = None)

Navigates to a route. Handles parameters, query strings, guards, transitions, and history.

Example

get_router().navigate("/users/42?tab=profile")

---

back

back()

Navigates to the previous route in the history stack.

---

forward

forward()

Navigates forward in the history stack.

---

go

go(delta: int)

Navigates by a relative offset (e.g., -1 to go back, 1 to go forward).

---

on_change

on_change(callback: Callable[[str, dict], None])

Registers a listener to respond to route changes.

Example

get_router().on_change(lambda path, params: print("Route changed:", path))

---

🗺️ Route Config Format

ROUTES = {
    "/": HomePage,
    "/about": AboutPage,
    "/users/<id>": {
        "view": UserDetailPage,
        "guard": is_logged_in,
        "redirect": "/login",
        "transition": slide_transition
    }
}

Supports dynamic segments (<id>), route guards, custom transitions, and redirects.

---

🎛️ Routed Widgets

RouteLinkButton

RouteLinkButton(master, to: str, params: dict = None, **kwargs)

A button that navigates to a route when clicked.

Example

RouteLinkButton(self, "/about", text="Go to About")

---

RouteLinkLabel

RouteLinkLabel(master, to: str, params: dict = None, **kwargs)

A label that acts like a hyperlink and navigates on click.

Example

RouteLinkLabel(self, "/users/<id>", params={"id": 12}, text="User 12")

---

bind_route

bind_route(widget, path: str, params: dict = None)

Binds navigation logic to any widget with a command option.

Example

bind_route(my_button, "/settings", params={"tab": "advanced"})

---

with_route

@with_route(path, params)
def handler(): ...

Decorator that adds route metadata to a function.

Example

@with_route("/help")
def open_help():
    ...

---

🎥 Transitions

slide_transition

slide_transition(outlet, view_class, params, duration=300)

Animates a slide-in transition from the right.

Example

from tkrouter.transitions import slide_transition
create_router(ROUTES, outlet, transition_handler=slide_transition)

---

simple_fade_transition

simple_fade_transition(outlet, view_class, params, duration=300)

Fades between views using an overlay.

Example

from tkrouter.transitions import simple_fade_transition
ROUTES = {
    "/fade": {
        "view": FadeView,
        "transition": simple_fade_transition
    }
}

---

⚠️ Exceptions

RouteNotFoundError

Raised when no route matches the requested path.

NavigationGuardError

Raised when a guard condition blocks access to a route.