Struct Route 

pub struct Route {
    pub config: RouteConfig,
    pub builder: Option<RouteBuilder>,
    pub children: Vec<RouteRef>,
    pub named_children: HashMap<String, Vec<RouteRef>>,
    pub guards: Vec<BoxedGuard>,
    pub middleware: Vec<BoxedMiddleware>,
    pub lifecycle: Option<BoxedLifecycle>,
    pub transition: TransitionConfig,
}

Route definition with render function

Fields

config: RouteConfig

Route configuration

builder: Option<RouteBuilder>

Builder function to create the view for this route

children: Vec<RouteRef>

Child routes with their own builders This is the preferred way to define nested routes (instead of RouteConfig.children)

named_children: HashMap<String, Vec<RouteRef>>

Named outlets - map of outlet name to child routes Allows multiple outlet areas in a single parent route

guards: Vec<BoxedGuard>

Available on crate feature guard only.

Guards that control access to this route

middleware: Vec<BoxedMiddleware>

Available on crate feature middleware only.

Middleware that runs before and after navigation to this route

lifecycle: Option<BoxedLifecycle>

Lifecycle hooks for this route

transition: TransitionConfig

Available on crate feature transition only.

Transition animation for this route

Implementations

impl Route

pub fn new<F, E>(path: impl Into<String>, builder: F) -> Self

where E: IntoElement, F: Fn(&mut Window, &mut App, &RouteParams) -> E + Send + Sync + 'static,

Create a route with a builder function

Routes are registered with a path pattern and a builder function that creates the view. The builder receives the window, app context and extracted route parameters.

Example

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

// Simple static route
Route::new("/home", |window, cx, params| {
    div().child("Home Page")
});

// Route with dynamic parameter
Route::new("/users/:id", |window, cx, params| {
    let id = params.get("id").unwrap();
    div().child(format!("User: {}", id))
});

pub fn view<F>(path: impl Into<String>, view: F) -> Self

where F: Fn() -> AnyElement + Send + Sync + 'static,

Create a stateless route from a simple view function

Use this for simple, stateless pages that don’t need access to route params, window, or context. The view function is called on every render.

Example

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

Route::view("/about", || {
    div().child("About Page").into_any_element()
});

pub fn component<T, F>(path: impl Into<String>, create: F) -> Self

where T: Render + 'static, F: Fn() -> T + Send + Sync + 'static + Clone,

Create a stateful route with an Entity-based component

Use this for pages that maintain internal state across navigation. The component is cached using window.use_keyed_state(), so navigating back to the route will preserve the component’s state.

Example

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

struct CounterPage {
    count: i32,
}

impl CounterPage {
    fn new() -> Self {
        Self { count: 0 }
    }
}

impl Render for CounterPage {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<'_, Self>) -> impl IntoElement {
        div().child(format!("Count: {}", self.count))
    }
}

Route::component("/counter", CounterPage::new);

pub fn component_with_params<T, F>(path: impl Into<String>, create: F) -> Self

where T: Render + 'static, F: Fn(&RouteParams) -> T + Send + Sync + 'static + Clone,

Create a stateful route with parameters

Like component(), but the create function receives route parameters. The component is cached per unique set of parameter values, so navigating to /user/1 and /user/2 will create two separate component instances.

Example

use gpui_navigator::{Route, RouteParams};
use gpui::*;

struct UserPage {
    user_id: String,
}

impl UserPage {
    fn new(user_id: String) -> Self {
        Self { user_id }
    }
}

impl Render for UserPage {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<'_, Self>) -> impl IntoElement {
        div().child(format!("User: {}", self.user_id))
    }
}

Route::component_with_params("/user/:id", |params| {
    let id = params.get("id").unwrap().to_string();
    UserPage::new(id)
});

pub fn children(self, children: Vec<RouteRef>) -> Self

Add child routes to this route

Child routes will be rendered in a RouterOutlet within the parent’s layout.

Example

use gpui_navigator::{Route, render_router_outlet};
use gpui::*;

Route::new("/dashboard", |window, cx, params| {
    div()
        .child("Dashboard Header")
        .child(render_router_outlet(window, cx, None)) // Children render here
})
.children(vec![
    Route::new("overview", |_, _cx, _params| {
        div().child("Overview")
    })
    .into(),
    Route::new("settings", |_, _cx, _params| {
        div().child("Settings")
    })
    .into(),
]);

pub fn child(self, child: RouteRef) -> Self

Add a single child route

Example

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

Route::new("/dashboard", |_, _cx, _params| div())
    .child(Route::new("overview", |_, _cx, _params| div()).into())
    .child(Route::new("settings", |_, _cx, _params| div()).into());

pub fn name(self, name: impl Into<String>) -> Self

