Struct ClientRouter 

pub struct ClientRouter { /* private fields */ }

Available on crate feature client-router only.

The main client-side router.

ClientRouter renders views using the Page type.

Clone semantics

The Clone impl is shallow by design. Signal fields share their underlying reactive state across clones, and on WASM the navigation observer state (held behind Rc) is shared as well; only the route table (Vec<ClientRoute> / HashMap<String, usize>) is copied independently. As a result two clones see the same navigation state but can diverge if either is mutated to register new routes — this is not a deep clone of the router.

In practice Clone is only invoked by collect_client_router_from_inventory (Refs #4453) as the fallback path for Arc::try_unwrap when the underlying factory Arc is shared, and ClientLauncher::register_routes_from_inventory() is the only caller. Application code should NOT call .clone() directly to “branch” routers; treat the router as a single owned value moved into the launcher. Refs Copilot review on PR #4477.

Implementations

impl ClientRouter

pub fn new() -> ClientRouter

Available on crate feature test and native only.

Creates a new router.

pub fn merge(self, other: ClientRouter) -> ClientRouter

Available on crate feature test and native only.

Combine another ClientRouter into this one.

Routes and named-route mappings from other are appended to self, preserving the order in which routes were originally registered. The reactive signals (current_path, current_params, current_route_name) and the not_found handler from other are discarded — self’s observation state is the one that drives the merged router.

Named-route collisions

If both routers register the same named route, the entry from other overwrites the entry from self (last-wins). This matches the way UnifiedRouter::mount_unified already composes per-app routers, and keeps merge callable in chains where the caller does not want to handle errors. Use ClientRouter::try_merge for a fallible variant that surfaces collisions instead of silently shadowing them.

Examples

Composing per-app SPA routers produced by #[url_patterns(InstalledApp::<app>, mode = client)] into the single ClientRouter that ClientLauncher::router_client expects:

let router = polls_client_url_patterns()
    .merge(users_client_url_patterns());

pub fn try_merge(self, other: ClientRouter) -> Result<ClientRouter, MergeError>

Available on crate feature test and native only.

Like ClientRouter::merge, but fail if any named route collides.

Validates first, so on Err self is dropped without being mutated. On success the semantics are identical to merge (routes appended, other’s signals and not_found discarded).

Errors

Returns MergeError::NameCollision carrying a colliding name when at least one named route is registered in both routers. When several names collide, the returned name is one of them; the choice is unspecified because named routes are stored in a HashMap.

Examples

match polls_client_url_patterns().try_merge(users_client_url_patterns()) {
    Ok(router) => launcher.router_client(|| router),
    Err(MergeError::NameCollision { name }) => {
        panic!("two apps register the route `{name}`");
    }
}

pub fn with_namespace(self, namespace: &str) -> ClientRouter

Available on crate feature test and native only.

Prefix all named route keys with "namespace:".

This is the client-side equivalent of ServerRouter::with_namespace(). Called by #[url_patterns(InstalledApp::<variant>, mode = client)] (or mode = unified) to ensure registered names match the "app:route" format used by per-app resolver structs.

pub fn route<F>(self, pattern: &str, component: F) -> ClientRouter

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

Available on crate feature test and native only.

Adds a route to the router.

pub fn named_route<F>( self, name: &str, pattern: &str, component: F, ) -> ClientRouter

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

Available on crate feature test and native only.

Adds a named route to the router.

pub fn route_params<F, T>(self, pattern: &str, handler: F) -> ClientRouter

where F: Fn(Path<T>) -> Page + Send + Sync + 'static, T: FromPath + Send + Sync + 'static,

Available on crate feature test and native only.

Adds a route with typed path parameters.

pub fn named_route_params<F, T>( self, name: &str, pattern: &str, handler: F, ) -> ClientRouter

where F: Fn(Path<T>) -> Page + Send + Sync + 'static, T: FromPath + Send + Sync + 'static,

Available on crate feature test and native only.

Adds a named route with typed path parameters.

pub fn route_result<F, T, E>(self, pattern: &str, handler: F) -> ClientRouter

where F: Fn(Path<T>) -> Result<Page, E> + Send + Sync + 'static, T: FromPath + Send + Sync + 'static, E: Into<RouterError> + Send + Sync + 'static,

Available on crate feature test and native only.

Adds a route with typed path parameters that returns a Result.

pub fn named_route_result<F, T, E>( self, name: &str, pattern: &str, handler: F, ) -> ClientRouter

where F: Fn(Path<T>) -> Result<Page, E> + Send + Sync + 'static, T: FromPath + Send + Sync + 'static, E: Into<RouterError> + Send + Sync + 'static,

Available on crate feature test and native only.

Adds a named route with typed path parameters that returns a Result.

pub fn guarded_route<F, G>( self, pattern: &str, component: F, guard: G, ) -> ClientRouter

where F: Fn() -> Page + Send + Sync + 'static, G: Fn(&ClientRouteMatch) -> bool + Send + Sync + 'static,

Available on crate feature test and native only.

Adds a route with a guard.

pub fn route_path<F, T>(self, pattern: &str, handler: F) -> ClientRouter

where F: Fn(Path<T>) -> Page + Send + Sync + 'static, T: SingleFromPath + Send + Sync + 'static,

Available on crate feature test and native only.

Adds a route with a single path parameter using Path<T> extractor.

Example

let router = ClientRouter::new()
    .route_path("/users/{id}/", |Path(id): Path<i64>| {
        user_detail(id)
    });

pub fn named_route_path<F, T>( self, name: &str, pattern: &str, handler: F, ) -> ClientRouter

where F: Fn(Path<T>) -> Page + Send + Sync + 'static, T: SingleFromPath + Send + Sync + 'static,

Available on crate feature test and native only.

Adds a named route with a single path parameter using Path<T> extractor.

pub fn route_path2<F, T1, T2>(self, pattern: &str, handler: F) -> ClientRouter

where F: Fn(Path<T1>, Path<T2>) -> Page + Send + Sync + 'static, T1: SingleFromPath + Send + Sync + 'static, T2: SingleFromPath + Send + Sync + 'static,

Available on crate feature test and native only.

Adds a route with two path parameters using multiple Path<T> extractors.

Example

let router = ClientRouter::new()
    .route_path2("/users/{user_id}/posts/{post_id}/",
        |Path(user_id): Path<i64>, Path(post_id): Path<i64>| {
            user_post_detail(user_id, post_id)
        });

pub fn named_route_path2<F, T1, T2>( self, name: &str, pattern: &str, handler: F, ) -> ClientRouter

where F: Fn(Path<T1>, Path<T2>) -> Page + Send + Sync + 'static, T1: SingleFromPath + Send + Sync + 'static, T2: SingleFromPath + Send + Sync + 'static,

Available on crate feature test and native only.

Adds a named route with two path parameters.

pub fn route_path3<F, T1, T2, T3>( self, pattern: &str, handler: F, ) -> ClientRouter

where F: Fn(Path<T1>, Path<T2>, Path<T3>) -> Page + Send + Sync + 'static, T1: SingleFromPath + Send + Sync + 'static, T2: SingleFromPath + Send + Sync + 'static, T3: SingleFromPath + Send + Sync + 'static,

Available on crate feature test and native only.

Adds a route with three path parameters using multiple Path<T> extractors.

Example

let router = ClientRouter::new()
    .route_path3("/org/{org}/repos/{repo}/issues/{issue}/",
        |Path(org): Path<String>, Path(repo): Path<String>, Path(issue): Path<i32>| {
            issue_detail(org, repo, issue)
        });

pub fn named_route_path3<F, T1, T2, T3>( self, name: &str, pattern: &str, handler: F, ) -> ClientRouter

where F: Fn(Path<T1>, Path<T2>, Path<T3>) -> Page + Send + Sync + 'static, T1: SingleFromPath + Send + Sync + 'static, T2: SingleFromPath + Send + Sync + 'static, T3: SingleFromPath + Send + Sync + 'static,

Available on crate feature test and native only.

Adds a named route with three path parameters.

pub fn not_found<F>(self, component: F) -> ClientRouter

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

Available on crate feature test and native only.

Sets the not found handler.

pub fn current_path(&self) -> &Signal<String>

Available on crate feature test and native only.

Returns the current path signal.

pub fn current_params(&self) -> &Signal<HashMap<String, String>>

Available on crate feature test and native only.

Returns the current params signal.

pub fn current_route_name(&self) -> &Signal<Option<String>>

Available on crate feature test and native only.

Returns the current route name signal.

pub fn route_patterns(&self) -> impl Iterator<Item = (&str, Option<&str>)>

Available on crate feature test and native only.

Returns an iterator over registered route patterns and their optional names.

Each item is (pattern_str, name) where name is Some for named routes. Intended for diagnostic output (e.g., the runserver startup banner).

pub fn match_path(&self, path: &str) -> Option<ClientRouteMatch>

Available on crate feature test and native only.

Matches a path against registered routes.

pub fn push(&self, path: &str) -> Result<(), RouterError>

Available on crate feature test and native only.

Navigates to a path using pushState.

pub fn replace(&self, path: &str) -> Result<(), RouterError>

Available on crate feature test and native only.

Navigates to a path using replaceState.

pub fn on_navigate<F>(&self, listener: F) -> NavigationSubscription

where F: Fn(&str, &HashMap<String, String>) + 'static,

Available on crate feature test and native only.

Register a listener for navigation events.

Returns a NavigationSubscription handle. Drop the handle to deregister the listener. The router itself only retains a Weak reference, so dropping the subscription frees the listener closure immediately. The stale Weak entry in navigation_observers is pruned lazily on the next notify_observers call (the listener itself is already gone by then).

Robust against nested reactive nodes spawned during view rendering because this subscription is independent of the reactive Effect / Signal auto-tracking system.

Mirrors pages::Router::on_navigate. (Refs #4234)

On native targets (Fixes #4258) this is effectively a no-op: the returned NavigationSubscription is unbound to any observer storage because reactive observation only fires from the wasm popstate listener. The method is still callable on native so that the SpaRouter trait impl in reinhardt-pages (which dispatches into on_navigate from cross-target launcher code) keeps compiling.

pub fn reverse( &self, name: &str, params: &[(&str, &str)], ) -> Result<String, RouterError>

Available on crate feature test and native only.

Generates a URL by route name with parameters.

pub fn render_current(&self) -> Page

Available on crate feature test and native only.

Renders the current route’s component.

Returns the registered not_found page when no route matches, or a default 404 page if no not_found handler has been set.

pub fn route_count(&self) -> usize

Available on crate feature test and native only.

Returns the number of registered routes.

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

Available on crate feature test and native only.

Checks if a route name exists.

pub fn to_reverser(&self) -> ClientUrlReverser

Available on crate feature test and native only.

Extract a lightweight, thread-safe URL reverser.

The returned ClientUrlReverser contains only the named-route-to-pattern mapping and can be shared across threads (unlike ClientRouter itself which holds reactive signals).

pub fn setup_history_listener(&self)

Available on crate feature test and native only.

Non-WASM version of setup_history_listener.

Trait Implementations

impl Clone for ClientRouter

fn clone(&self) -> ClientRouter

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ClientRouter

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

Formats the value using the given formatter.

impl Default for ClientRouter

fn default() -> ClientRouter

Returns the “default value” for a type.