Vaadin Router

The RouterLocation object describes the state of the router at a specific point in time. It is provided to view Web Components via lifecycle callbacks, as a property on the component itself, and via router.location.

Key properties:

• pathname: The current path (e.g., /users/42). Always starts with /.
• params: An IndexedParams object containing named and unnamed URL parameters.
• search: The query string portion of the URL.
• searchParams: A URLSearchParams object for the query string.
• hash: The fragment identifier (including #).
• baseUrl: The base URL used by the router.
• redirectFrom: The original pathname if the current location is the result of a redirect.
• route: The Route object associated with this location (undefined in router.location or global events).
• routes: A list of matching Route objects (the hierarchy from parent layouts to the view).
• getUrl(params?: Params): A method to generate a URL for the current route, optionally overriding parameters.

Vaadin Router traverses a routes tree from the root down to the leaves to match a given pathname. The matching process consumes parts of the pathname as it moves through parent routes to find matching child routes.

Path Syntax Rules

• Leading Slashes (/):
  • For the root of the routes tree, a leading / matters.
  • For all other child routes, a leading / has no significance.
• Trailing Slashes (/):
  • Leaf Routes: A trailing / in a leaf route path matches only if the pathname also has a trailing /.
  • Child Routes: A trailing / in a route path does not affect how its children are matched.
  • Pathnames: Trailing slashes in the pathname generally do not affect matching, except when matching leaf nodes.
• Special Routes ("" and /):
  • As a single route: "" matches only "" pathnames; / matches only / pathnames.
  • As a parent: "" matches any pathname without consuming any part of it; / matches any absolute pathname by consuming its leading /.
  • As a leaf: Both "" and / match only if the entire pathname has been consumed by the parent chain.
  • Squashing: Directly nested "" or / routes are 'squashed', meaning nesting two / routes does not require a double // in the pathname.

Matching Behavior

The matching process returns a lazily evaluated iterator. This allows for traversing the matches found in the tree. If a route has children: true (or has a children array), prefix matching is enabled.

Side Effect Note: A routes tree defined as { path: '' } matches only the '' pathname. However, a tree defined as { path: '', children: [ { path: '' } ] } will match any pathname because the root matches the empty string without consuming anything.

An action function is the most powerful way to control route resolution. It is called before the route is resolved and can return several types of results to influence the outcome:

• Return an HTMLElement: The route is resolved to this specific element.
• Return commands.component(name): The route is resolved to the specified Web Component.
• Return commands.redirect(path): The current navigation is aborted and a redirect to the new path is initiated.
• Return context.next(): Asynchronously requests the next route in the resolution chain.
• Return prevent(): Cancels the navigation entirely.

Important: If you use an arrow function for action, you will not have access to the route object via this. Use a standard function if you need to access the route object.

// Example of an action using commands
{
  path: '/admin',
  action(function(context, commands) {
    const isAdmin = checkAuth(); // your logic
    if (!isAdmin) {
      return commands.redirect('/login');
    }
    // If we return nothing, it proceeds to use the 'component' property
  }),
  component: 'admin-view'
}

Vaadin Router automatically calls specific methods on your view Web Components during the navigation lifecycle. You do not need to extend a specific class; simply defining these methods is sufficient. Methods can be synchronous or return a Promise.

Navigation Guarding and Redirecting

Use these methods to intercept navigation, prevent it, or redirect the user:

• onBeforeEnter(location, commands, router): Called before the outlet is updated.
  • Return commands.prevent() (or a Promise resolving to it) to abort navigation.
  • Return commands.redirect(path) (or a Promise resolving to it) to start a new navigation cycle to the new path.
• onBeforeLeave(location, commands, router): Called when navigating away from the component.
  • Return commands.prevent() to abort the navigation.

Post-Navigation Hooks

Use these methods for setup or cleanup after the DOM has been updated:

• onAfterEnter(location, commands, router): Called asynchronously after connectedCallback() once the outlet has been updated with the new element.
• onAfterLeave(location, commands, router): Called when the component is being removed from the DOM. Note that this method cannot prevent navigation; the component is already being resolved for removal.

class MyView extends HTMLElement {
  async onBeforeEnter(location, commands, router) {
    const isAuthorized = await checkAuth();
    if (!isAuthorized) {
      return commands.redirect('/login');
    }
  }

  onAfterEnter(location, commands, router) {
    console.log('View entered:', location.pathname);
  }
}