Skip to main content

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 and users/: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 in your app

View all routes in your app

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.