Usage
Note
The sections below assume you already know the basics of ReacPy.
Here you'll learn the various features of reactpy-router
and how to use them. All examples
will utilize the simple.router (though you can use your own).
Routers and Routes
The simple.router component is one possible
implementation of a Router. Routers takes a series of
Route objects as positional arguments and render whatever
element matches the current location. For convenience, these Route
objects are created
using the route function.
Note
The current location is determined based on the browser's current URL and can be found by checking the use_location hook.
Here's a basic example showing how to use simple.router
with two routes:
from reactpy import component, html, run
from reactpy_router import route, simple, use_location
@component
def root():
location = use_location()
return simple.router(
route("/", html.h1("Home Page 🏠")),
route("*", html.h1("Missing Link 🔗💥")),
)
Here we'll note some special syntax in the route path for the second route. The *
is a
wildcard that will match any path. This is useful for creating a "404" page that will be
shown when no other route matches.
Simple Router
The syntax for declaring routes with the simple.router is very similar to the syntax used by Starlette (a popular Python web framework). As such route parameters are declared using the following syntax:
/my/route/{param}
/my/route/{param:type}
In this case, param
is the name of the route parameter and the optionally declared
type
specifies what kind of parameter it is. The available parameter types and what
patterns they match are are:
- str (default) -
[^/]+
- int -
\d+
- float -
\d+(\.\d+)?
- uuid -
[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}
- path -
.+
Note
The path
type is special in that it will match any path, including /
characters.
This is useful for creating routes that match a path prefix.
So in practice these each might look like:
/my/route/{param}
/my/route/{param:int}
/my/route/{param:float}
/my/route/{param:uuid}
/my/route/{param:path}
Any route parameters collected from the current location then be accessed using the
use_params
hook.
Note
It's worth pointing out that, while you can use route parameters to capture values
from queryies (i.e. ?foo=bar
), this is not recommended. Instead, you should use
the use_query hook to access query parameters.
Route Links
Links between routes should be created using the link component. This will allow ReactPy to handle the transition between routes more quickly by avoiding the cost of a full page load.
from reactpy import component, html, run, use_location
from reactpy_router import link, route, simple
@component
def root():
use_location()
return simple.router(
route(
"/",
html.div(
html.h1("Home Page 🏠"),
link(html.button("About"), to="/about"),
),
),
route("/about", html.h1("About Page 📖")),
)
Hooks
reactpy-router
provides a number of hooks for working with the routes:
use_query
- for accessing query parametersuse_params
- for accessing route parameters
If you're not familiar with hooks, you should read the docs.
Using Queries
The use_query hook can be used to access query parameters from the current location. It returns a dictionary of query parameters, where each value is a list of strings.
from reactpy import component, html, run
from reactpy_router import link, route, simple, use_query
@component
def root():
use_location()
return simple.router(
route(
"/",
html.div(
html.h1("Home Page 🏠"),
link("Search", to="/search?q=reactpy"),
),
),
route("/about", html.h1("About Page 📖")),
)
@component
def search():
query = use_query()
return html.h1(f"Search Results for {query['q'][0]} 🔍")
Using Parameters
The use_params hook can be used to access route parameters from the current location. It returns a dictionary of route parameters, where each value is mapped to a value that matches the type specified in the route path.
from reactpy import component, html, run
from reactpy_router import link, route, simple, use_params
@component
def root():
return simple.router(
route(
"/",
html.div(
html.h1("Home Page 🏠"),
link("User 123", to="/user/123"),
),
),
route("/user/{id:int}", user()),
)
@component
def user():
params = use_params()
return html.h1(f"User {params['id']} 👤")