Crate leptos_router

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() -> 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>
        // <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=ContactList
            >
              // users like /gbj or /bob
              <Route
                path=":id"
                view=Contact
              />
              // a fallback if the /:id segment is missing from the URL
              <Route
                path=""
                view=move || view! { <p class="contact">"Select a contact."</p> }
              />
            </Route>
            // LR will automatically use this for /about, not the /:id match above
            <Route
              path="about"
              view=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() -> impl IntoView {
  // loads the contact list data once; doesn't reload when nested routes change
  let contacts = create_resource(|| (), |_| contact_list_data());
  view! {

    <div>
      // show the contacts
      <ul>
        {move || contacts.read().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 = create_resource(

    move || params.with(|p| p.get("id").cloned().unwrap_or_default()),
    move |id| contact_data(id)
  );
  todo!()
}

#[component]
fn About() -> 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() -> impl IntoView {
  view! {
    <Router>
      <Routes>
        <Route path="/" view=move || {
          view! { "-> /" }
        }/>
        <ExternallyDefinedRoute/>
      </Routes>
    </Router>
  }
}

// `transparent` here marks the component as returning data (a RouteDefinition), not a view
#[component(transparent)]
pub fn ExternallyDefinedRoute() -> impl IntoView {
  view! {
    <Route path="/some-area" view=move || {
      view! { <div>
        <h2>"Some Area"</h2>
        <Outlet/>
      </div> }
    }>
      <Route path="/path-a/:id" view=move || {
        view! { <p>"Path A"</p> }
      }/>
      <Route path="/path-b/:id" view=move || {
        view! { <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
• nightly: On nightly Rust, enables the function-call syntax for signal getters and setters.

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

Re-exports

• pub use matching::*;

Macros

• params_map
  Create a ParamsMap in a declarative style.

Structs

• AProps
  Props for the A component.
• ActionFormProps
  Props for the ActionForm component.
• AnimatedOutletProps
  Props for the AnimatedOutlet component.
• AnimatedRoutesProps
  Props for the AnimatedRoutes component.
• BrowserIntegration
  The default integration when you are running in the browser, which uses the History API.
• FormProps
  Props for the Form component.
• Loader
• Location
  A reactive description of the current URL, containing equivalents to the local parts of the browser’s Location.
• LocationChange
  A description of a navigation.
• MultiActionFormProps
  Props for the MultiActionForm component.
• NavigateOptions
  Options that can be used to configure a navigation. Used with use_navigate.
• OutletProps
  Props for the Outlet component.
• ParamsMap
  A key-value map of the current named route params and their values.
• PossibleBranchContext
  Context to contain all possible routes.
• ProtectedRouteProps
  Props for the ProtectedRoute component.
• RedirectProps
  Props for the Redirect component.
• RouteContext
  Context type that contains information about the current, matched route.
• RouteData
• RouteDefinition
  Defines a single route in a nested route tree. This is the return type of the <Route/> component, but can also be used to build your own configuration-based or filesystem-based routing.
• RouteListing
  A route that this application can serve.
• RouteProps
  Props for the Route component.
• RouterContext
  Context type that contains information about the current router state.
• RouterIntegrationContext
  The wrapper type that the Router uses to interact with a History. This is automatically provided in the browser. For the server, it should be provided as a context. Be sure that it can survive conversion to a URL in the browser.
• RouterProps
  Props for the Router component.
• RoutesProps
  Props for the Routes component.
• RoutingProgressProps
  Props for the RoutingProgress component.
• ServerIntegration
  A generic router integration for the server side.
• ServerRedirectFunction
  Wrapping type for a function provided as context to allow for server-side redirects. See provide_server_redirect and Redirect.
• State
• StaticParamsMap
• StaticRouteProps
  Props for the StaticRoute component.
• Url

Enums

• FromFormDataError
• Method
  Represents an HTTP method that can be handled by this route.
• NavigationError
  An error that occurs during navigation.
• ParamsError
  Errors that can occur while parsing params using Params.
• SsrMode
  Indicates which rendering mode should be used for this route during server-side rendering.
• StaticMode
  The mode to use when rendering the route statically. On mode Upfront, the route will be built with the server is started using the provided static data. On mode Incremental, the route will be built on the first request to it and then cached and returned statically for subsequent requests.
• TrailingSlash
  Declares how you would like to handle trailing slashes in Route paths. This can be set on Router and overridden in crate::components::Route

Traits

• FromFormData
  Tries to deserialize a type from form data. This can be used for client-side validation during form submission.
• History
  The Router relies on a RouterIntegrationContext, which tells the router how to find things like the current URL, and how to navigate to a new page. The History trait can be implemented on any type to provide this information.
• IntoParam
• Params
  A simple method of deserializing key-value data (like route params or URL search) into a concrete data type. Self should typically be a struct in which each field’s type implements FromStr.
• ToHref
  Describes a value that is either a static or a reactive URL, i.e., a String, a &str, or a reactive Fn() -> String.

Functions

• A
  An HTML a progressively enhanced to use client-side routing.
• ActionForm
  Automatically turns a server Action into an HTML form progressively enhanced to use client-side routing.
• AnimatedOutlet
  Displays the child route nested in a parent route, allowing you to control exactly where that child route is displayed. Renders nothing if there is no nested child.
• AnimatedRoutes
  Contains route definitions and manages the actual routing process, with animated transitions between routes.
• Form
  An HTML form progressively enhanced to use client-side routing.
• MultiActionForm
  Automatically turns a server MultiAction into an HTML form progressively enhanced to use client-side routing.
• Outlet
  Displays the child route nested in a parent route, allowing you to control exactly where that child route is displayed. Renders nothing if there is no nested child.
• ProtectedRoute
  Describes a route that is guarded by a certain condition. This works the same way as <Route/>, except that if the condition function evaluates to false, it redirects to redirect_path instead of displaying its view.
• Redirect
  Redirects the user to a new URL, whether on the client side or on the server side. If rendered on the server, this sets a 302 status code and sets a Location header. If rendered in the browser, it uses client-side navigation to redirect. In either case, it resolves the route relative to the current route. (To use an absolute path, prefix it with /).
• Route
  Describes a portion of the nested layout of the app, specifying the route it should match, the element it should display, and data that should be loaded alongside the route.
• Router
  Provides for client-side and server-side routing. This should usually be somewhere near the root of the application.
• Routes
  Contains route definitions and manages the actual routing process.
• RoutingProgress
  A visible indicator that the router is in the process of navigating to another route.
• StaticRoute
  Describes a portion of the nested layout of the app, specifying the route it should match, the element it should display, and data that should be loaded alongside the route.
• create_location
  Creates a reactive location from the given path and state.
• create_query_signal
  Constructs a signal synchronized with a specific URL query parameter.
• escape
• generate_route_list_inner
  Generates a list of all routes this application could possibly serve. This returns the raw routes in the leptos_router format. Odds are you want generate_route_list() from either the actix or axum integrations if you want to work with their router.
• generate_route_list_inner_with_context
  Generates a list of all routes this application could possibly serve. This returns the raw routes in the leptos_router format. Odds are you want generate_route_list() from either the actix or axum integrations if you want to work with their router.
• provide_server_redirect
  Provides a function that can be used to redirect the user to another absolute path, on the server. This should set a 302 status code and an appropriate Location header.
• unescape
• use_location
  Returns the current Location, which contains reactive variables
• use_navigate
  Returns a function that can be used to navigate to a new route.
• use_params
  Returns the current route params, parsed into the given type, or an error.
• use_params_map
  Returns a raw key-value map of route params.
• use_query
  Returns the current URL search query, parsed into the given type, or an error.
• use_query_map
  Returns a raw key-value map of the URL search query.
• use_resolved_path
  Resolves the given path relative to the current route.
• use_route
  Returns the current RouteContext, containing information about the matched route.
• use_route_data
  Returns the data for the current route, which is provided by the data prop on <Route/>.
• use_router
  Returns the current RouterContext, containing information about the router’s state.

Type Aliases

• StaticData
• StaticDataFn
• StaticDataMap