rooter
A small, window-scoped router for GPUI.
Each window owns its own router and navigation state. Routes are configured once,
and NavLink automatically uses the router attached to its window.
Example
use *;
use ;
use ;
See examples/simple.rs for a complete application and
examples/multi_file/ for an application with one file per page.
examples/nested.rs demonstrates recursive groups, group index routes,
dynamic segments, and scoped catch-alls.
examples/layouts.rs demonstrates nested layouts, Outlet, and stateful chrome.
examples/prefetch.rs demonstrates route loaders, a 2s artificial delay, and hover prefetch.
Compatibility
This crate tracks gpui 0.2.x. GPUI is still evolving; a GPUI breaking release may require a breaking rooter release.
Minimum supported Rust: 1.88 (see rust-version in Cargo.toml).
Versioning
rooter stays on 0.x until both this API and GPUI settle. During 0.x:
- Breaking public API changes bump the minor version (0.1 → 0.2).
- Compatible fixes and additions bump the patch version.
matchit and regex are implementation details and are not re-exported.
See CHANGELOG.md for released changes.
Navigation behavior
navigate and replace no-op (no history change, no NavigationEvent) when
the path normalizes to the current location. back and forward no-op at the
ends of the stack. Router::url returns UrlError for an unknown name or a
missing path parameter; extra parameters become query string entries.
navigate_window / replace_window / back_window / forward_window return
false only when the window has no attached router. They return true even
when the underlying method no-ops.
Layouts and stateful chrome
.layout() wraps every route in the current group. Put Outlet where the child
route should render. Nested groups stack layouts from the inside out.
Layout and page factories run again every time the router renders. They should
return elements, not create long-lived state. If chrome needs to remember
anything across navigations (a collapsed sidebar, a filter, scroll position),
create a GPUI Entity once on the window root and clone it into the layout:
The layout still rebuilds each frame. The Sidebar entity does not, so its
fields survive leaving /dashboard and coming back. Creating that entity
inside the layout factory would reset it on every render.
Route data
.loader() starts an async task for the previous route. The page receives a
Resource (is_loading, has_error, get, error). Navigation does not wait
for the loader. Hover or first paint on NavLink, or Router::prefetch_window,
run the same task so a later visit can reuse it. Cached results expire after
30 seconds by default (DEFAULT_CACHE_FOR). Set the TTL on the link or prefetch
call, not on the route.
new
.route
.loader;
to
.prefetch
.child;
to
.prefetch
.child;
prefetch_window;
prefetch_window;
invalidate_window;
invalidate_window;
invalidate_window;
invalidate_window;
Keep load next to page in the same module. The loader must return
Result<T, E> where both types are Send + Sync.
See examples/prefetch.rs for a complete window with a 2 second delay.
Development
Run the tests:
Check formatting:
Run the linter:
License
Licensed under the MIT License. See LICENSE.