Introduction

As your app grows, it can be helpful to organize your app into multiple pages or views you can switch between. In web application, each view has an associated url that can be saved and shared. The Dioxus router helps you manage the URL state of your application. It provides a type safe interface that checks all routes at compile time to prevent runtime errors.

Installing the router

To get started, you can add the router feature to your dioxus dependency in your Cargo.toml:

[dependencies]
dioxus = { version = "0.7", features = ["router"] }

Creating a Routable enum

The core of the router is your Routable enum. You will use this enum throughout your application to navigate to different pages. Each variant of the enum is a single view page in your app handles:

1. Parsing your route from a URL
2. Displaying your route as a URL
3. Rendering your route as a component

To create a Routable enum, you will need to derive the Routable with a #[route(..)] attribute on each variant which describes the format of the route. You must have a component in scope that matches the name of each variant to render the route:

use dioxus::prelude::*;

#[derive(Clone, Debug, PartialEq, Routable)]
enum Route {
    #[route("/")]
    Home,
    #[route("/about")]
    About,
    #[route("/user/:id")]
    User { id: u32 },
}

#[component]
fn Home() -> Element {
    rsx!("Welcome to the home page!")
}

#[component]
fn About() -> Element {
    rsx!("This is the about page.")
}

#[component]
fn User(id: u32) -> Element {
    rsx!("User page for user with id: {id}")
}

Rendering the router

Now that you have defined your routes, you can use the Router component to render them. The Router component takes your Routable enum as a generic argument to define handle parsing, and rendering routes.

fn main() {
    dioxus::launch(|| rsx! { Router::<Route> {} });
}

Linking to your first route

To navigate between routes, you can use the Link component provided by the router. The Link component takes a to prop which can be either a unchecked string route or a variant of your Routable enum:

// ...

#[component]
fn Home() -> Element {
    rsx! {
        div {
            "Welcome to the home page!"
            Link { to: Route::About, "Go to About Page" }
        }
    }
}