Router Basics

The Blits framework comes with a built-in, performant router that eliminates the need to pull in any additional dependencies into your App.

Before we dive into the details, let's first touch base on some key concepts.

Key concepts

Pages are regular Blits Components

The router in Blits is primarily used to navigate between Pages in your App. In the context of a Blits App, a Page is just a regular Blits Component. Usually it will be a Component that fills the entire screen. But it is also possible to have only a smaller portion of the screen contain dynamic routed content.

URL hash

When navigating to a page, the hash in the URL of the browser will automatically be updated (i.e. http://localhost:8080/#my/page) to match the current page. The hash can also be used to deep-link directly into your application. Upon first load, the router functionality will evaluate the URL hash and try to match that to a defined route. If a matching route is found, it will load that page as deep linked content.

Defining Routes

Routes are defined in the main Application component, as an Array under the routes key of the configuration object.

Each route in this array, is an Object literal that includes the following key properties:

• path - the url hash to the route (i.e. /my/page)
• component - the Blits component to render for the route. This can be a direct reference, but also a promise or a dynamic import that resolves to a Blits component
• hooks (optional) - hooks such as before can be defined to execute code before navigating to the route
• options (optional) - additional options defining route behaviour, such as keepAlive and inHistory
• transitions (optional) - used to define custom transitions between pages

Dynamic routes with params

Besides static routes such as /account and /settings/wifi/advanced, the Blits router also supports dynamic routes where URI parts can contain params.

To define a param in a route path, prefix a string with a colon (:), followed by the name of the param, e.g. /movies/:genre/:id. This route path will match a URI hash such as #/movies/sci-fi/65281918. The router will take the params and inject them as a prop into the Page that's being navigated to.

To access these props in the Page component, they must first be defined in the Page component as props first (i.e. props: ['genre', 'id']). Once defined, the values (sci-fi and 65281918) in this case, will be available on the this scope as this.genre and this.id (or as $genre and $id when used in the template), as with any regular Component.

Using query parameters in routes

According to the browser specifications, query parameters are not part of a URL hash. This means that query parameters should be placed before the URL hash (i.e. http://localhost:5173?id=100&name=john#/my/page/hash) and implies that "real" query parameters are not part of the route paths.

In this case id and name won't automatically be made available as props inside a Blits component. They can however be retrieved using document.location.search in combination with new URLSearchParams, and can be used in an App's index.js to set dynamic launch settings for example.

Sometimes you may actually want pass custom data into a Blits component, without it being part of the dynamic route path or data-object during navigation. For these cases Blits allows you to use query parameters as part of a route (i.e. #/series/simpsons/5/10?id=100&name=john).

This URL hash will match the route /series/:show/:season/:episode and it will pass id and name as additional props into the Page component. Note: similar to dynamic path params, route query params should also be be defined in the Page component as props first (i.e. props: ['id', 'name']) in order to be accessed on the this-scope.

Router view

The routes are loaded into a <RouterView /> component, which acts as a placeholder for the routed Page components.

The <RouterView /> component can be positioned and sized as you would expect from a normal Blits Component.

export default Blits.Application({
  template: `
    <Element>
      <RouterView x="300" y="200" w="1520" h="680" />
    </Element>
  `,
  routes: [
      { path: '/', component: Home },
      { path: '/details', component: () => import('./pages/Details.js'), },
      { path: '/account',
        component: () => {
          // imagine this is an API call or some other async action
          return new Promise((resolve) => {
            resolve(Account)
          })
        }
      }
  ],
  // ...
})

Navigation

Each component in a routed Blits app has a this.$router object that provides access to the Router instance. It can be used to programmatically navigate to pages, by calling the to() method on it.

The this.$router.to()-methods accepts 3 arguments:

• path - the path of the route to navigate to
• data (optional) - an object with data to pass into the page as props
• options (optional) - additional options defining route behaviour, such as keepAlive and inHistory (these will overwrite any options specified for a route in the routes array)

export default Blits.Component('Poster', {
  input: {
    enter() {
      this.$router.to('/movie/details', {id: '1', img: 'details.png'}, {inHistory: false})
    }
  }
})

Whenever you navigate to a new page, the URL hash will automatically be updated. Unless specified otherwise, navigating to a new page, will add that route to the history stack. The back input action is automatically wired up to navigate back down the history stack.

Router API

The Router API provides several useful methods and properties for managing routes and navigation:

• this.$router.to() - navigating to a different location (as discussed above)
• this.$router.back() - programmatically navigate back down the history stack
• this.$router.currentRoute - retrieve the current route
• this.$router.routes - retrieve the list of all routes
• this.$router.navigating - retrieve the current navigating state