Leptos Router

Leptos Router is a router and state management tool for web applications written in Rust using the Leptos web framework. It is ”isomorphic,” i.e., it can be used for client-side applications/single-page apps (SPAs), server-side rendering/multi-page apps (MPAs), or to synchronize state between the two.

Philosophy

Leptos Router is built on a few simple principles:

1. URL drives state. For web applications, the URL should be the ultimate source of truth for most of your app’s state. (It’s called a Universal Resource Locator for a reason!)

2. Nested routing. A URL can match multiple routes that exist in a nested tree and are rendered by different components. This means you can navigate between siblings in this tree without re-rendering or triggering any change in the parent routes.

3. Progressive enhancement. The [A] and [Form] components resolve any relative nested routes, render actual <a> and <form> elements, and (when possible) upgrading them to handle those navigations with client-side routing. If you’re using them with server-side rendering (with or without hydration), they just work, whether JS/WASM have loaded or not.

Example

use leptos::*;
use leptos_router::*;

#[component]
pub fn RouterExample(cx: Scope) -> impl IntoView {
  view! {
    cx,
    <div id="root">
      // we wrap the whole app in a <Router/> to allow client-side navigation
      // from our nav links below
      <Router>
        // <nav> and <main> will show on every route
        <nav>
          // LR will enhance the active <a> link with the [aria-current] attribute
          // we can use this for styling them with CSS like `[aria-current] { font-weight: bold; }`
          <A href="contacts">"Contacts"</A>
          // But we can also use a normal class attribute like it is a normal component
          <A href="settings" class="my-class">"Settings"</A>
          // It also supports signals!
          <A href="about" class=move || "my-class">"About"</A>
        </nav>
        <main>
          // <Routes/> both defines our routes and shows them on the page
          <Routes>
            // our root route: the contact list is always shown
            <Route
              path=""
              view=move |cx| view! { cx,  <ContactList/> }
            >
              // users like /gbj or /bob
              <Route
                path=":id"
                view=move |cx| view! { cx,  <Contact/> }
              />
              // a fallback if the /:id segment is missing from the URL
              <Route
                path=""
                view=move |_| view! { cx,  <p class="contact">"Select a contact."</p> }
              />
            </Route>
            // LR will automatically use this for /about, not the /:id match above
            <Route
              path="about"
              view=move |cx| view! { cx,  <About/> }
            />
          </Routes>
        </main>
      </Router>
    </div>
  }
}

type ContactSummary = (); // TODO!
type Contact = (); // TODO!()

// contact_data reruns whenever the :id param changes
async fn contact_data(id: String) -> Contact {
  todo!()
}

// contact_list_data *doesn't* rerun when the :id changes,
// because that param is nested lower than the <ContactList/> route
async fn contact_list_data() -> Vec<ContactSummary> {
  todo!()
}

#[component]
fn ContactList(cx: Scope) -> impl IntoView {
  // loads the contact list data once; doesn't reload when nested routes change
  let contacts = create_resource(cx, || (), |_| contact_list_data());
  view! {
    cx,
    <div>
      // show the contacts
      <ul>
        {move || contacts.read(cx).map(|contacts| view! { cx, <li>"todo contact info"</li> } )}
      </ul>

      // insert the nested child route here
      <Outlet/>
    </div>
  }
}

#[component]
fn Contact(cx: Scope) -> impl IntoView {
  let params = use_params_map(cx);
  let data = create_resource(
    cx,
    move || params.with(|p| p.get("id").cloned().unwrap_or_default()),
    move |id| contact_data(id)
  );
  todo!()
}

#[component]
fn About(cx: Scope) -> impl IntoView {
  todo!()
}

Module Route Definitions

Routes can also be modularized and nested by defining them in separate components, which can be located in and imported from other modules. Components that return <Route/> should be marked #[component(transparent)], as in this example:

use leptos::*;
use leptos_router::*;

#[component]
pub fn App(cx: Scope) -> impl IntoView {
  view! { cx,
    <Router>
      <Routes>
        <Route path="/" view=move |cx| {
          view! { cx, "-> /" }
        }/>
        <ExternallyDefinedRoute/>
      </Routes>
    </Router>
  }
}

// `transparent` here marks the component as returning data (a RouteDefinition), not a view
#[component(transparent)]
pub fn ExternallyDefinedRoute(cx: Scope) -> impl IntoView {
  view! { cx,
    <Route path="/some-area" view=move |cx| {
      view! { cx, <div>
        <h2>"Some Area"</h2>
        <Outlet/>
      </div> }
    }>
      <Route path="/path-a/:id" view=move |cx| {
        view! { cx, <p>"Path A"</p> }
      }/>
      <Route path="/path-b/:id" view=move |cx| {
        view! { cx, <p>"Path B"</p> }
      }/>
    </Route>
  }
}

Feature Flags

• csr Client-side rendering: Generate DOM nodes in the browser
• ssr Server-side rendering: Generate an HTML string (typically on the server)
• hydrate Hydration: use this to add interactivity to an SSRed Leptos app
• stable By default, Leptos requires nightly Rust, which is what allows the ergonomics of calling signals as functions. Enable this feature to support stable Rust.

Important Note: You must enable one of csr, hydrate, or ssr to tell Leptos which mode your app is operating in.