Routes
A Route defines the URL that maps to a page in your application. Each page in a Superblocks application has at least one route.
A route is composed of one or more "route segments", which are the parts between the slashes in the route.
Static routes
A static route is a route that is entirely known ahead of time. Static routes are suitable when the content on the page is mostly fixed.
For example, /transactions
, /home
, or /users/settings
are all static routes as they would typically point to pages with mostly fixed content. A static route can have many segments, but each segment must be static for the route to be static.
Dynamic routes
A dynamic route is a route where a part or parts of the route are dynamic and expected to change.
For example, imagine you are building a User Detail page. You want to render the same page for each user, but want the data on the page to change based on which user you are viewing.
To do so, you would want to use a dynamic route which takes a userId
as a route parameter.
Defining route parameters
To define a route parameter and make your route dynamic, you simply type a colon after a slash ("/:") to indicate you are specifying a dynamic route segment which maps to a route parameter.
In this example, your route would be /users/:userId
. Now, userId
would be a route parameter, which means in order to load this route, the URL must contain a specific User ID. For example, both /users/123
and /users/456
would correspond to this route.
Accessing route parameter values
To actually make use of the data passed via the route parameter(s), you will use Global.URL.routeParams
.
The routeParams
object is keyed by the parameter ID, so in the example above, I would type Global.URL.routeParams.userId
to access the User ID passed in the URL.
When to use dynamic routes
It is best practice to use a dynamic route when the page depends on external data or parameters.
Most web applications use dynamic routes for any resource-specific page. Using a dynamic route is preferable to passing data using query parameters when the page strictly depends on the presence of that data, which is typically the case for resource-specific pages.
Going back to the example above, I would not want to rely on query parameters for my userId
because I don't want my User Detail page to ever be displayed if the user is not specified.
Using dynamic routes ensures that the page can only be loaded if the necessary data is present, which is often desirable when the page is intended for a specific resource, such as a user or transaction.
If you want to store some optional data in the URL, you can always use query parameters.
Handling the root route
Most web applications have their root or home page at the /
route. For example, when I visit ChatGPT, the URL is https://chatgpt.com/
.
We recommend that applications in Superblocks follow this convention, such the /
route is mapped to the main entry point of your application. By default, this route is mapped to the initial page of your app.
If you wish to move this route to another page, you can delete it from one page and recreate it on the other page. You can also add additional routes to your home page - for example, you may want both /
and /home
as routes for the root page of your application.
Route best practices
We recommend the following conventions when defining routes:
- Keep route strings lowercase
- Use dashes ("-") between words
- Use camelCase for route parameters
- Use descriptive names for route parameters
- Use consistent route segments for related pages (i.e.
/users
andusers/:userId
for a Users and UserDetail page) - Use route parameters for any required data, such as the ID of a resource on a resource-specific page
- Do not delete the slash (
/
) route from your application
For example, a route that follows these conventions would be /payment-methods/:methodType
.
View all routes
You can view an overview of all routes in your application by clicking the Route icon in the Navigation above your pages.
![View all routes View all routes in your app](/assets/images/view-all-routes-6aa6c38363cf0e63cc27f3259d42496a.png)
![View all routes View all routes in your app](/assets/images/routes-modal-a9da50a6a1dd6ca901d222c86f870193.png)
This feature is useful as a reference for the architecture of your application, as well as for new developers starting to build in an existing app.