mirror of
https://github.com/yewstack/yew.git
synced 2025-12-08 21:26:25 +00:00
90b4e55ebc
* change suffixes from md to mdx fix broken links for English locale tree shake and update docusaurus add docusaurus ideal image plugin use svg and themed image delete unused static asset * move localized landing page * change GitLocalize project page * nit pick * remove ignore to have the block checked
497 lines
16 KiB
Plaintext
497 lines
16 KiB
Plaintext
---
|
|
title: "Router"
|
|
description: "Yew's official router"
|
|
---
|
|
|
|
Routers in Single Page Applications (SPA) handle displaying different pages depending on what the URL is. Instead of the
|
|
default behavior of requesting a different remote resource when a link is clicked, the router instead sets the URL
|
|
locally to point to a valid route in your application. The router then detects this change and then decides what to
|
|
render.
|
|
|
|
Yew provides router support in the `yew-router` crate. To start using it, add the dependency to your `Cargo.toml`
|
|
|
|
<!-- Reminder: fix this when we release a new version of yew -->
|
|
|
|
```toml
|
|
yew-router = { git = "https://github.com/yewstack/yew.git" }
|
|
```
|
|
|
|
The utilities needed are provided under `yew_router::prelude`,
|
|
|
|
## Usage
|
|
|
|
You start by defining a `Route`.
|
|
|
|
Routes are defined as an `enum` which derives `Routable`. This enum must be `Clone + PartialEq`.
|
|
|
|
```rust
|
|
use yew_router::prelude::*;
|
|
|
|
#[derive(Clone, Routable, PartialEq)]
|
|
enum Route {
|
|
#[at("/")]
|
|
Home,
|
|
#[at("/secure")]
|
|
Secure,
|
|
#[not_found]
|
|
#[at("/404")]
|
|
NotFound,
|
|
}
|
|
```
|
|
|
|
A `Route` is paired with a `<Switch />` component, which finds the variant whose path matches the browser's
|
|
current URL and passes it to the `render` callback. The callback then decides what to render. In case no path is
|
|
matched, the router navigates to the path with `not_found` attribute. If no route is specified, nothing is rendered, and
|
|
a message is logged to console stating that no route was matched.
|
|
|
|
Finally, you need to register one of the Router context provider components like `<BrowserRouter />`.
|
|
It provides location information and navigator to its children.
|
|
|
|
:::caution
|
|
When using `yew-router` in browser environment, `<BrowserRouter />` is highly recommended.
|
|
You can find other router flavours in the [API Reference](https://docs.rs/yew-router/).
|
|
:::
|
|
|
|
```rust
|
|
use yew_router::prelude::*;
|
|
use yew::prelude::*;
|
|
|
|
#[derive(Clone, Routable, PartialEq)]
|
|
enum Route {
|
|
#[at("/")]
|
|
Home,
|
|
#[at("/secure")]
|
|
Secure,
|
|
#[not_found]
|
|
#[at("/404")]
|
|
NotFound,
|
|
}
|
|
|
|
#[function_component(Secure)]
|
|
fn secure() -> Html {
|
|
let navigator = use_navigator().unwrap();
|
|
|
|
let onclick = Callback::once(move |_| navigator.push(Route::Home));
|
|
html! {
|
|
<div>
|
|
<h1>{ "Secure" }</h1>
|
|
<button {onclick}>{ "Go Home" }</button>
|
|
</div>
|
|
}
|
|
}
|
|
|
|
fn switch(routes: &Route) -> Html {
|
|
match routes {
|
|
Route::Home => html! { <h1>{ "Home" }</h1> },
|
|
Route::Secure => html! {
|
|
<Secure />
|
|
},
|
|
Route::NotFound => html! { <h1>{ "404" }</h1> },
|
|
}
|
|
}
|
|
|
|
#[function_component(Main)]
|
|
fn app() -> Html {
|
|
html! {
|
|
<BrowserRouter>
|
|
<Switch<Route> render={Switch::render(switch)} />
|
|
</BrowserRouter>
|
|
}
|
|
}
|
|
```
|
|
|
|
### Path Segments
|
|
|
|
It is also possible to extract information from a route.
|
|
You can then access the post's id inside `<Switch />` and forward it to the appropriate component via properties.
|
|
|
|
```rust
|
|
use yew::prelude::*;
|
|
use yew_router::prelude::*;
|
|
|
|
#[derive(Clone, Routable, PartialEq)]
|
|
enum Route {
|
|
#[at("/")]
|
|
Home,
|
|
#[at("/post/:id")]
|
|
Post { id: String },
|
|
}
|
|
|
|
fn switch(route: &Route) -> Html {
|
|
match route {
|
|
Route::Home => html! { <h1>{ "Home" }</h1> },
|
|
Route::Post { id } => html! {<p>{format!("You are looking at Post {}", id)}</p>},
|
|
}
|
|
}
|
|
```
|
|
|
|
:::note
|
|
You can have a normal `Post` variant instead of `Post {id: String}` too. For example when `Post` is rendered
|
|
with another router, the field can then be redundant as the other router is able to match and handle the path. See the
|
|
[Nested Router](#nested-router) section below for details
|
|
:::
|
|
|
|
Note the fields must implement `Clone + PartialEq` as part of the `Route` enum. They must also implement
|
|
`std::fmt::Display` and `std::str::FromStr` for serialization and deserialization. Primitive types like integer, float,
|
|
and String already satisfy the requirements.
|
|
|
|
In case when the form of the path matches, but the deserialization fails (as per `FromStr`). The router will consider
|
|
the route as unmatched and try to render the not found route (or a blank page if the not found route is unspecified).
|
|
|
|
Consider this example:
|
|
|
|
```rust ,ignore
|
|
#[derive(Clone, Routable, PartialEq)]
|
|
enum Route {
|
|
#[at("/news/:id")]
|
|
News { id: u8 },
|
|
#[not_found]
|
|
#[at("/404")]
|
|
NotFound,
|
|
}
|
|
// switch function renders News and id as is. Omitted here.
|
|
```
|
|
|
|
When the segment goes over 255, `u8::from_str()` fails with `ParseIntError`, the router will then consider the route
|
|
unmatched.
|
|
|
|
|
|
|
|
For more information about the route syntax and how to bind parameters, check
|
|
out [route-recognizer](https://docs.rs/route-recognizer/0.3.1/route_recognizer/#routing-params).
|
|
|
|
### Location
|
|
|
|
The router provides a universal `Location` struct via context which can be used to access routing information.
|
|
They can be retrieved by hooks or convenient functions on `ctx.link()`.
|
|
|
|
### Navigation
|
|
|
|
`yew_router` provides a handful of tools to work with navigation.
|
|
|
|
#### Link
|
|
|
|
A `<Link />` renders as an `<a>` element, the `onclick` event handler will call
|
|
[preventDefault](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault), and push the targeted page to the
|
|
history and render the desired page, which is what should be expected from a Single Page App. The default onclick of a
|
|
normal anchor element would reload the page.
|
|
|
|
The `<Link />` component also passes its children to the `<a>` element. Consider it a replacement of `<a/>` for in-app
|
|
routes. Except you supply a `to` attribute instead of a `href`. An example usage:
|
|
|
|
```rust ,ignore
|
|
<Link<Route> to={Route::Home}>{ "click here to go home" }</Link<Route>>
|
|
```
|
|
|
|
Struct variants work as expected too:
|
|
|
|
```rust ,ignore
|
|
<Link<Route> to={Route::Post { id: "new-yew-release".to_string() }}>{ "Yew v0.19 out now!" }</Link<Route>>
|
|
```
|
|
|
|
#### Navigator API
|
|
|
|
Navigator API is provided for both function components and struct components. They enable callbacks to change the
|
|
route. An `Navigator` instance can be obtained in either cases to manipulate the route.
|
|
|
|
##### Function Components
|
|
|
|
For function components, the `use_navigator` hook re-renders the component when the underlying navigator provider changes.
|
|
Here's how to implement a button that navigates to the `Home` route when clicked.
|
|
|
|
```rust ,ignore
|
|
#[function_component(MyComponent)]
|
|
pub fn my_component() -> Html {
|
|
let navigator = use_navigator().unwrap();
|
|
let onclick = Callback::once(move |_| navigator.push(Route::Home));
|
|
|
|
html! {
|
|
<>
|
|
<button {onclick}>{"Click to go home"}</button>
|
|
</>
|
|
}
|
|
}
|
|
```
|
|
|
|
:::caution
|
|
The example here uses `Callback::once`. Use a normal callback if the target route can be the same with the route
|
|
the component is in, or just to play safe. For example, when you have a logo button on every page, that goes back to
|
|
home when clicked, clicking that button twice on home page causes the code to panic because the second click pushes an
|
|
identical Home route and the `use_navigator` hook won't trigger a re-render.
|
|
:::
|
|
|
|
If you want to replace the current location instead of pushing a new location onto the stack, use `navigator.replace()`
|
|
instead of `navigator.push()`.
|
|
|
|
You may notice `navigator` has to move into the callback, so it can't be used again for other callbacks. Luckily `navigator`
|
|
implements `Clone`, here's for example how to have multiple buttons to different routes:
|
|
|
|
```rust ,ignore
|
|
use yew::prelude::*;
|
|
use yew_router::prelude::*;
|
|
|
|
#[function_component(NavItems)]
|
|
pub fn nav_items() -> Html {
|
|
let navigator = use_navigator().unwrap();
|
|
|
|
let go_home_button = {
|
|
let navigator = navigator.clone();
|
|
let onclick = Callback::once(move |_| navigator.push(Route::Home));
|
|
html! {
|
|
<button {onclick}>{"click to go home"}</button>
|
|
}
|
|
};
|
|
|
|
let go_to_first_post_button = {
|
|
let navigator = navigator.clone();
|
|
let onclick = Callback::once(move |_| navigator.push(Route::Post { id: "first-post".to_string() }));
|
|
html! {
|
|
<button {onclick}>{"click to go the first post"}</button>
|
|
}
|
|
};
|
|
|
|
let go_to_secure_button = {
|
|
let onclick = Callback::once(move |_| navigator.push(Route::Secure));
|
|
html! {
|
|
<button {onclick}>{"click to go to secure"}</button>
|
|
}
|
|
};
|
|
|
|
html! {
|
|
<>
|
|
{go_home_button}
|
|
{go_to_first_post_button}
|
|
{go_to_secure_button}
|
|
</>
|
|
}
|
|
}
|
|
```
|
|
|
|
##### Struct Components
|
|
|
|
For struct components, the `Navigator` instance can be obtained through the `ctx.link().navigator()` API. The rest is
|
|
identical with the function component case. Here's an example of a view function that renders a single button.
|
|
|
|
```rust ,ignore
|
|
fn view(&self, ctx: &Context<Self>) -> Html {
|
|
let navigator = ctx.link().navigator().unwrap();
|
|
let onclick = Callback::once(move |_| navigator.push(MainRoute::Home));
|
|
html!{
|
|
<button {onclick}>{"Go Home"}</button>
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Redirect
|
|
|
|
`yew-router` also provides a `<Redirect />` component in the prelude. It can be used to achieve similar effects as the
|
|
navigator API. The component accepts a
|
|
`to` attribute as the target route. When a `<Redirect/>` is rendered users will be redirect to the route specified in props.
|
|
Here is an example:
|
|
|
|
```rust ,ignore
|
|
#[function_component(SomePage)]
|
|
fn some_page() -> Html {
|
|
// made-up hook `use_user`
|
|
let user = match use_user() {
|
|
Some(user) => user,
|
|
// Redirects to the login page when user is `None`.
|
|
None => return html! {
|
|
<Redirect<Route> to={Route::Login}/>
|
|
},
|
|
};
|
|
// ... actual page content.
|
|
}
|
|
```
|
|
|
|
:::tip `Redirect` vs `Navigator`, which to use
|
|
The Navigator API is the only way to manipulate route in callbacks.
|
|
While `<Redirect />` can be used as return values in a component. You might also want to use `<Redirect />` in other
|
|
non-component context, for example in the switch function of a [Nested Router](#nested-router).
|
|
:::
|
|
|
|
### Listening to Changes
|
|
|
|
#### Function Components
|
|
|
|
You can use `use_location` and `use_route` hooks. Your components will re-render when
|
|
provided values change.
|
|
|
|
#### Struct Components
|
|
|
|
In order to react on route changes, you can pass a callback closure to the `add_location_listener()` method of `ctx.link()`.
|
|
|
|
:::note
|
|
The location listener will get unregistered once it is dropped. Make sure to store the handle inside your
|
|
component state.
|
|
:::
|
|
|
|
```rust ,ignore
|
|
fn create(ctx: &Context<Self>) -> Self {
|
|
let listener = ctx.link()
|
|
.add_location_listener(ctx.link().callback(
|
|
// handle event
|
|
))
|
|
.unwrap();
|
|
MyComponent {
|
|
_listener: listener
|
|
}
|
|
}
|
|
```
|
|
|
|
`ctx.link().location()` and `ctx.link().route::<R>()` can also be used to retrieve the location and the route once.
|
|
|
|
### Query Parameters
|
|
|
|
#### Specifying query parameters when navigating
|
|
|
|
In order to specify query parameters when navigating to a new route, use either `navigator.push_with_query` or
|
|
the `navigator.replace_with_query` functions. It uses `serde` to serialize the parameters into query string for the URL so
|
|
any type that implements `Serialize` can be passed. In its simplest form this is just a `HashMap` containing string
|
|
pairs.
|
|
|
|
#### Obtaining query parameters for current route
|
|
|
|
`location.query` is used to obtain the query parameters. It uses `serde` to deserialize the parameters from query string
|
|
in the URL.
|
|
|
|
## Nested Router
|
|
|
|
Nested router can be useful when the app grows larger. Consider the following router structure:
|
|
|
|
<!--
|
|
The graph is produced with the following code, with graphviz.
|
|
To reproduce. Save the code in a file, say `input.dot`,
|
|
And run `$ dot -Tsvg input.dot -o nested-router.svg`
|
|
|
|
digraph {
|
|
bgcolor=transparent
|
|
node [shape=box style="filled, rounded" fillcolor=white]
|
|
Home; News; Contact; "Not Found"; Profile; Friends; Theme; SettingsNotFound [label="Not Found"];
|
|
|
|
node [fillcolor=lightblue style="filled, rounded"]
|
|
"Main Router"; "Settings Router";
|
|
|
|
"Main Router" -> {Home News Contact "Not Found" "Settings Router"} [arrowhead=none]
|
|
"Settings Router" -> {SettingsNotFound Profile Friends Theme } [arrowhead=none]
|
|
SettingsNotFound -> "Not Found" [constraint=false]
|
|
}
|
|
-->
|
|
|
|
<!--
|
|
Also the dark themed version:
|
|
digraph {
|
|
bgcolor=transparent
|
|
node [shape=box style="filled, rounded" fillcolor=grey color=white fontcolor=white]
|
|
Home; News; Contact; "Not Found"; Profile; Friends; Theme; SettingsNotFound [label="Not Found"];
|
|
|
|
node [fillcolor=lightblue style="filled, rounded" color=white fontcolor=black]
|
|
"Main Router"; "Settings Router";
|
|
|
|
"Main Router" -> {Home News Contact "Not Found" "Settings Router"} [arrowhead=none color=white]
|
|
"Settings Router" -> {SettingsNotFound Profile Friends Theme } [arrowhead=none color=white]
|
|
SettingsNotFound -> "Not Found" [constraint=false color=white]
|
|
}
|
|
-->
|
|
|
|
import useBaseUrl from "@docusaurus/useBaseUrl";
|
|
import ThemedImage from '@theme/ThemedImage';
|
|
|
|
<ThemedImage
|
|
alt="nested router structure"
|
|
sources={{
|
|
light: useBaseUrl('/img/nested-router-light.svg'),
|
|
dark: useBaseUrl('/img/nested-router-dark.svg'),
|
|
}}
|
|
/>
|
|
|
|
The nested `SettingsRouter` handles all urls that start with `/settings`. Additionally, it redirects urls that are not
|
|
matched to the main `NotFound` route. So `/settings/gibberish` will redirect to `/404`.
|
|
|
|
It can be implemented with the following code:
|
|
|
|
```rust
|
|
use yew::prelude::*;
|
|
use yew_router::prelude::*;
|
|
|
|
#[derive(Clone, Routable, PartialEq)]
|
|
enum MainRoute {
|
|
#[at("/")]
|
|
Home,
|
|
#[at("/news")]
|
|
News,
|
|
#[at("/contact")]
|
|
Contact,
|
|
#[at("/settings/:s")]
|
|
Settings,
|
|
#[not_found]
|
|
#[at("/404")]
|
|
NotFound,
|
|
}
|
|
|
|
#[derive(Clone, Routable, PartialEq)]
|
|
enum SettingsRoute {
|
|
#[at("/settings/profile")]
|
|
Profile,
|
|
#[at("/settings/friends")]
|
|
Friends,
|
|
#[at("/settings/theme")]
|
|
Theme,
|
|
#[not_found]
|
|
#[at("/settings/404")]
|
|
NotFound,
|
|
}
|
|
|
|
fn switch_main(route: &MainRoute) -> Html {
|
|
match route {
|
|
MainRoute::Home => html! {<h1>{"Home"}</h1>},
|
|
MainRoute::News => html! {<h1>{"News"}</h1>},
|
|
MainRoute::Contact => html! {<h1>{"Contact"}</h1>},
|
|
MainRoute::Settings => html! {
|
|
<Switch<SettingsRoute> render={Switch::render(switch_settings)} />
|
|
},
|
|
MainRoute::NotFound => html! {<h1>{"Not Found"}</h1>},
|
|
}
|
|
}
|
|
|
|
fn switch_settings(route: &SettingsRoute) -> Html {
|
|
match route {
|
|
SettingsRoute::Profile => html! {<h1>{"Profile"}</h1>},
|
|
SettingsRoute::Friends => html! {<h1>{"Friends"}</h1>},
|
|
SettingsRoute::Theme => html! {<h1>{"Theme"}</h1>},
|
|
SettingsRoute::NotFound => html! {
|
|
<Redirect<MainRoute> to={MainRoute::NotFound}/>
|
|
}
|
|
}
|
|
}
|
|
|
|
#[function_component(App)]
|
|
pub fn app() -> Html {
|
|
html! {
|
|
<BrowserRouter>
|
|
<Switch<MainRoute> render={Switch::render(switch_main)} />
|
|
</BrowserRouter>
|
|
}
|
|
}
|
|
```
|
|
|
|
### Basename
|
|
|
|
It's possible to define a basename with `yew-router`.
|
|
A basename is a common prefix of all routes. Both the Navigator API and
|
|
`<Switch />` component respect basename setting. All pushed routes will be
|
|
prefixed with the basename and all switches will strip the basename before
|
|
trying to parse the path into a `Routable`.
|
|
|
|
If a basename prop is not supplied to the Router component, it will use
|
|
the href attribute of the `<base />` element in your html file and
|
|
fallback to `/` if no `<base />` presents in the html file.
|
|
|
|
## Relevant examples
|
|
|
|
- [Router](https://github.com/yewstack/yew/tree/master/examples/router)
|
|
|
|
## API Reference
|
|
|
|
- [yew-router](https://docs.rs/yew-router/)
|