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 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 one or more parts of the route are dynamic and expected to change. For example, when building a User Detail page, the same page is rendered for each user, but the data on the page changes based on the user being viewed.

To do this, you can 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, simply type a colon after a slash ("/:") to specify a dynamic route segment that maps to a route parameter.

In the User Detail example, the route /users/:userId includes userId as a route parameter. This means the URL must contain a specific User ID to load the route. For example, both /users/123 and /users/456 would correspond to this route.

Accessing route parameter values​

To utilize the data passed via the route parameters, use Global.URL.routeParams.

The routeParams object is keyed by the parameter ID. For instance, in the example above, the User ID passed in the URL can be accessed with Global.URL.routeParams.userId.

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 utilize dynamic routes for resource-specific pages. Using a dynamic route is preferable to passing data using query parameters when the page strictly depends on the presence of that data. This is typically the case for resource-specific pages.

In the User Details example, relying on query parameters for userId is not ideal because the User Detail page should not be displayed if the user is not specified. Dynamic routes ensure that the page can only be loaded if the necessary data is present. This is often desirable when the page is intended for a specific resource, such as a user or transaction.

For storing optional data in the URL, query parameters can be used.

Handling the root route​

Most web applications have their root or home page at the / route. For example, visiting ChatGPT is done via https://chatgpt.com/.

We recommend that applications in Superblocks follow this convention, mapping the / route to the main entry point of your application. By default, this route is mapped to the initial page of your app.

To move this route to another page, delete it from the current page and recreate it on the desired page. Additionally, you can add mutliple routes to the home page of an application; for instance, both / and /home can serve 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.
  • Choose descriptive names for route parameters.
  • Maintain consistent route segments for related pages (i.e. /users and users/:userId for a Users and UserDetail page).
  • Use route parameters for 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​

For an overview of all routes in your application, click the three dots next to the pin icon in the Navigation pane, then select View all routes

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.