Router Containers

In order to use a router in an application, it must be attached to the DOM with a router container. Router containers are provided by the lwr-router-container component.

A router container provides navigation context. This means that the router container is responsible for processing all navigation wires and events from its descendants in the DOM. In the following example, those descendants are my-nav and lwr-outlet.

<template>
    <lwr-router-container
        router={router}
        onhandlenavigation={handleNavigation}
        onprenavigate={preNavigate}
        onpostnavigate={postNavigate}
        onerrornavigate={errorNavigate}>
        <my-nav></my-nav>
        <lwr-outlet></lwr-outlet>
    </lwr-router-container>
</template>

import { LightningElement } from "lwc";
import { createRouter } from "lwr/router";
import { ROUTE_DEFINITIONS } from "./routeDefinitions";

export default class MyApp extends LightningElement {
  router = createRouter({ routes: ROUTE_DEFINITIONS });
  approvedCategories = ["apps", "entrees", "sides", "desserts"];

  handleNavigation(e: CustomEvent): void {
    console.log("navigate() called with page reference:", e.detail);
  }

  preNavigate(e: CustomEvent): void {
    const {
      next: {
        route: { pageReference },
      },
    } = e.detail;
    const {
      attributes: { cat },
    } = pageReference;
    console.log("navigation event incoming with page reference:", pageReference);
    if (!this.approvedCategories.includes(cat)) {
      // REJECT unapproved recipe categories
      e.preventDefault();
    }
  }

  postNavigate(e: CustomEvent): void {
    const {
      route: { pageReference },
    } = e.detail;
    console.log("navigated to page reference:", pageReference);
  }

  errorNavigate(e: CustomEvent): void {
    const { code, message } = e.detail;
    console.error(`navigation error -> ${code}: ${message}`);
  }
}

Router Container Events

A router container requires a router, and it fires these events:

onhandlenavigation

• Dispatched when navigate(pageRef) is called.
• event.preventDefault() cancels the navigation event.
• event.detail is the PageReference.

onprenavigate

• Dispatched when a navigation event is received and a RouteDefinition match is found.

• event.preventDefault() cancels the navigation event.

• event.detail is a RouteChange().

interface RouteChange { current?: DomRoutingMatch; // the current location info next: DomRoutingMatch; // location info for the incoming nav event }

`onpostnavigate`

- Dispatched when a navigation event has completed.
- `event.detail` is a `DomRoutingMatch` for the current location.

interface DomRoutingMatch { url: string; // e.g. "/recipes/desserts/010?units=metric&yummy=yes" route: RouteInstance; routeDefinition: RouteDefinition; }

`onerrornavigate`

- Dispatched when there is an error processing a navigation event. (For example, no `RouteDefinition` match or `prenavigate` cancelation.)
- `event.detail` is a `MessageObject`.

interface MessageObject { code: string | number; message: string; level: number; // Fatal = 0, Error = 1, Warning = 2, Log = 3 }

## Next Steps

[Simple Client-Side Routing: Create a Router](./lwr-routing-example-simple.md#create-a-router) demonstrates how to attach a router instance to a router container.