Crate gpui_navigator 

GPUI Router

A declarative routing library for GPUI with support for:

• Route Transitions - Fade, slide, scale animations with configurable duration
• Nested Routing - Parent/child route hierarchies with RouterOutlet
• Route Guards - Authentication, authorization, and custom access control
• Middleware - Before/after hooks for navigation events
• Named Routes - Navigate using route names instead of paths
• Route Matching - Pattern matching with parameters and constraints
• Error Handling - Custom 404 and error handlers

Quick Start

use gpui::*;
use gpui_navigator::*;

fn main() {
    Application::new().run(|cx| {
        init_router(cx, |router| {
            router.add_route(
                Route::new("/", home_page)
                    .transition(Transition::fade(300))
            );
        });

        cx.open_window(WindowOptions::default(), |_, cx| {
            cx.new(|_| AppView)
        })
    });
}

fn home_page(_cx: &mut App, _params: &RouteParams) -> AnyElement {
    gpui::div().into_any_element()
}

struct AppView;

impl Render for AppView {
    fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
        gpui::div()
    }
}

Navigation

The library provides a simple navigation API:

use gpui_navigator::Navigator;

// Push new route
Navigator::push(cx, "/profile");

// Replace current route
Navigator::replace(cx, "/login");

// Go back (pop)
Navigator::pop(cx);

// Go forward
Navigator::forward(cx);

Route Guards

Protect routes with authentication and authorization:

use gpui_navigator::*;

Route::new("/admin", admin_page)
    .guard(AuthGuard::new(is_logged_in, "/login"))
    .guard(RoleGuard::new(get_user_role, "admin", Some("/forbidden")))

Nested Routes

Create hierarchical route structures:

use gpui_navigator::*;

Route::new("/dashboard", dashboard_layout)
    .children(vec![
        Route::new("overview", overview_page).into(),
        Route::new("settings", settings_page).into(),
    ])

Feature Flags

Feature	Default	Description
guard	yes	Route guards (AuthGuard, RoleGuard, PermissionGuard)
middleware	yes	Before/after navigation hooks
transition	yes	Fade, slide animations on route change
cache	yes	LRU cache for route resolution (depends on lru)
log	yes	Logging via the log crate
tracing	no	Logging via tracing (mutually exclusive with log)

Re-exports

pub use cache::CacheStats;cache

pub use cache::RouteCache;cache

pub use cache::RouteId;cache

pub use error::ErrorHandler;

pub use error::ErrorHandlers;

pub use error::NavigationError;

pub use error::NavigationResult;

pub use error::NotFoundHandler;

pub use guards::guard_fn;guard

pub use guards::AuthGuard;guard

pub use guards::GuardBuilder;guard

pub use guards::Guards;guard

pub use guards::NotGuard;guard

pub use guards::PermissionGuard;guard

pub use guards::RoleGuard;guard

pub use guards::RouteGuard;guard

pub use history::History;

pub use history::HistoryEntry;

pub use history::HistoryState;

pub use lifecycle::NavigationAction;

pub use lifecycle::RouteLifecycle;

pub use middleware::middleware_fn;middleware

pub use middleware::RouteMiddleware;middleware

pub use nested::build_child_path;

pub use nested::extract_param_name;

pub use nested::normalize_path;

pub use nested::resolve_child_route;

pub use params::QueryParams;

pub use params::RouteParams;

pub use resolve::resolve_match_stack;

pub use resolve::MatchEntry;

pub use resolve::MatchStack;

pub use route::validate_route_path;

pub use route::BuilderFn;

pub use route::IntoRoute;

pub use route::NamedRoute;

pub use route::NamedRouteRegistry;

pub use route::PageRoute;

pub use route::Route;

pub use route::RouteConfig;

pub use route::RouteDescriptor;

pub use state::RouterState;

pub use transition::SlideDirection;transition

pub use transition::Transition;transition

pub use transition::TransitionConfig;transition

pub use widgets::render_router_outlet;

pub use widgets::router_link;

pub use widgets::router_outlet;

pub use widgets::router_outlet_named;

pub use widgets::router_view;

pub use widgets::DefaultPages;

pub use widgets::RouterLink;

pub use widgets::RouterOutlet;

pub use widgets::RouterView;

Modules

cachecache

Route resolution caching.

error

Error handling for the router.

guardsguard

Route guards for authentication, authorization, and validation.

history

Navigation history management.

lifecycle

Route lifecycle hooks and navigation action types.

logging

Logging abstraction layer.

middlewaremiddleware

Route middleware for cross-cutting navigation concerns.

nested

Nested route resolution

params

Route parameter extraction and query string parsing.

resolve

Route resolution via Match Stack

route

Route definition and configuration.

state

Router state management.

transitiontransition

Route transition animations.

widgets

Router widgets for rendering routes.

Macros

debug_log

Emit a debug-level log message.

error_log

Emit an error-level log message.

info_log

Emit an info-level log message.

trace_log

Emit a trace-level log message.

warn_log

Emit a warn-level log message.

Structs

GlobalRouter

Global router state accessible from any component.

NavigationRequest

Request for navigation.

Navigator

Navigation API for convenient route navigation.

NavigatorHandle

Handle returned by Navigator::of for fluent chained navigation.

RouteChangeEvent

Event emitted when the route changes.

RouteMatch

Route path matching result.

Enums

NavigationDirection

Navigation direction indicator.

Traits

UseRouter

Trait for accessing the global router from context.

Functions

current_path

Return the current path from the global router.

init_router

Initialize global router with routes.

navigate

Navigate to a path using the global router and refresh all windows.