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

• log (default) - Uses the standard log crate for logging
• tracing - Uses the tracing crate for structured logging (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::BoxedGuard;guard

pub use guards::GuardBuilder;guard

pub use guards::GuardContext;guard

pub use guards::GuardResult;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 lifecycle::BoxedLifecycle;

pub use lifecycle::LifecycleResult;

pub use lifecycle::RouteLifecycle;

pub use middleware::middleware_fn;middleware

pub use middleware::BoxedMiddleware;middleware

pub use middleware::RouteMiddleware;middleware

pub use nested::build_child_path;

pub use nested::resolve_child_route;

pub use params::QueryParams;

pub use params::RouteParams;

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::Router;

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;Deprecated

pub use widgets::router_outlet_named;Deprecated

pub use widgets::DefaultPages;

pub use widgets::RouterLink;

pub use widgets::RouterOutlet;

Modules

cachecache

Route resolution caching

error

Error handling for router

guardsguard

Route guards for authentication, authorization, and validation

history

Navigation history management

lifecycle

Route lifecycle hooks

logging

Logging abstraction layer

matcher

Advanced route matching with priority system

middlewaremiddleware

Route middleware trait and types

nested

Nested route resolution

params

Route parameter extraction and query string parsing

route

Route definition and configuration

state

Router state management

transitiontransition

Route transition animations

widgets

RouterOutlet component for rendering nested routes

Macros

debug_log

Debug-level logging

error_log

Error-level logging

guards

Helper macro for creating Guards composition

info_log

Info-level logging

trace_log

Trace-level logging

warn_log

Warn-level logging

Structs

GlobalRouter

Global router state accessible from any component

NavigationRequest

Request for navigation.

Navigator

Navigation API for convenient route navigation

NavigatorHandle

Handle for Navigator.of(context) pattern

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

Get current path from global router

init_router

Initialize global router with routes

navigate

Navigate to a path using global router