Struct GlobalRouter 

pub struct GlobalRouter { /* private fields */ }

Global router state accessible from any component.

This is the central routing object stored as a GPUI global. It holds the navigation state, route registry, and orchestrates the navigation pipeline (guards -> middleware -> navigation -> middleware).

Implementations

impl GlobalRouter

pub fn new() -> Self

Create a new global router with empty state and no registered routes.

pub const fn match_stack(&self) -> &MatchStack

Get the pre-resolved match stack for the current path.

Outlets call this during render to find their route by depth index. The stack is built once per navigation, so this is O(1).

pub const fn previous_stack(&self) -> Option<&MatchStack>

Available on crate feature transition only.

Get the previous match stack (for transition animations).

pub fn add_route(&mut self, route: Route)

Register a route and re-resolve the match stack.

If the route has a name, it is also registered in the NamedRouteRegistry for URL generation via url_for.

pub fn push(&mut self, path: String, cx: &App) -> NavigationResult

Navigate to a path, running the full guard/middleware pipeline.

Pipeline:

1. Collect guards from matched route (+ ancestors)
2. Check guards — if any denies/redirects, navigation is blocked
3. Run before_navigation middleware
4. Perform actual navigation
5. Run after_navigation middleware

pub fn replace(&mut self, path: String, cx: &App) -> NavigationResult

Replace current path, running the full guard/middleware pipeline.

pub fn back(&mut self, cx: &App) -> Option<NavigationResult>

Go back in history, checking guards on the target route.

pub fn forward(&mut self, cx: &App) -> Option<NavigationResult>

Go forward in history, checking guards on the target route.

pub fn push_with_state( &mut self, path: String, state: HistoryState, cx: &App, ) -> NavigationResult

Push a new path with associated HistoryState data, running the full pipeline.

Allows attaching arbitrary key-value state (scroll position, form data, etc.) to the history entry. The pipeline (guards, middleware) runs first; state is only attached if navigation succeeds.

pub fn replace_with_state( &mut self, path: String, state: HistoryState, cx: &App, ) -> NavigationResult

Replace current path with associated HistoryState data, running the full pipeline.

pub fn current_entry(&self) -> &HistoryEntry

Return the current HistoryEntry (path + optional state data).

pub fn push_named( &mut self, name: &str, params: &RouteParams, cx: &App, ) -> Option<NavigationResult>

Navigate to a named route, resolving the URL from params.

Returns None if the name is not registered.

pub fn url_for(&self, name: &str, params: &RouteParams) -> Option<String>

Generate a URL for a named route by substituting params into its pattern.

Returns None if the name is not registered.

pub fn current_path(&self) -> &str

Return the current navigation path.

pub fn current_match(&mut self) -> Option<RouteMatch>

Get current route match (with caching, requires mutable).

pub fn current_match_immutable(&self) -> Option<RouteMatch>

Get current route match (immutable, no caching).

pub fn current_route(&self) -> Option<&Arc<Route>>

Get the current matched Route.

pub const fn can_go_back(&self) -> bool

Check if can go back.

pub fn can_go_forward(&self) -> bool

Check if can go forward.

pub fn state_mut(&mut self) -> &mut RouterState

Get mutable state reference.

pub const fn state(&self) -> &RouterState

Get state reference.

pub fn nested_cache_mut(&mut self) -> &mut RouteCache

Available on crate feature cache only.

Get nested route cache (mutable).

pub const fn cache_stats(&self) -> &CacheStats

Available on crate feature cache only.

Get nested route cache statistics.

pub fn set_error_handlers(&mut self, handlers: ErrorHandlers)

Set custom error handlers for 404 and navigation errors.

pub const fn error_handlers(&self) -> &ErrorHandlers

Get a reference to the current error handlers.

pub fn get_cached_component(&self, key: &str) -> Option<&AnyView>

Get a cached component view by key.

pub fn cache_component(&mut self, key: String, view: AnyView)

Store a component view in the cache, evicting the oldest entry if full.

pub fn set_next_transition(&mut self, transition: Transition)

Available on crate feature transition only.

Set transition for the next navigation.

pub fn take_next_transition(&mut self) -> Option<Transition>

Available on crate feature transition only.

Get and consume the next transition override.

pub const fn has_next_transition(&self) -> bool

Available on crate feature transition only.

Check if there’s a transition override set.

pub fn clear_next_transition(&mut self)

Available on crate feature transition only.

Clear transition override.

pub fn push_with_transition( &mut self, path: String, transition: Transition, cx: &App, ) -> NavigationResult

Available on crate feature transition only.

Navigate with a specific transition.

pub fn replace_with_transition( &mut self, path: String, transition: Transition, cx: &App, ) -> NavigationResult

Available on crate feature transition only.

Replace with a specific transition.

Trait Implementations

impl Clone for GlobalRouter

fn clone(&self) -> GlobalRouter

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for GlobalRouter

fn default() -> Self

Returns the “default value” for a type.

impl Global for GlobalRouter