Crate leptos_router

Source
Expand description

§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::prelude::*;
use leptos_router::components::*;
use leptos_router::path;
use leptos_router::hooks::use_params_map;

#[component]
pub fn RouterExample() -> impl IntoView {
  view! {

    <div id="root">
      // we wrap the whole app in a <Router/> to allow client-side navigation
      // from our nav links below
      <Router>
        <main>
          // <Routes/> both defines our routes and shows them on the page
          <Routes fallback=|| "Not found.">
            // our root route: the contact list is always shown
            <ParentRoute
              path=path!("")
              view=ContactList
            >
              // users like /gbj or /bob
              <Route
                path=path!(":id")
                view=Contact
              />
              // a fallback if the /:id segment is missing from the URL
              <Route
                path=path!("")
                view=move || view! { <p class="contact">"Select a contact."</p> }
              />
            </ParentRoute>
          </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() -> impl IntoView {
  // loads the contact list data once; doesn't reload when nested routes change
  let contacts = Resource::new(|| (), |_| contact_list_data());
  view! {

    <div>
      // show the contacts
      <ul>
        {move || contacts.get().map(|contacts| view! { <li>"todo contact info"</li> } )}
      </ul>

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

#[component]
fn Contact() -> impl IntoView {
  let params = use_params_map();
  let data = Resource::new(
    move || params.read().get("id").unwrap_or_default(),
    move |id| contact_data(id)
  );
  todo!()
}

You can find examples of additional APIs in the router example.

§Feature Flags

  • ssr Server-side rendering: Generate an HTML string (typically on the server)
  • nightly: On nightly Rust, enables the function-call syntax for signal getters and setters.
  • tracing: Enables support for the tracing crate.

Modules§

  • components
    Components for route definition and for enhanced links and forms.
  • flat_router
    An optimized “flat” router without nested routes.
  • hooks
    Hooks that can be used to access router state inside your components.
  • location
    Utilities for accessing the current location.
  • nested_router
    A nested router that supports multiple levels of route definitions.
  • params
    Support for maps of parameters in the path or in the query.
  • static_routes
    Support for static routing.

Macros§

  • path
    Constructs a path for use in a [leptos_router::Route] definition.

Structs§

Enums§

  • Method
    Represents an HTTP method that can be handled by this route.
  • PathSegment
  • SsrMode
    Indicates which rendering mode should be used for this route during server-side rendering.

Traits§