Set route name

Named routes can be referenced by name instead of path.

pub fn meta(self, key: impl Into<String>, value: impl Into<String>) -> Self

Add metadata to the route

Metadata can be used for guards, analytics, titles, etc.

Example

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

Route::new("/admin", |_, _cx, _params| div())
    .meta("requiresAuth", "true")
    .meta("requiredRole", "admin")
    .meta("title", "Admin Panel");

pub fn named_outlet( self, name: impl Into<String>, children: Vec<RouteRef>, ) -> Self

Add routes for a named outlet

Named outlets allow you to have multiple content areas in a single parent route. For example, a main content area and a sidebar.

Example

use gpui_navigator::{Route, render_router_outlet};
use gpui::*;

Route::new("/dashboard", |window, cx, _params| {
    div()
        .child(render_router_outlet(window, cx, None))             // Main content
        .child(render_router_outlet(window, cx, Some("sidebar")))  // Sidebar
})
.children(vec![
    Route::new("analytics", |_, _cx, _params| div()).into(),
])
.named_outlet("sidebar", vec![
    Route::new("stats", |_, _cx, _params| div()).into(),
]);

pub fn guard<G>(self, guard: G) -> Self

where G: RouteGuard<Future = Pin<Box<dyn Future<Output = GuardResult> + Send>>>,

Available on crate feature guard only.

Add a guard to this route

Guards control access to routes. If any guard denies access, navigation is blocked.

Example

use gpui_navigator::{Route, AuthGuard, RoleGuard};
use gpui::*;

fn is_authenticated(_cx: &App) -> bool { true }
fn get_role(_cx: &App) -> Option<String> { Some("user".into()) }

Route::new("/dashboard", |_, _cx, _params| div())
    .guard(AuthGuard::new(is_authenticated, "/login"))
    .guard(RoleGuard::new(get_role, "user", Some("/forbidden")));

pub fn guards(self, guards: Vec<BoxedGuard>) -> Self

Available on crate feature guard only.

Add multiple guards at once

Example

use gpui_navigator::{Route, BoxedGuard};
use gpui::*;

Route::new("/admin", |_, _cx, _params| div())
    .guards(vec![
        // Add boxed guards here
    ]);

pub fn middleware<M>(self, middleware: M) -> Self

where M: RouteMiddleware<Future = Pin<Box<dyn Future<Output = ()> + Send>>>,

Available on crate feature middleware only.

Add middleware to this route

Middleware runs before and after navigation.

Example

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

// Route::new("/dashboard", |_, _cx, _params| div().into_any_element())
//     .middleware(LoggingMiddleware::new());

pub fn middlewares(self, middleware: Vec<BoxedMiddleware>) -> Self

Available on crate feature middleware only.

Add multiple middleware at once

Example

use gpui_navigator::{Route, BoxedMiddleware};
use gpui::*;

Route::new("/dashboard", |_, _cx, _params| div().into_any_element())
    .middlewares(vec![
        // Add boxed middleware here
    ]);

pub fn lifecycle<L>(self, lifecycle: L) -> Self

where L: RouteLifecycle<Future = Pin<Box<dyn Future<Output = LifecycleResult> + Send>>>,

Add lifecycle hooks to this route

Lifecycle hooks allow you to run code when entering/exiting routes.

Example

use gpui_navigator::{Route, RouteLifecycle, LifecycleResult, NavigationRequest};
use gpui::*;
use std::pin::Pin;
use std::future::Future;

// Lifecycle hooks allow running code when entering/exiting routes
// Implement RouteLifecycle trait for custom behavior

pub fn transition(self, transition: Transition) -> Self

Available on crate feature transition only.

Set the transition animation for this route

Example

use gpui_navigator::{Route, Transition};
use gpui::*;

Route::new("/page", |_, _cx, _params| div().into_any_element())
    .transition(Transition::fade(200));

pub fn get_named_children(&self, name: &str) -> Option<&[RouteRef]>

Get child routes for a named outlet

Returns None if the outlet doesn’t exist

pub fn has_named_outlet(&self, name: &str) -> bool

Check if this route has a named outlet

pub fn named_outlet_names(&self) -> Vec<&str>

Get all named outlet names

pub fn matches(&self, path: &str) -> Option<RouteMatch>

Match a path against this route

pub fn build( &self, window: &mut Window, cx: &mut App, params: &RouteParams, ) -> Option<AnyElement>

Build the view for this route

pub fn find_child(&self, segment: &str) -> Option<&RouteRef>

Find a child route by path segment

Used internally by RouterOutlet to resolve child routes.

pub fn get_children(&self) -> &[RouteRef]

Get all child routes

Trait Implementations

impl Debug for Route

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.